for advanced users¶

Follow the two first steps in the previous paragraph.

To install dhcpcanon and the systemd service:

sudo make install WITH_SYSTEMD=true

In Debian this will install all the required files under /usr/local. WITH_SYSTEMD will install a systemd service and enable it, to run it:

systemctl start dhcpcanon

It’s possible to also install support for udev:

sudo apt install sudo make install WITH_SYSTEMD=true
sudo make install WITH_SYSTEMD=true WITH_SYSTEMD_UDEV=true

And apparmor profile:

sudo apt install apparmor
sudo make install WITH_APPARMOR=true

In the case that you would like to install without root privileges, you can install it without the systemd service and you can specify an alternative location, for instance:

make --prefix=/home/user/.local install

Note however that without systemd dhcpcanon will need to be run with root privileges, while the systemd service drop dhcpcanon root privileges and only keeps the required network capabilities.

You would also need to install resolvconf-admin to be able to run it as non root user and set up DNS servers provided by the DHCP server. It will be possible to set up DNS servers with systemd too soon.

An alternative to do not run dhcpcanon with root privileges nor systemd, is to use ambient-rs wrapper and run:

RUST_BACKTRACE=1 ./target/debug/ambient \
-c NET_RAW,NET_ADMIN,NET_BIND_SERVICE \
/usr/bin/python3 -m dhcpcanon.dhcpcanon -v

system files¶

sbin/dhcpcanon-script systemd/dhcpcanon.service tmpfiles.d/dhcpcanon.conf systemd/network/90-dhcpcanon.link console_scripts -> /sbin/dhcpcanon

run cases¶

1. standalone without systemd, using -sp sbin/dhcpcanon-script
2. standalone without systemd, using resolvconf
3. standalone without systemd, using resolvconf-admin
4. launched with a wrapper, using -sp sbin/dhcpcanon-script
5. launched with a wrapper, sing resolvconf
6. launched with a wrapper, using resolvconf-admin
7. launched as systemd service, using systemd-resolved

install from¶

• setup.py: dhcpcanon-scriptresolvconf, resolvconf-admin and/or systemd need to be installed manually
• pip: dhcpcanon-scriptresolvconf, resolvconf-admin and/or systemd need to be installed manually
• Makefile
• Debian

General contribution guidelines¶

• Any non-trivial change should contain tests.
• All the functions and methods should contain Sphinx docstrings which are used to generate the API documentation.

Code style guide¶

• We follow PEP8 Python Style Guide
• Use 4 spaces for a tab
• Use 79 characters in a line
• Make sure edited file doesn’t contain any trailing whitespace
• You can verify that your modifications don’t break any rules by running the flake8 script - e.g. flake8 dhcpcanon/edited_file.py or tox -e style. Second command will run flake8 on all the files in the repository.

And most importantly, follow the existing style in the file you are editing and be consistent.

Docstring conventions¶

For documenting the API we we use Sphinx and reStructuredText syntax.

Contribution workflow¶

git checkout -b <features/my_feature>

tox

Reporting a Vulnerability¶

Please do not report security issues using the public Issue tracker. Send a description of it to juga at riseup dot net. You are also encouraged to encrypt this email using GPG. The key can be found in the public servers.

This docummentation is partly copied from libcloud contributing

ISC-DHCP¶

Reference ISC implementation ISC License

homepage tar.gz

isc-dhcp-client¶

Debian default

debian debian source

network-manager built-in¶

systemd-networkd¶

man 5 systemd.network => DHCP options

udhcpc¶

Busybox implementation

debian

Gnome Network Manager¶

Can use 3 DHCP clients: - ISC DHCP client: package isc-dhpc-client, binarry dhclient - systemd DHCP client - built-in DHCP client

debian

wicd¶

debian

python-isc-dhcp-leases¶

Python module for reading dhcp leases files

debian

pydhcplib¶

Pure Python library.

GPL. Last updated XX. Commiters: 1.

pypi, repo, wiki debian

pydhcpd¶

DHCP command-line query and testing tool. Uses pydhcplib

GPL. Last updated: 2009

code

staticdhcpd¶

is an all-Python, RFC 2131-compliant DHCP server, with support for most common DHCP extensions and extensive site-specific customisation.

