Skip to content

Commit

Permalink
Enhance DHCP options in addon_core_dhcp_server
Browse files Browse the repository at this point in the history
  • Loading branch information
@rkmfl
rkmfl committed Jun 15, 2024
1 parent ce7ae49 commit ca2fec1
Show file tree
Hide file tree
Showing 2 changed files with 98 additions and 57 deletions.
129 changes: 78 additions & 51 deletions dhcp_server/DOCS.md
View file
Original file line number Diff line number Diff line change
@@ -1,34 +1,34 @@
# Home Assistant Add-on: DHCP server
# Home Assistant Add-on: DHCP Server

## Installation

Follow these steps to get the add-on installed on your system:
Follow these steps to install the DHCP add-on:

1. Navigate in your Home Assistant frontend to **Settings** -> **Add-ons** -> **Add-on store**.
2. Find the "DHCP server" add-on and click it.
3. Click on the "INSTALL" button.
4. Modify configuration as needed
2. Find and click the "DHCP server" add-on.
3. Click the "INSTALL" button.
4. Modify the configuration as needed.

## How to use
## How to Use

1. Set the `domain` option, e.g., `mynetwork.local`.
2. Save the add-on configuration by clicking the "SAVE" button.
1. Set the `domain` option, e.g., `mynetwork.internal`.
2. Save the configuration by clicking the "SAVE" button.
3. Start the add-on.

## Configuration

The DHCP server add-on can be tweaked to your likings. This section
describes each of the add-on configuration options.
The DHCP server add-on can be customized to suit your needs. This section describes all of the configuration options.

Example add-on configuration:
Example configuration:

```yaml
domain: mynetwork.local
domain: mynetwork.internal
dns:
- 8.8.8.8
- 8.8.4.4
ntp:
- 192.168.1.0
- pool.ntp.org
default_lease: 86400
max_lease: 172800
networks:
Expand All @@ -38,99 +38,126 @@ networks:
range_end: 192.168.1.200
broadcast: 192.168.1.255
gateway: 192.168.1.1
interface: end0
interface: eth0
hosts:
- name: webcam_xy
mac: aa:bb:ee:cc
- name: bedroom-switch
mac: aa:bb:cc:dd:ee:ff
ip: 192.168.1.40
```
### Option: `domain` (required)

Your network domain name, e.g., `mynetwork.local` or `home.local`
The domain name for your network, e.g., `home.internal` or `home.local` (be aware that issues exist with using `.local` for DHCP/DNS)

### Option: `dns` (required)

