CloneDeploy

OS Deployment

 

Latest Version: 1.4.0

I. What Is CloneDeploy Proxy DHCP

CloneDeploy Proxy DHCP is a service I created to aid in / provide enhanced functionality to the PXE boot / Apple NetBoot process.  When used in conjunction with any DHCP server, TFTP server and Web server, it provides booting over the network for legacy bios computers, efi computers, and Apple computers, all at the same time.  You could think of it as a way to dynamically set tftp-server (option 66) and bootfile (option 67) based on the type of client computer.  It was designed to operate specifically with CloneDeploy, but could also be used as a standalone proxy dhcp server in any manner you see fit.  Additionally, the proxy server does not require you to set DHCP options on your current DHCP server scope.  This is useful in situations like a home router where boot options cannot be set, or where policies prevent changing the existing DHCP options in your network.  Finally, if needed, each individual computer can be assigned a specific boot server and boot file.  It is also important to remember that CloneDeploy Proxy DHCP is not a standalone PXE or NetBoot server.  It is just one piece of the puzzle, but when used with CloneDeploy it does provide a full PXE boot / Apple NetBoot solution.

CloneDeploy Proxy DHCP operates in a similar manner to a traditional DHCP server except for two things. First, it does not hand out ip addresses. For PC PXE booting, It only sends the next-server and bootfile to client requests.  For Apple NetBoot it sends the NBI list.  Second, it only responds to PXE Boot / NetBoot requests. It can be installed machine in your environment.  It does not need to be installed on your CloneDeploy Server, but it can if you want to.

PC PXE Operation When Installed On A Different Server Than Your DHCP Server (Recommended Implementation)

If using CloneDeploy with multiple subnets / vlans,  you must add an IP Helper pointing to the proxy dhcp server with this method.

Traditionally when a client requests an ip address, it will send out a discover broadcast to port 67 asking for a dhcp offer. Your dhcp server will respond with the ip address among other things. The Proxy Server will also be listening on port 67 but on another server and will also send out an offer, but only if it is a PXE boot request. The proxy offer will only include the server identifier and and option 60 with a value of PXEClient. Once the client receives this offer it will realize that option 60 has been set to PXEClient. This instructs the client to send another request to the Proxy DHCP server on port 4011 to get the boot options.  The proxy server is also listening on port 4011.  CloneDeploy Proxy DHCP  will then send an acknowledgement to the client with the ip address of your tftp server and boot file name based on the settings in config.ini

 

PC PXE Operation When Installed On Same Server as DHCP

This method does not require any additional IP Helpers because there should already be one pointing to the DHCP server.

If installing on an existing DHCP server, port 67 is already in use and the proxy cannot bind to respond to discover requests. You must set listen-dhcp to false in CloneDeploy Proxy DHCP and set option 60 to PXEClient on the DHCP server.

In this mode, CloneDeploy Proxy DHCP only listens on port 4011.

Apple Netboot cannot be used this way

Apple Operation

 

If using CloneDeploy Proxy for Apple NetBoot, you must be able to bind to port 67.  It does not listen on port 4011 like PC PXE booting.  It cannot be used on an existing DHCP Server.  Review the PC operations above for more info.  It responds to DHCP Inform requests and sends the appropriate NBI list, as well as the Tftp Server Address and the Web Server path for the NetBoot Image.

When using the proxy server for Apple NetBoot, multiple servers are supported, as well as load balancing among the servers.  It supports setting the startup disk by holding the N key during bootup or from the boot selection screen when holding option during boot.  It also supports using the startup preference pane.  It may or may not work with Apple NetBoot servers that are not served via CloneDeploy.  It depends how they are implemented.  For example when using multiple CloneDeploy proxy servers, each one is smart enough to know to only respond to requests intended for that specific server.  If you are using something like JAMF NetSUS, it is unaware that multiple servers are in use, and always responds to requests even if not intended for it.  The easiest solution if you are using an incompatible server is to let CloneDeploy host those NBI’s also.

Network Considerations

CloneDeploy Proxy DHCP follows the same rules as a traditional DHCP server in the sense of broadcast domains. It will only be visible to clients within the same subnet or vlan. If you need to access it from other segments you must add an ip helper to your switch / router to allow the broadcasts to travel across the broadcast domain. You will end with two ip helpers, one for your DHCP server and one for the CloneDeploy Proxy DHCP server.

Limitations

CloneDeploy Proxy will not override options that are already set by your DHCP server. If you have already set option 60, 66 or 67, you must remove them before it will work. In addition to this, some DHCP servers incorrectly set the next-server to be themselves even if you have not set it. These will not work because options cannot be overridden.

