diff --git a/dhcp_server/DOCS.md b/dhcp_server/DOCS.md index 30bdd4d4853..e27ecb1aef7 100644 --- a/dhcp_server/DOCS.md +++ b/dhcp_server/DOCS.md @@ -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: @@ -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 @@ -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 \ No newline at end of file diff --git a/dhcp_server/data/run.sh b/dhcp_server/data/run.sh index ff0b89871dc..f277d1cb5e4 100755 --- a/dhcp_server/data/run.sh +++ b/dhcp_server/data/run.sh @@ -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