GPL. Last updated 12/03/2017. Commiters: +3

repo

dhquery¶

DHCP command line query and testing tool

code one github fork (updated 2016)

dhcpy6d¶

MAC address aware DHCPv6 server written in Python

Last updated 28/06/2017. Commiters: 2?

homepage repo doc debian

dhcpscapy¶

Simple DCHP client and server implemented with scapy

Last updated. 18/05/2014. Commiters: 1

repo

Message types¶

SHOULD randomize the ordering of options

If this can not be implemented
MUST order the options by option code number (lowest to highest).

MUST contain the Message Type option,

MUST NOT contain the Client Identifier option,

MUST NOT contain the Parameter Request List option.

MUST NOT contain any other option.

MUST contain the Message Type option,

MUST NOT contain the Client Identifier option,

MUST NOT contain the Parameter Request List option.

MUST NOT contain any other option.

If in response to a DHCPOFFER,
MUST contain the corresponding Server Identifier option
MUST contain the Requested IP address option.

If the message is not in response to a DHCPOFFER (BOUND, RENEW),:

MUST NOT contain a Requested IP address option

MUST contain the Message Type option,
MUST contain the Server Identifier option,
MUST contain the Requested IP address option;

MUST NOT contain the Client Identifier option.

MUST contain the Message Type option,

MUST NOT contain the Client Identifier option,
MUST NOT contain the Parameter Request List option.

It MUST NOT contain any other option.

Message Options¶

MUST NOT include in the message a Client IP address that has been obtained
with a different link-layer address.

MUST NOT use the Requested IP address option in DHCPDISCOVER messages.

MUST use the option when mandated (DHCPREQUEST)

If in INIT-REBOOT:

MUST perform a complete four-way handshake, starting with a DHCPDISCOVER

If the hardware address is reset to a new randomized value,

the DHCP client MUST use the new randomized value in the DHCP messages

MUST NOT have this option

DHCP
clients MUST use client identifiers based solely on the link-layer
address that will be used in the underlying connection.

MUST NOT have this option

MUST NOT send the Host Name option.

MUST NOT include the Client FQDN option

Nodes visiting untrusted networks MUST NOT send or use the PXE options.

MUST NOT use the

Vendor-Specific Information option (code 43), the Vendor Class
Identifier option (code 60), the V-I Vendor Class option (code 124),
or the V-I Vendor-Specific Information option (code 125),

Operational considerations¶