II. Usage

CloneDeploy Proxy DHCP can be installed as a service on Windows or a Daemon in Linux or run in console mode from a cmd prompt or terminal. It requires .NET 4.0 or newer or Mono 4.0 or newer.  Before you begin:

  • Ensure ports 67 and 4011 are open
  • Modify config.ini to your liking. Directions are in config.ini or see next section
  • If you are using an OS Version that blocks untrusted sources, you must right click cd_proxyd.exe, select properties, and unblock it.

Cmd Line Arguments

        --version        Displays the current version
        --generate       Generates the apple-vendor-specific-information string for Apple NetBoot
        --install        Installs service on Windows
        --uninstall      Uninstalls service on Windows
        --console        Run application in console mode without installing service
        --debug          Run the application in console mode with debug output without installing service
        --daemon         Run the application for unix in daemon mode for use with Upstart, Systemd, etc.
        --help           Displays this menu

Configuration Files

There are 4 configuration files that can be used with CloneDeploy Proxy DHCP.  Config.ini is the only one that is required.  When running in service mode, the service must be restarted when any of the config files are changed.

config.ini

;Config File For CloneDeploy Proxy DHCP Server

[settings]

; LISTEN-DHCP sets the server to listen for pxe boot dhcp offers and apple netboot dhcp informs on port 67
; Must be true in order for Apple NetBoot to work
; Can be false if not using Apple NetBoot and the CloneDeploy Proxy DHCP is installed on the same server as your DHCP Server and option 60 is set to PXEClient on that DHCP Server
; Valid values: true | false
 
listen-dhcp=true

; LISTEN-PROXY sets the server to listen for pxe boot proxy dhcp requests on port 4011
; Must be true for PXE booting
; Apple NetBoot does not use this port
; Valid values: true | false

listen-proxy=true

; LISTEN-APPLE-BSDP sets the server to listen for Apple NetBoot Inform Requests
; Must be true to use with Apple NetBoot
; listen-dhcp must also be true when this is true
; Valid values: true | false

listen-apple-bsdp=true

; INTERFACE sets the nic you want to listen on.
; Any interface can be specified with 0.0.0.0
; If running on Linux with Mono, you must use 0.0.0.0
; When binding to the interface, it is possible to reuse the port if there is already an existing DHCP Server on the same machine, with some limitations
; -- This lets you use the CloneDeploy Proxy DHCP on an isolated network with only a single machine for both DHCP services and Proxy DHCP services, but ideally should be on it's own machine with an ip helper pointing to it
; -- Not all DHCP servers support this, if CloneDeploy Proxy DHCP cannot bind, it will let you know
; -- Requests that are fowarded by a relay or ip helper, will not work when CloneDeploy Proxy DHCP is bound to the same interface that a DHCP Server is already using
; ----- It will only respond to requests in the same subnet / vlan
; Valid values: A single IPv4 address | 0.0.0.0

interface=192.168.56.1

; NEXT-SERVER sets the IPv4 address of the tftp server
; Value is required for both PXE and Apple NetBoot
; Valid values: A single IPv4 address

next-server=192.168.56.1

; CLONEDEPLOY-SERVICE-URL sets the optional url to check for boot reservations on CloneDeploy
; Used to set specific boot files for specific computers
; Comment out to disable 
; Valid Value: Your CloneDeploy Web Service from CloneDeploy Web Interface ->Admin->Server->Web Service

;clonedeploy-service-url=http://192.168.56.1/clonedeploy/service/client.asmx/

; ALLOW-ALL-MAC sets the server to respond to all pxe boot or netboot requests or limit to only those set in the allow file
; Valid values true | false

allow-all-mac=true

; BIOS-BOOTFILE sets the file that is loaded for legacy bios clients, both x86 and x64
; Path is relative to your tftp base folder
; If using with CloneDeploy, it should always be proxy/bios/pxeboot.0

bios-bootfile=proxy/bios/pxeboot.0

; EFI32-BOOTFILE sets the file that is loaded for efi x86 clients
; Path is relative to your tftp base folder
; If using with CloneDeploy, it should always be proxy/efi32/pxeboot.0

efi32-bootfile=proxy/efi32/pxeboot.0

; EFI64-BOOTFILE sets the file that is loaded for efi x64 clients
; Path is relative to your tftp base folder
; If using with CloneDeploy, it should always be proxy/efi64/pxeboot.0

efi64-bootfile=/proxy/efi64/pxeboot.0

