DHCP Server for Windows » faq

How to run external scripts from the HTTP server?

uwe — Sun, 11 Aug 2024 07:38:19 +0000

External scripts are a great way to enhance the HTTP server with specific features. This is supported in the Raspberry Pi Version V2.9.4.0 only, for now.

The external script can be actually any executable, but the most obvious is to run a bash script. Here is an example:

#!/bin/bash
echo ""
echo ""
echo "Hello Script"
echo ""

Place this file into your wwwroot folder name it say “script01″ and make it an executable with the chmod command from the command line:

cd /usr/local/etc/dhcpsrv/wwwroot
chmod +x script01

It is assumed that the HTTP Server function is enabled and reachable by an url such as http://raspberry. To execute script01 and see the resulting page enter http://raspberry/script01 into the address line of your browser and you will see the Hello Script page. If that is not the case then please check the HTTP server configuration.

In case you don’t want to return HTML code from your script but for example some JSON structure then this can be done as well. This a bash script that returns a JSON structure:

#!/bin/bash
DATA="{\"valid\":true}"
# write to stdout the HTTP response
DATESTRING=$(date "+%a, %d %b %Y %H:%M:%S %Z")
printf "HTTP/1.1 200 OK\r\n"
printf "Date: %s\r\n" "$DATESTRING"
printf "Last-Modified: %s\r\n" "$DATESTRING"
printf "Server: %s\r\n" "dhcpsrv"
printf "Content-Type: %s\r\n" "application/json"
printf "Content-Length: %s\r\n" "${#DATA}"
printf "\r\n"
printf "%s" "$DATA"

As you can see the big difference is that in case of something else than a , the full header needs to be included into the output of the bash script. Let’s paste the above into a bash script02 file and make that executable as well with chmod, then your browser will display the JSON output when directed to the url http://raspberry/script02.

The examples so far were HTTP GET use cases. Now let’s take a look at POST requests. POST requests differ from GET requests in extra data supplied from the client app running in the browser. This extra data is usually a list of key/value pairs as they are coming from an HTML form. The DHCP server integrated HTTP function writes that extra data into a temporary file and that filename is supplied as a parameter to the external script. Here is an example on how to deal with that:

#!/bin/bash
saveIFS=$IFS
IFS='=&'

declare -A post