The DNS servers your DHCP server gives to your clients. This option can
contain a list of servers. By default, it is configured to have Google's
public DNS servers: `"8.8.8.8", "8.8.4.4".
The DNS (Name Servers) provided to clients. This option can
contain a list of servers. By default, Google's public DNS servers are included: `8.8.8.8`, `8.8.4.4`.

### Option `ntp` (required)
### Option: `ntp` (required)

The NTP servers your DHCP server gives to your clients. This option can
contain a list of server. By default, none are configured ([])
The NTP servers (Network Time Protocol) provided to clients. By default, no servers are included (`[]`).

### Option: `default_lease` (required)

The default time in seconds that the IP is leased to your client.
Defaults to `86400`, which is one day.
The default lease time in seconds. Defaults to `86400` (one day).

### Option: `max_lease` (required)

The max time in seconds that the IP is leased to your client.
Defaults to `172800`, which is two days.
The maximum lease time in seconds. Defaults to `172800` (two days).

### Option: `networks` (one item required)
### Option: `networks` (at least one item required)

This option defines settings for one or multiple networks for the DHCP server
to hand out IP addresses for.
Defines one or more IP address ranges ("networks"). For example, `192.168.1.0` to `192.168.1.255` (also expressed as a Class-C network: `192.168.1.0/24`).

At least one network definition in your configuration is required for the
DHCP server to work.
A minimum of one network is required. Example:
```yaml
networks:
- subnet: 192.168.1.0
netmask: 255.255.255.0
range_start: 192.168.1.100
range_end: 192.168.1.200
gateway: 192.168.1.1
interface: eth0
broadcast: 192.168.1.255
```

#### Option: `networks.subnet`

Your network schema/subnet. For example, if your IP addresses are `192.168.1.x`
the subnet becomes `192.168.1.0`.
The first IP of the network. For example, if your IP addresses are `192.168.1.x`, the subnet is `192.168.1.0`.

#### Option: `networks.netmask`

Your network netmask. For example, if your IP addresses are `192.168.1.x` the
netmask becomes `255.255.255.0`.
The network netmask. Typically `255.255.255.0` for a class-C network, which includes addresses from `x.x.x.0` to `x.x.x.255` (254 usable addresses).

A class-B network would have a netmask of `255.255.0.0`, covering addresses from `x.x.0.0` to `x.x.255.255` (65,534 usable addresses).

If unsure, use `255.255.255.0`.

#### Option: `networks.range_start`

Defines the start IP address for the DHCP server to lease IPs for.
Use this together with the `range_end` option to define the range of IP
addresses the DHCP server operates in.
The start IP address for the DHCP lease range. Used with `range_end` to define the range of IP's available for lease by the DHCP server.

#### Option: `networks.range_end`

Defines the end IP address for the DHCP server to lease IPs for.
The last IP address for the range of IP addresses available for lease by the DHCP server.

#### Option: `networks.broadcast`

The broadcast address specific to the lease range. For example, if your
IP addresses are `192.168.1.x`, the broadcast address is usually `192.168.1.255`.
The broadcast IP address of the network, typically the first three octets of your class-C network plus `.255`, e.g., `192.168.1.255` for `192.168.1.0`.

#### Option: `networks.gateway`

Sets the gateway address for that the DHCP server hands out to its clients.
This is usually the IP address of your router.
The router (gateway) address where traffic is routed from your network onto the Internet.

This is typically the first three octets of your class-C network plus `.1`, e.g., `192.168.1.1` for `192.168.1.0`.

This is required. If this address is missing or wrong, traffic will not flow onto the Internet.

#### Option: `networks.interface`

The network interface to listen to for this network, e.g., `end0`.
The network interface to listen on, e.g., `eth0`, the default for Home Assistant OS.

### Option: `hosts` (optional)

This option defines settings for one or host definitions for the DHCP server.
A list of hosts to be assigned fixed IP addresses. Requires the host's MAC address.

Fixed IP addresses can be anywhere within the network, as long as they are not duplicates. They are not required to be within the `range_start` and `range_end`. This range is for dynamically allocated IP addresses.

It allows you to fix a host to a specific IP address.
By default, no hosts are configured and none are required for DHCP server function.

By default, non are configured.
Example:
```yaml
hosts:
- name: MyRouter
mac: aa:bb:cc:dd:ee:ff
ip: 192.168.1.1
6: 94.140.14.15 # Option 6 w/Family-Friendly DNS Server (AdGuard)
```

#### Option: `hosts.name`

The name of the hostname you'd like to fix an address for.
The name of the host (client) to be assigned a fixed IP address.

#### Option: `hosts.mac`

The MAC address of the client device.
The MAC address of the host (client) device.

#### Option: `hosts.ip`

The IP address you want the DHCP server to assign.
The IP address assigned to the host (client) device.

#### Option: Number between 1 - 254

For advanced users, you may choose to include numbered DHCP options.

For example, you may prefer an alternative DNS server for your Router or Children's PC's, that DNS server can be assigned with **Option 6.**

Assign a custom domain name using **Option 15.**

Assign a TFTP server for flashing devices using **Option 66.**

Assign a NetBIOS name server to speed local name resolution on Windows networks using **Option 44.**

## Support

Expand All @@ -148,4 +175,4 @@ In case you've found a bug, please [open an issue on our GitHub][issue].
[forum]: https://community.home-assistant.io
[issue]: https://github.com/home-assistant/addons/issues
[reddit]: https://reddit.com/r/homeassistant
[repository]: https://github.com/hassio-addons/repository
[repository]: https://github.com/hassio-addons/repository
26 changes: 20 additions & 6 deletions dhcp_server/data/run.sh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -57,17 +57,31 @@ for network in $(bashio::config 'networks|keys'); do
} >> "${CONFIG}"
done

# Create hosts
# Create DHCP Hosts by enumerating Host List & Keys (IP, MAC, Name, or DHCP Option)
for host in $(bashio::config 'hosts|keys'); do
IP=$(bashio::config "hosts[${host}].ip")
MAC=$(bashio::config "hosts[${host}].mac")
NAME=$(bashio::config "hosts[${host}].name")

{
echo "host ${NAME} {"
echo " hardware ethernet ${MAC};"
echo " fixed-address ${IP};"
echo " option host-name \"${NAME}\";"

# Iterate all Hosts
for key in $(bashio::config "hosts[${host}]|keys"); do
VALUE=$(bashio::config "hosts[${host}].${key}")

# Validate: Named options
if [[ "${key}" == "ip" ]]; then
echo " fixed-address ${VALUE};"
elif [[ "${key}" == "mac" ]]; then
echo " hardware ethernet ${VALUE};"

# Validate: Numeric DHCP Option
elif [[ "${key}" =~ ^[0-9]+$ ]]; then
if (( key > 0 && key < 255 )); then
echo " option ${key} ${VALUE};"
fi
fi
done

echo "}"
} >> "${CONFIG}"
done
Expand Down

0 comments on commit ca2fec1

Please sign in to comment.