; APPLE-EFI-BOOT-FILE sets the boot file on Apple NetBoot when not using a macOS NBI. Ex: The CloneDeploy Linux Imaging Environment
; This file is only loaded if an nbi is selected with an id of 3913 or 39131
; This feature enables NetBooting to both an Apple NBI and the Linux Environment while using only a single CloneDeploy Proxy DHCP Server
; If using with CloneDeploy, it should always be proxy/efi64/ipxe.efi

apple-efi-boot-file=proxy/efi64/ipxe.efi

; APPLE-BOOT-FILE sets the boot file on Apple NetBoot when a macOS NBI is selected.
; Path is relative to your tftp base folder
; [nbi-id] is a placeholder for the selected NBI from the Apple Boot Menu
; If using with CloneDeploy, it should always be [nbi_id]/i386/booter

apple-boot-file=[nbi_id]/i386/booter

; APPLE-ROOT-PATH sets the location of the NBI .dmg folder for Apple NetBoot - Only supports serving over http - No NFS
; [nbi-id] is a placeholder for the selected NBI from the Apple Boot Menu
; If using with CloneDeploy, it should always be http://clonedeploy-server-ip/clonedeploy/public/macos_nbis/[nbi_id]/NetBoot.dmg

apple-root-path=http://192.168.56.1/clonedeploy/public/macos_nbis/[nbi_id]/NetBoot.dmg

; APPLE-VENDOR-SPECIFIC-INFORMATION sets the NBI list boot menu for Apple NetBoot
; If using with CloneDeploy, it should be generated from the CloneDeploy Web Interface->Admin->BootMenu->Apple NetBoot
; If not using with CloneDeploy, you can generate it by filling in the vendor-specific-info-generator section below and running with the --generate argument

apple-vendor-specific-information=

; SERVER-IDENTIFIER-OVERRIDE sets the Server Identifier
; By default this value is set to the inteface value when empty, except in cases where it cannot be, such as an interface set to 0.0.0.0
; Valid values: A single IPv4 address

server-identifier-override=

; The Following section is used to generate the apple-vendor-specific-information string for use with Apple NetBooting when CloneDeploy Proxy DHCP is ran with the --generate argument
; This Should Only be filled in if using without CloneDeploy
; It supports adding up to 5 boot options to the Apple NetBoot Menu
; NETBOOT-SERVER-IP sets the CloneDeploy Proxy DHCP that should be targeted when a boot Menu selection is selected
; NETBOOT-SERVER-IP should match either the interface value or the apple-target-ip-override value
; Id Values for a single CloneDeploy Proxy DHCP Server must be unique
; Id Values for an NBI being served from a single server must be b/w 1-4095 
; Id Values for an NBI being served from multiple servers for load balancing must be b/w 4096-65535
; An id with the a value of 3913 or 39131 will load the apple-efi-boot-file, any other value will load the apple-boot-file
; Name values can be any name you want to display on the Apple NetBoot Boot Menu
; Name values should not contain spaces or special characters
[vendor-specific-info-generator]

netboot-server-ip=

apple_nbi_id_1=
apple_nbi_name_1=

apple_nbi_id_2=
apple_nbi_name_2=

apple_nbi_id_3=
apple_nbi_name_3=

apple_nbi_id_4=
apple_nbi_name_4=

apple_nbi_id_5=
apple_nbi_name_5=

allow

This file contains a list of mac addresses that the proxy server will respond to.   This file is ignored unless allow-all-mac is set to false in the config.ini.

deny

This file contains a list of mac addresses that the proxy server should not respond to.  This file can be used if the allow-all-mac setting is true or false.  This list always overrides the allow list.

reservations

This file contains a list of mac address reservations for the proxy server. This can be used send specific clients to specific Tftp servers or boot files.  Settings for individual computers listed here will override the default global settings for only those computers.

 

III. Integrating With CloneDeploy Server

Integrating with CloneDeploy is very simple. Ensure you have read section I and II above to understand how it works. The tftpboot directory structure is already setup to work with the proxy dhcp server, and the config.ini file already has the boot files set correctly. You just need to do the following:

  • Set the interface to the ip of the nic you wan to bind to in the config.ini
  • Set the next-server to your CloneDeploy server ip in the config.ini
  • If using for Apple computers, update the ip address in apple-root-path to your CloneDeploy server ip in config.ini
  • In the CloneDeploy Web Inteface, select Admin->PXE->Using Proxy DHCP->Yes
  • Create the default global boot files when prompted.

I recommend running the proxy server in console debug mode while you are first getting started.  Then move to service mode after you confirm everything is working.

in Additional Help
19 10