[RFC 7844#section-5.]

Implementers SHOULD provide a way for clients to control when the
anonymity profiles are used and when standard behavior is preferred.

dhcpcanon does not currently implement the standard behavior described in [RFC 2131] in order to keep the implementation simple and because all existing implementations already implement it

Not specified in RFC7844, but in RFC2131¶

the allocating
server SHOULD probe the reused address before allocating the address,
e.g., with an ICMP echo request, and the client SHOULD probe the
newly received address, e.g., with ARP.

 The client SHOULD perform a
check on the suggested address to ensure that the address is not
already in use.  For example, if the client is on a network that
supports ARP, the client may issue an ARP request for the suggested
request.  When broadcasting an ARP request for the suggested address,
the client must fill in its own hardware address as the sender's
hardware address, and 0 as the sender's IP address, to avoid
confusing ARP caches in other hosts on the same subnet.>>

The client SHOULD broadcast an ARP
reply to announce the client's new IP address and clear any outdated
ARP cache entries in hosts on the client's subnet.

The client SHOULD wait a random time between one and ten seconds to
   desynchronize the use of DHCP at startup.

a client retransmitting as described in section 4.1 might retransmit the
DHCPREQUEST message four times, for a total delay of 60 seconds

In both RENEWING and REBINDING states,
if the client receives no response to its DHCPREQUEST
message, the client SHOULD wait one-half of the remaining
time until T2 (in RENEWING state) and one-half of the
remaining lease time (in REBINDING state), down to a
minimum of 60 seconds, before retransmitting the
DHCPREQUEST message.

For example, in a 10Mb/sec Ethernet
internetwork, the delay before the first retransmission SHOULD be 4
seconds randomized by the value of a uniform random number chosen
from the range -1 to +1

Clients with clocks that provide resolution
granularity of less than one second may choose a non-integer
randomization value.

The delay before the next retransmission SHOULD
be 8 seconds randomized by the value of a uniform number chosen from
the range -1 to +1.

The retransmission delay SHOULD be doubled with
subsequent retransmissions up to a maximum of 64 seconds.

DHCP clients are free to use any strategy in selecting a DHCP server
among those from which the client receives a DHCPOFFER message.

client may choose to collect several DHCPOFFER
messages and select the "best" offer.

If the client receives no acceptable offers, the client
may choose to try another DHCPDISCOVER message.

The client collects DHCPOFFER messages over a period of time, selects
one DHCPOFFER message from the (possibly many) incoming DHCPOFFER
messages

The time
over which the client collects messages and the mechanism used to
select one DHCPOFFER are implementation dependent.

Times T1 and T2 are configurable by the server through options.  T1
defaults to (0.5 * duration_of_lease).  T2 defaults to (0.875 *
duration_of_lease).  Times T1 and T2 SHOULD be chosen with some
random "fuzz" around a fixed value, to avoid synchronization of
client reacquisition.

renewing_time = lease_time * 0.5 - time_elapsed_after_request
range_fuzz = lease_time * 0.875 - renewing_time
renewing_time += random.uniform(-(range_fuzz), +(range_fuzz))

rebinding_time = lease_time * 0.875 - time_elapsed_after_request
range_fuzz = lease_time - rebinding_time
rebinding_time += random.uniform(-(range_fuzz), +(range_fuzz))

There are scenarios in which a client connecting to a network
remembers a previously allocated address, i.e., when it is in the
INIT-REBOOT state.  In that state, any client that is concerned with
privacy SHOULD perform a complete four-way handshake, starting with a
DHCPDISCOVER, to obtain a new address lease.  If the client can
ascertain that this is exactly the same network to which it was
previously connected, and if the link-layer address did not change,
the client MAY issue a DHCPREQUEST to try to reclaim the current
address.

Message Options¶

Not specified in RFC7844, but in RFC2131¶

Not specified in any RFC¶

• is it needed to check that the ACK options match with the OFFER ones?
• is it needed to check that all options make sense?, which ones?

DHCPDISCOVER¶

Always broadcast in AP:

Ehter: src=client_mac, dst="ff:ff:ff:ff:ff:ff"
IP: src="0.0.0.0", dst="255.255.255.255"
UDP: sport=68, dport=67
BOOTP: Client Hardware address (chaddr in scapy)
DHCP: Message Type option (message-type in scapy)

DHCPREQUEST¶

In SELECTING state: Broadcast in AP:

Ehter: src=client_mac, dst="ff:ff:ff:ff:ff:ff"
IP: src="0.0.0.0", dst="255.255.255.255"
UDP: sport=68, dport=67
BOOTP: Client Hardware address (chaddr in scapy)
DHCP: Message Type option (message-type in scapy)
DHCP: Server Identifier option (server_id in scapy, siaddr in server BOOTP offer)
DHCP: Requested IP option (requested_addr in scapy, yiaddr in server BOOTP offer)

In RENEWING state: Unicast to server id:

Ehter: src=client_mac, dst=server_mac
IP: src=client_ip, dst=server_ip
UDP: sport=68, dport=67
BOOTP: Client Hardware address (chaddr in scapy)
DHCP: Message Type option (message-type in scapy)
Client IP address (ciaddr=client_ip)?

In REBINDING state: broadcast:

Ehter: src=client_mac, dst="ff:ff:ff:ff:ff:ff"
IP: src="0.0.0.0", dst="255.255.255.255"
UDP: sport=68, dport=67
BOOTP: Client Hardware address (chaddr in scapy)
DHCP: Message Type option (message-type in scapy)
Client IP address (ciaddr=client_ip)?

DHCPDECLINE¶

Always broadcast?:

Ehter: src=client_mac, dst="ff:ff:ff:ff:ff:ff"
IP: src="0.0.0.0", dst="255.255.255.255"
UDP: sport=68, dport=67
BOOTP: Client Hardware address (chaddr in scapy)
DHCP: Message Type option (message-type in scapy)
DHCP: Server Identifier option (server_id in scapy, siaddr in server BOOTP offer)
DHCP: Requested IP option (requested_addr in scapy, yiaddr in server BOOTP offer)

DHCPRELEASE¶

Always unicast, is not being used:

Ehter: src=client_mac, dst=server_mac
IP: src=client_ip, dst=server_ip
UDP: sport=68, dport=67
BOOTP: Client Hardware address (chaddr in scapy)
DHCP: Message Type option (message-type in scapy)
DHCP: Server Identifier option (server_id in scapy, siaddr in server BOOTP offer)

DHCPINFORM¶

Always broadcast in Anonymity Profile, is not being used:

Ehter: src=client_mac, dst="ff:ff:ff:ff:ff:ff"
IP: src=client_ip, dst="255.255.255.255"
UDP: sport=68, dport=67
BOOTP: Client Hardware address (chaddr in scapy)
BOOTP: Client IP address (ciaddr=client_ip)
DHCP: Message Type option (message-type in scapy)

Wrapper to inherit capabilities¶

With capsh, dhcpcanon could be launched as another user and inherit only the required capabilities, in a similar way as systemd.service does:

capsh --caps=cap_net_raw,cap_net_bind_service,cap_net_admin+epi --keep=1 -- -c "mkdir -p /run/dhcpcanon && cd /run/dhcpcanon && su -c 'exec /sbin/dhcpcanon enp0s25' -s /bin/sh dhcpcanon"

-s is needed cause dhcpcanon shell is /bin/false

However this does not have capabilities to create the socket.

To show the capabilities that are actually inherited:

capsh --keep=1 --secbits=0x1C --caps=cap_net_raw,cap_net_bind_service,cap_net_admin+epi  -- -c "mkdir -p /run/dhcpcanon && cd /run/dhcpcanon && su -c '/sbin/capsh --print' -s /bin/sh dhcpcanon"

In man capsh --securebits is not documented, securebits.h has some documentation, but it seems to be needed a newer version of libcap as commented in this post

Integration with Gnome Network Manager¶

Gnome Network Manager has several components.

In Debian the service NetworkManager by default calls dhclient which in turn calls nm-dhcp-helper. Depending on the configuration, dhclient is called with the parameters:

/sbin/dhclient -d -q
-sf /usr/lib/NetworkManager/nm-dhcp-helper
-pf /var/run/dhclient-<interface>.pid
-lf /var/lib/NetworkManager/dhclient-<?>-<interface>.lease
-cf /var/lib/NetworkManager/dhclient-<interface>.conf
<interface>

Dclient calls nm-dhcp-helper via the -sf parameter, which seems to communicate back with NetworkManager via D-Bus.

NetworkManager can be configured to use dhcpcd or internal, as DHCP clients instead of dhclient.

FIXME: Configuring NetworkManager to use internal did not work
(why?). Is it using systemd DHCP client code? (libsystemd-network <https://github.com/NetworkManager/NetworkManager/tree/master/src/systemd/src/libsystemd-network`>`_
is included in ``NetworkManager source code, which is in systemd
code).

It does not work either with dhcpcd:
NetworkManager[12712]: <warn>  [1493146345.7994] dhcp-init: DHCP client 'dhcpcd' not available

FIXME: Are these variables documented somewhere?.

The following reasons
   are currently defined: MEDIUM, PREINIT, BOUND, RENEW, REBIND,  REBOOT,
   EXPIRE, FAIL, STOP, RELEASE, NBI and TIMEOUT.

reason='PREINIT'
interface=
--------------------------
reason='REBOOT'
interface=
new_ip_address=
new_network_number=
new_subnet_mask=
new_broadcast_address=
new_routers=
new_domain_name=
new_domain_name_servers=

FIXME: however for some reason this generates D-Bus errors.

nm notes¶

Debugging:

[logging] level=DEBUG

It is not possible to set dhcp-send-hostname (Bug 768076 - No way to set dhcp-send-hostname globally) globally.

To modify dhcp-send-hostname per interface:

nmcli connection modify “Wired connection” ipv4.dhcp-send-hostname no nmcli connection show “Wired connection”

Or the files:

/etc/NetworkManager/system-connections/Wiredconnection

There is currently no way that when a new device is create it defaults to a configuration.

Integration with wicd¶

TBD

wicd

wicd documentation

dhcpcapfsm module¶

dhcpcap module¶

dhcpcaplease module¶

clientscript module¶

timers module¶

Timers for the DHCP client implementation of the Anonymity Profile ([RFC 7844]).

dhcpcanon.timers.future_dt_str(dt, td)[source]¶

.

dhcpcanon.timers.gen_delay_selecting()[source]¶

Generate the delay in seconds in which the DISCOVER will be sent.

[RFC 2131#section-4.4.1]:

The client SHOULD wait a random time between one and ten seconds to
desynchronize the use of DHCP at startup.

dhcpcanon.timers.gen_rebinding_time(lease_time, elapsed=0)[source]¶

.

dhcpcanon.timers.gen_renewing_time(lease_time, elapsed=0)[source]¶

Generate RENEWING time.

[RFC 2131#section-4.4.5]:

T1
defaults to (0.5 * duration_of_lease).  T2 defaults to (0.875 *
duration_of_lease).  Times T1 and T2 SHOULD be chosen with some
random "fuzz" around a fixed value, to avoid synchronization of
client reacquisition.

dhcpcanon.timers.gen_timeout_request_rebind(lease)[source]¶

.

dhcpcanon.timers.gen_timeout_request_renew(lease)[source]¶

Generate time in seconds to retransmit DHCPREQUEST.

[RFC 2131#section-4..4.5]:

In both RENEWING and REBINDING states,
if the client receives no response to its DHCPREQUEST
message, the client SHOULD wait one-half of the remaining
time until T2 (in RENEWING state) and one-half of the
remaining lease time (in REBINDING state), down to a
minimum of 60 seconds, before retransmitting the
DHCPREQUEST message.

dhcpcanon.timers.gen_timeout_resend(attempts)[source]¶

Generate the time in seconds in which DHCPDISCOVER wil be retransmited.

[RFC 2131#section-3.1]:

might retransmit the
DHCPREQUEST message four times, for a total delay of 60 seconds

[RFC 2131#section-4.1]:

For example, in a 10Mb/sec Ethernet
internetwork, the delay before the first retransmission SHOULD be 4
seconds randomized by the value of a uniform random number chosen
from the range -1 to +1.  Clients with clocks that provide resolution
granularity of less than one second may choose a non-integer
randomization value.  The delay before the next retransmission SHOULD
be 8 seconds randomized by the value of a uniform number chosen from
the range -1 to +1.  The retransmission delay SHOULD be doubled with
subsequent retransmissions up to a maximum of 64 seconds.

dhcpcanon.timers.nowutc()[source]¶

.

dhcpcaputils module¶

constants module¶

Constants for the DHCP client implementation of the Anonymity Profile ([RFC 7844]).

dhcpcanon.constants.PRL = b'\x01\x03\x06\x0f\x1f!+,./y\xf9\xfc'¶

SD_DHCP_OPTION_SUBNET_MASK = 1 SD_DHCP_OPTION_ROUTER = 3 SD_DHCP_OPTION_DOMAIN_NAME_SERVER = 6 SD_DHCP_OPTION_DOMAIN_NAME = 15 SD_DHCP_OPTION_ROUTER_DISCOVER = 31 SD_DHCP_OPTION_STATIC_ROUTE = 33 SD_DHCP_OPTION_VENDOR_SPECIFIC = 43 SD_DHCP_OPTION_NETBIOS_NAMESERVER = 44 SD_DHCP_OPTION_NETBIOS_NODETYPE = 46 SD_DHCP_OPTION_NETBIOS_SCOPE = 47 SD_DHCP_OPTION_CLASSLESS_STATIC_ROUTE = 121 SD_DHCP_OPTION_PRIVATE_CLASSLESS_STATIC_ROUTE = 249 SD_DHCP_OPTION_PRIVATE_PROXY_AUTODISCOVERY = 252

conflog module¶

Logging configuration.

Finite State Machine diagram¶

Classes diagram¶

Packages diagram¶

Calls diagram¶

Organigram¶

This organigram does not reflect the current status of dhcpcanon, but as it should be changed