if [ -f "$1" ]; then
 # construct the associative array for POST_STRING
 POST_STRING="$(<"$1")"
 parm=($POST_STRING)
 for ((i=0; i<${#parm[@]}; i+=2))
 do
    post[${parm[i]}]=${parm[i+1]}
 done
fi

IFS=$saveIFS

# do something with the post data e.g. ${post["firstname"]}

printf "HTTP/1.1 301 Moved Permanently\r\n"
printf "Date: %s\r\n" "$DATESTRING"
printf "Last-Modified: %s\r\n" "$DATESTRING"
printf "Server: %s\r\n" "dhcpsrv"
printf "Location: %s\r\n" "post.html"
printf "\r\n"

We see two important things here:

The post data is read from the file supplied as a argument $1 into a param array splitted by ‘=’ and ‘&’. The param array is only there to construct an associative array with the name “post”. That in turn can be used by the script to perform the required action on that data.
The returning result text from the script is now a redirect header. This is part of the post-redirect-get pattern commonly used together with POST requests. In this case the redirection target is post.html and obviously can be anything else.

We save the above script as “script03″ in the wwwroot folder and call that script from a post request such as in the following example HTML post.html:



 
 
 
  
   First name:
   


   Last name:

This HTML code presents a form with two entry fields “First name” and “Last name”. Those will show up in the script03 as ${post[“firstname”]} and ${post[“lastname”]} and can be used to perform whatever that script needs to do.

QUERY data is supported as well, as they are supplied as part of the URL such as “http://raspberry/script04?key1=value1&key2=value2″. An enhanced version of script03 (called script04) can make use of the query data as follows:

#!/bin/bash
saveIFS=$IFS
IFS='=&'

declare -A post
declare -A query

# construct the associative array for QUERY_STRING
parm=($QUERY_STRING)
for ((i=0; i<${#parm[@]}; i+=2))
do
 query[${parm[i]}]=${parm[i+1]}
done

if [ -f "$1" ]; then
 # construct the associative array for POST_STRING
 POST_STRING="$(<"$1")"
 parm=($POST_STRING)
 for ((i=0; i<${#parm[@]}; i+=2))
 do
    post[${parm[i]}]=${parm[i+1]}
 done
fi

IFS=$saveIFS

# do something with the post data e.g. ${post["firstname"]} or ${query["key1"]}

printf "HTTP/1.1 301 Moved Permanently\r\n"
printf "Date: %s\r\n" "$DATESTRING"
printf "Last-Modified: %s\r\n" "$DATESTRING"
printf "Server: %s\r\n" "dhcpsrv"
printf "Location: %s\r\n" "post.html"
printf "\r\n"

The scripts executed this way run with the privilege of the dhcpsrv executable. Usually root privileges in case of systemctl based installation as described here. Handle with care!

Does the integrated HTTP Server support POST?

uwe — Sun, 11 Aug 2024 07:35:53 +0000

Yes, POST requests are supported since V2.9.4.0 on Raspberry Pi version only for now. It works in a CGI like manner and is described in detail here.

How to configure DHCP server for redundancy?

uwe — Mon, 31 Aug 2020 03:27:53 +0000

The DHCP Server supports the split scope redundancy

Split scope means that you simply run two DHCP servers each with a different IP range. A client asking for an IP address by broadcasting a DHCPDISCOVER message gets two answers. This adds network traffic but is otherwise not creating any trouble. The client will choose one of the answers (mostly the first it got). Once an IP address is assigned then the client will extend the lease by sending the DHCP message by unicast anyway and is therefore only talking to the chosen DHCP server. The client will reinitiate the complete process in case that server is down and does not reply to requests. The beauty of split scope redundancy is, that it only relies on standard DHCP protocol mechanisms. The client will simply get a new IP address from the other DHCP server and will be happy to talk to that server from now on. Another big benefit is that since the two DHCP servers never sync up, they don‘t need to be the same software or software version.

Configuration of server 1:

[Settings]
IPPOOL_1=10.0.0.2-200
IPBIND_1=10.0.0.1
AssociateBindsToPools=1
Trace=1

[GENERAL]
LEASETIME=86400
NODETYPE=8
SUBNETMASK=255.255.254.0

Configuration of server 2:

[Settings]
IPPOOL_1=10.0.1.2-200
IPBIND_1=10.0.1.1
AssociateBindsToPools=1
Trace=1

[GENERAL]
LEASETIME=86400
NODETYPE=8
SUBNETMASK=255.255.254.0

Please note that I have chosen a subnet mask of 255.255.254.0 which allows me to have twice as many IP addresses. The two servers are running on two different computers with the IP addresses 10.0.0.1 and 10.0.1.1, respectively. Each serve different IP ranges: 10.0.0.2-200 and 10.0.1.2-200.

The clients can talk to each other and to both servers with no problem, because they are all on the same subnet 10.0.0.1/23 but get IP addresses assigned depending on which server was chosen.

The only thing that needs to be taken care of is to set DNS_0 and ROUTER_0 dependent on your network infrastructure.

In case DHCP server acts as DNS server as well, then one problem exists. A DNS request reaching server 0 can not be fulfilled with data stored at server 1, and vice versa. Therefore, since V2.9 the SyncServer feature has been introduced. Here is the same example as above with the SyncServer feature enabled:

Configuration of server 1:

[Settings]
IPPOOL_1=10.0.0.2-200
IPBIND_1=10.0.0.1
AssociateBindsToPools=1
Trace=1
SyncServer=10.0.1.1:80

[GENERAL]
LEASETIME=86400
NODETYPE=8
SUBNETMASK=255.255.254.0

[HTTP-SETTINGS]
EnableHTTP=1

Configuration of server 2:

[Settings]
IPPOOL_1=10.0.1.2-200
IPBIND_1=10.0.1.1
AssociateBindsToPools=1
Trace=1
SyncServer=10.0.0.1:80

[GENERAL]
LEASETIME=86400
NODETYPE=8
SUBNETMASK=255.255.254.0

[HTTP-SETTINGS]
EnableHTTP=1

Please note that enabling the HTTP function is essential for this to work, because the sync mechanism simply utilizes the same communication as the status web page.

How to uninstall DHCP server

uwe — Fri, 03 Apr 2015 15:18:21 +0000

The DHCP server has no install function and therefore also does not have an uninstall function either. The DHCP server runs as an application without any install, just run it and stop it as you wish.

If you are using the DHCP server as a service then you have to remove the service. To remove the service, you can either just hit the stop followed by the remove button or you go into the services applet of windows and remove the service there. Please keep in mind that you need administrator privileges to do so.

Some people that have used the HTTP function of the DHCP server software, have experienced that the browser shows the DHCP status page even when the software is not running. This is due to the browser and its cache. Please just clean your browser cache in that case.

After you have removed the service and cleaned the browser cache, the DHCP server software is completely removed from your system.

How to exclude clients from IP assignment

uwe — Sun, 21 Sep 2014 09:04:06 +0000

Option 1: Exclude with negative (black) list

You can use the IPSCOPE feature, in order to exclude one or more clients from getting an IP address assigned. Assuming you want to exclude just one client with a given MAC address (e.g. 08:00:00:01:03:A1). Here is an example:

[Settings]
IPPOOL_1=10.30.99.2-30
IPBIND_1=10.30.99.1
IPSCOPE_1=if(chaddr == "08:00:00:01:03:A1", null, "validdevice");

AssociateBindsToPools=1
Trace=1
DeleteOnRelease=0
ExpiredLeaseTimeout=3600

[GENERAL]
LEASETIME=86400
NODETYPE=8
SUBNETMASK=255.255.255.0
DNS_0=10.30.99.1
ROUTER_0=10.30.99.1

This will consider all clients but 08:00:00:01:03:A1 to be a “validdevice”. 08:00:00:01:03:A1 is not.

The term validdevice can be used to configure specifics in the scope section for the devices named by IPSCOPE_1. You can follow up on that by reading the IPSCOPE feature description. There is no need to go into details of that now for excluding certain devices from IP address assignment.

If you want to exclude even more devices then just extent the IPSCOPE setting accordingly:

[Settings]
...
IPSCOPE_1=if(chaddr == "08:00:00:01:03:A1" || chaddr == "08:00:00:01:03:A2", null, "validdevice");
...

Now also 08:00:00:01:03:A2 will not get an IP address anymore.
Please be aware that this feature works only, if the client(s) don’t already have a client section in the INI file. Only new clients (unknown to the DHCP server) will be selected based on the IPSCOPE definition.

Option 2: Exclude with positive (white) list

The other way to define which client get an IP address assigned is a white-list approach. Here is an example on how to do that based on the IgnoreUnkownClients setting:

[Settings]
IPPOOL_1=10.30.99.2-30
IPBIND_1=10.30.99.1

AssociateBindsToPools=1
Trace=1
DeleteOnRelease=0
ExpiredLeaseTimeout=3600
IgnoreUnknownClients=1

[GENERAL]
LEASETIME=86400
NODETYPE=8
SUBNETMASK=255.255.255.0
DNS_0=10.30.99.1
ROUTER_0=10.30.99.1

; white-list of clients that get an IP address assigned:
[10-11-12-13-14-15]
[10-11-12-13-14-16]
[10-11-12-13-14-17]
[10-11-12-13-14-18]

Please note that only the four clients listed based on their mac addresses will be served by the DHCP server. The client section does not need to include anything. Simply add more client mac addresses to the list to serve them as well.
The key to this approach is, besides the fact that you need to know the clients beforehand, is to set IgnoreUnkownClients=1. You can add clients to the INI file anytime. And, you can even use wildcards, as described here.

The following example adds all clients 10-11-12-13-14-00 up to 10-11-12-13-14-FF to the (white) list of clients:

...
[10-11-12-13-14-??]
...

I want to establish a pxe boot environment but I don’t get it to work. What am I doing wrong?

uwe — Sat, 06 Sep 2014 11:34:22 +0000

Remote booting of a device usually works in the following steps.

Client device boots up and requests an IP address from the DHCP server in the local network. This is done by means of DHCPDISCOVER and DHCPREQUEST messages that the client sends out. Mostly via broadcast messages.
DHCP server answers to the request with DHCPOFFER / DHCP ACK messages. Along with that comes the IP address that the DHCP server is assigning to the requesting client. Plus additional information such as the address of the TFTP server and the file to load. This is stored in options as part of the DHCP messages. The options are: NEXTSERVER and OPTION_66 for the TFTP server address, BOOTFILE for the file to load. Sometimes other options are needed but that depends on the client.
Once the client has booted so far (from ROM) that he needs the actual boot file, he is contacting the TFTP server. The address of the TFTP server has been given to the client as part of Step 2. The TFTP server is requested to send the file specified as the boot file (again: see Step 2). This transfers one file from the server to the client.
The boot file may not be the only file needed on the client side to finish booting. What usually happens is once the boot file is on the client side, the ROM based first boot phase is finished and the operating system included in the boot file is executed. Now a different OS than the one acting from ROM is starting and a different TCP/IP stack is also running. Therefore the client starts again with step 1 – requesting an IP address …
More files may be fetched from the TFTP server based on whatever the boot file OS may be doing now.

The following INI file is the setup for a pxe boot environment for pxelinux. It assumes 192.168.0.2 as the server IP address.

[Settings]
Trace=1
IgnoreUnknownClients=1
ConfigureUnknownClients=1
AssociateBindsToPools=1

IPBIND_2=192.168.0.2
IPPOOL_2=192.168.0.3-134

[General]
LEASETIME=86400 ; lease time of 1 day
NEXTSERVER=192.168.0.2 ; tftp server (clients look in option 66 and/or in NEXTSERVER field)
OPTION_66=192.168.0.2 ; tftp server
BOOTFILE=pxelinux.0
SUBNETMASK=255.255.255.0
DOMAINNAME=mydomain.local
DNS_1=192.168.0.2

[TFTP-Settings] ; settings for the integrated tftp server
EnableTFTP=1
Root=D:\tftproot\

[DNS-Settings] ; settings for the integrated dns server
EnableDNS=1

This configuration works under the assumption that a server side path d:\tftproot\ exists with the needed pxelinux files stored, i.e. pxelinux.0. The integrated DNS is not really needed for a pxe boot environment to work. Please note that the integrated TFTP server (new in V1.9) is configured. If you are already using another TFTP server and want to continue to do so, then please set EnableTFTP=0 and make sure that the external TFTP server is setup accordingly.

The same works with Windows 7 and Windows PE boot. If you for example set up a Windows 7 network boot as it is described in the german computer magazin c’t 5/2011 page 176ff, then the following INI file will do the job:

[SETTINGS]
IPPOOL_1=192.168.0.3-254
IPBIND_1=192.168.0.2
AssociateBindsToPools=1

[GENERAL]
LEASETIME=86400
NODETYPE=8
SUBNETMASK=255.255.255.0
BOOTFILE=wdsnbp.0
NEXTSERVER=192.168.0.2

[TFTP-SETTINGS]
EnableTFTP=1
ROOT=D:\pxe

PXE booting UEFI client

The PXE booting of a UEFI client follows the same principle 5 steps as above. The UEFI PXE specification however makes it mandatory to have more INI file settings as described in the previous example. Here is an example INI file for UEFI PXE specification:

[SETTINGS]
IPPOOL_1=192.168.0.3-254
IPBIND_1=192.168.0.2
AssociateBindsToPools=1
IPSCOPE_1=if(OPTION_60~="PXEClient*", "PXEClient", "General") ;
; use [PXEClient] section if OPTION_60 starts with "PXEClient"

[PXEClient]
OPTION_60="PXEClient"
OPTION_97=@97 ; copy of option 97 from request
OPTION_61=@97 ; copy of option 97 from request
OPTION_43=06 (0A) 08 (00 00 01 192.168.0.2) 09 (00 00 ("Server")) 0A (0F "Select") FF ;
; PXE_DISCOVERY_CONTROL: 06, set this to 0A to not prompt
; PXE_BOOT_SERVERS: 08, set IP address of server
; PXE_BOOT_MENU: 09, set boot menu
; PXE_MENU_PROMPT: 0A, set prompt
OPTION_66="192.168.0.2"
BOOTFILE="BOOTX64.EFI"

[GENERAL]
LEASETIME=86400
NODETYPE=8
SUBNETMASK=255.255.255.0
NEXTSERVER=192.168.0.2

[TFTP-SETTINGS]
EnableTFTP=1
ROOT=D:\pxe

Booting BIOS and UEFI clients from the same server

The example above assumes that every PXE client is a UEFI client and gets the same boot file. In a mixed network this does not work, because a legacy BIOS client cannot execute an EFI boot file and a UEFI client cannot execute a BIOS boot file. Both client types announce their processor architecture in the vendor class (option 60), so IPSCOPE_n can be used to send each of them to a different scope section.

Processor architecture numbers

The client sends the architecture as a five digit decimal number as part of its vendor class, for example PXEClient:Arch:00007:UNDI:003000. These are the values in practical use:

PXEClient:Arch:00000	Legacy BIOS (x86)	pxelinux.0, undionly.kpxe
PXEClient:Arch:00006	UEFI IA32 (32 bit)	bootia32.efi, ipxe-i386.efi
PXEClient:Arch:00007	UEFI x64	bootx64.efi, ipxe-x86_64.efi
PXEClient:Arch:00009	UEFI x64 (alternative)	bootx64.efi, ipxe-x86_64.efi
PXEClient:Arch:00011	UEFI ARM64	bootaa64.efi, ipxe-arm64.efi

Most x64 UEFI firmware reports 00007, a few report 00009. Both mean the same thing in practice, so a configuration for 64 bit UEFI should accept both.

Example INI file

The following INI file serves legacy BIOS clients, 32 bit UEFI clients and 64 bit UEFI clients. It also covers iPXE chainloading, where the client first boots a small iPXE image over TFTP and then comes back with a user class of “iPXE” to fetch its boot script over HTTP. It assumes 192.168.0.2 as the server IP address.

[SETTINGS]
IPPOOL_1=192.168.0.3-254
IPBIND_1=192.168.0.2
AssociateBindsToPools=1
IPSCOPE_1=if(userclass ~~ "iPXE*", "iPXE", if(vendorclass ~~ "PXEClient:Arch:00007*" || vendorclass ~~ "PXEClient:Arch:00009*", "PXE-UEFI-X64", if(vendorclass ~~ "PXEClient:Arch:00006*", "PXE-UEFI-IA32", if(vendorclass ~~ "PXEClient:Arch:00000*", "PXE-BIOS", "General")))) ;

[GENERAL]
LEASETIME=86400
NODETYPE=8
SUBNETMASK=255.255.255.0
NEXTSERVER=$(IPBIND_1)
OPTION_66=$(IPBIND_1)

[PXE-BIOS]
BOOTFILE=undionly.kpxe
OPTION_60="PXEClient"
OPTION_97=@97
OPTION_43=06 (0A) FF

[PXE-UEFI-X64]
BOOTFILE=ipxe-x86_64.efi
OPTION_60="PXEClient"
OPTION_97=@97
OPTION_43=06 (0A) FF

[PXE-UEFI-IA32]
BOOTFILE=ipxe-i386.efi
OPTION_60="PXEClient"
OPTION_97=@97
OPTION_43=06 (0A) FF

[iPXE]
BOOTFILE=http://$(IPBIND_1)/autoexec.ipxe

[TFTP-SETTINGS]
EnableTFTP=1
ROOT=D:\pxe

[HTTP-SETTINGS]
EnableHTTP=1
ROOT=D:\pxe

The scope sections only contain what differs between the client types. Everything the clients have in common stays in [GENERAL], where every client picks it up. $(IPBIND_1) is replaced by the value of IPBIND_1, so the server address has to be written only once.

If you do not use iPXE, drop the [iPXE] section, the [HTTP-SETTINGS] section and the first if() test, and set BOOTFILE in the PXE sections to the boot loader you want to load directly, for example bootx64.efi for UEFI x64 and pxelinux.0 for BIOS.

Details that are easy to miss

The whole IPSCOPE_1 expression has to be on one single line. A setting is not continued on the next line. This is the most frequent mistake when a configuration is copied out of an e-mail or a chat window, because those tend to wrap long lines.
The last if() returns “General” and not null. A scope that results to null does not match at all, so a client that is not booting over the network would end up without any address. Returning the name of a regular section instead makes those clients fall back to a normal lease.
OPTION_60, OPTION_97 and OPTION_43 are needed in every PXE scope section. A UEFI client checks that the answer really comes from a PXE server before it accepts the boot file. Without these options most UEFI firmware silently ignores the offer and runs into a timeout.
OPTION_43 belongs into the PXE scope sections only, not into the [iPXE] section. Once iPXE is running, boot server discovery is over and the option can send the client back into a discovery loop.
The order of the tests matters. The user class is checked first, so that a client which has already been chainloaded into iPXE is not sent the iPXE image a second time, which would result in an endless boot loop.

If a client falls through all tests and ends up in the fallback section, it receives an address but no boot file. On the client side this usually shows up as a PXE timeout. Switching on Trace=1 shows the vendor class the client actually sent, which is the fastest way to find out which architecture number is missing from the configuration.

Why does IgnoreUnknownClients not work as expected?

uwe — Sat, 06 Sep 2014 12:03:31 +0000

Sometimes there is confusion about IgnoreUnknownClients. There are two settings that control the behavior of the DHCP server with respect to unknown clients: ConfigureUnknownClients and IgnoreUnknownClients. ConfigureUnknownClients controls whether an unknown client gets an entry automatically generated in the INI file based on IPPOOLs and so on. What makes a client a known client is any kind of client section in the INI file. This can be a client section with wildcards. This client section does not need to contain any IPADDR entry. The IPADDR entry is generated automatically. IgnoreUnknownClients controls how the DHCP server behaves in cases in which no client section is generated by the DHCP server. Sent a NAK to the requesting client or simple ignore the request. Example:

[00-40-8C-??-??-??] ; support only clients with mac address starting with 00-40-8C
AutoConfig=1
[Settings]
ConfigureUnknownClients=0
IgnoreUnknownClients=1

This tells the DHCP server to configure only clients with mac address 00-40-8C-??-??-?? and do not respond to any requests from other kind of clients.

Does the DHCP server support more than one ethernet card?

uwe — Sat, 06 Sep 2014 12:00:28 +0000

Yes. It automatically uses all NIC’s that it finds and listens for incoming DHCP requests. Windows 2000 (and later OSs) has a little bit of a different behavior than previous Windows operating systems. It doesn’t tell you the IP address of an adapter until it is physically connected. The DHCP server since V1.3 supports that as well by implicitly stopping and starting itself whenever a change in the IP configuration occurs.
You can also restrict the DHCP Server to certain cards by using the IPBIND_x entries in the [Settings] section or server “virtualization”.

Does the DHCP server support the BOOTP protocol?

uwe — Sat, 06 Sep 2014 11:58:25 +0000

Yes. The DHCP server implements the DHCP protocol. And since V1.8 also the BOOTP style requests are supported.

Is it possible to get the source code of the DHCP server?

uwe — Sat, 06 Sep 2014 11:57:14 +0000

DHCP Server for Windows is not open source and therefore the source code is not available for free.