APM-DHCP Access Policy Example and Detailed Instructions
Prepared with Mark Quevedo, F5 Principal Software Engineer
May, 2020
Sectional Navigation links
Important Version Notes || Installation Guide || What Is Going On Here? || Parameters You Set In Your APM Access Policy || Results of DHCP Request You Use in Access Policy || Compatibility Tips and Troubleshooting
Introduction
Ordinarily you assign an IP address to the “inside end” of an APM Network Tunnel (full VPN connection) from an address Lease Pool, from a static list, or from an LDAP or RADIUS attribute.
However, you may wish to assign an IP address you get from a DHCP server. Perhaps the DHCP server manages all available client addresses. Perhaps it handles dynamic DNS for named client workstations. Or perhaps the DHCP server assigns certain users specific IP addresses (for security filtering). Your DHCP server may even assign client DNS settings as well as IP addresses.
APM lacks DHCP address assignment support (though f5's old Firepass VPN had it ). We will use f5 iRules to enable DHCP with APM. We will send data from APM session variables to the DHCP server so it can issue the “right” IP address to each VPN tunnel based on user identity, client info, etc.
Important Version Notes
Version v4c includes important improvements and bug fixes. If you are using an older version, you should upgrade. Just import the template with “Overwrite existing templates” checked, then “reconfigure” your APM-DHCP Application Service—you can simply click “Finished” without changing any options to update the iRules in place.
Installation Guide
First install the APM-DHCP iApp template (file DHCP_for_APM.tmpl). Create a new Application Service as shown (choose any name you wish). Use the iApp to manage the APM-DHCP virtual servers you need. (The iApp will also install necessary iRules.)
You must define at least one APM-DHCP virtual server to receive and send DHCP packets. Usually an APM-DHCP virtual server needs an IP address on the subnet on which you expect your DHCP server(s) to assign client addresses. You may define additional APM-DHCP virtual servers to request IP addresses on additional subnets from DHCP. However, if your DHCP server(s) support subnet-selection (see session.dhcp.subnet below) then you may only need a single APM-DHCP virtual server and it may use any IP that can talk to your DHCP server(s).
It is best to give each APM-DHCP virtual server a unique IP address but you may use an BIG-IP Self IP as per SOL13896 . Ensure your APM and APM-DHCP virtual servers are in the same TMOS Traffic Group (if that is impossible set TMOS db key tmm.sessiondb.match_ha_unit to false).
Ensure that your APM-DHCP virtual server(s) and DHCP server(s) or relay(s) are reachable via the same BIG-IP route domain. Specify in your IP addresses any non-zero route-domains you are using (e.g., “192.168.0.20%3”)—this is essential.
(It is not mandatory to put your DHCP-related Access Policy Items into a Macro—but doing so makes the below screenshot less wide!)
Into your APM Access Policy, following your Logon Page and AD Auth (or XYZ Auth) Items (etc.) but before any (Full/Advanced/simple) Resource Assign Item which assigns the Network Access Resource (VPN), insert both Machine Info and Windows Info Items. (The Windows Info Item will not bother non-Windows clients.)
Next insert a Variable Assign Item and name it “DHCP Setup”. In your “DHCP Setup” Item, set any DHCP parameters (explained below) that you need as custom session variables. You must set session.dhcp.servers. You must also set session.dhcp.virtIP to the IP address of an APM-DHCP virtual server (either here or at some point before the “DHCP_Req” iRule Event Item).
Finally, insert an iRule Event Item (name it “DHCP Req”) and set its Agent ID to DHCP_req. Give it a Branch Rule “Got IP” using the expression “expr {[mcget {session.dhcp.address}] ne ""}” as illustrated. You must attach iRule ir-apm-policy-dhcp to your APM virtual server (the virtual server to which your clients connect).
Neither the Machine Info Item nor the Windows Info Item is mandatory. However, each gathers data which common DHCP servers want to see. By default DHCP_req will send that data, when available, to your DHCP servers.
See below for advanced options: DHCP protocol settings, data sent to DHCP server(s), etc. Typically your requests will include a user identifier from session.dhcp.subscriber_ID and client (machine or connection) identifiers from other parameters.
The client IP address assigned by DHCP will appear in session.dhcp.address. By default, the DHCP_req iRule Event handler will also copy that IP address into session.requested.clientip where the Network Access Resource will find it. You may override that behavior by setting session.dhcp.copy2var (see below).
Any “vendor-specific information” supplied by the DHCP server1 (keyed by the value of session.dhcp.vendor_class) will appear in variables session.dhcp.vinfo.N where N is a tag number (1-254). You may assign meanings to tag numbers.
Any DNS parameters the DHCP server supplies2 are in session.dhcp.dns_servers and session.dhcp.dns_suffix. If you want clients to use those DNS server(s) and/or DNS default search domain, put the name of every Network Access Resource your Access Policy may assign to the client into the session.dhcp.dns_na_list option.
NB: this solution does not renew DHCP address leases automatically, but it does release IP addresses obtained from DHCP after APM access sessions terminate.3 Please configure your DHCP server(s) for an address lease time longer than your APM Maximum Session Timeout.
Do not configure APM-DHCP virtual servers in different BIG-IP route domains so they share any part of a DHCP client IP range (address lease pool). For example, do not use two different APM-DHCP virtual servers 10.1.5.2%6 and 10.1.5.2%8 with one DHCP client IP range 10.1.5.10—10.1.5.250. APM-DHCP won’t recognize when two VPN sessions in different route domains get the same client IP from a non-route-domain-aware DHCP server, so it may not release their IP’s in proper sequence.
This solution releases DHCP address leases for terminated APM sessions every once in a while, when a new connection comes in to the APM virtual server (because the BIG IP only executes the relevant iRules on the “event” of each new connection). When traffic is sparse (say, in the middle of the night) there may be some delay in releasing addresses for dead sessions.
If ever you think this solution isn’t working properly, be sure to check the BIG IP’s LTM log for warning and error messages.
DHCP Setup (a Variable Assign Item) will look like:
Put the IP of (one of) your APM-DHCP virtual server(s) in session.dhcp.virtIP.
Your DHCP server list may contain addresses of DHCP servers or relays. You may list a directed broadcast address (e.g., “172.16.11.255”) instead of server addresses but that will generate extra network chatter.
To log information about DHCP processing for the current APM session you may set variable session.dhcp.debug to true (don’t leave it enabled when not debugging).
DHCP Req (an iRule Event Item) will look like:
Note DHCP Req branch rules:
If DHCP fails, you may wish to warn the user:
(It is not mandatory to Deny access after DHCP failure—you may substitute another address into session.requested.clientip or let the Network Access Resource use a Lease Pool.)
What is going on here?
We may send out DHCP request packets easily enough using iRules’ SIDEBAND functions, but it is difficult to collect DHCP replies using SIDEBAND.4 Instead, we must set up a distinct LTM virtual server to receive DHCP replies on UDP port 67 at a fixed address. We tell the DHCP server(s) we are a DHCP relay device so replies will come back to us directly (no broadcasting).5 For a nice explanation of the DHCP request process see http://technet.microsoft.com/en-us/library/cc940466.aspx. At this time, we support only IPv4, though adding IPv6 would require only toil, not genius.
By default, a DHCP server will assign a client IP on the subnet where the DHCP relay device (that is, your APM-DHCP virtual server) is homed. For example, if your APM-DHCP virtual server’s address were 172.30.4.2/22 the DHCP server would typically lease out a client IP on subnet 172.30.4.0. Moreover, the DHCP server will communicate directly with the relay-device IP so appropriate routes must exist and firewall rules must permit. If you expect to assign client IP’s to APM tunnel endpoints on multiple subnets you may need multiple APM-DHCP virtual servers (one per subnet). Alternatively, some but not all DHCP servers6 support the rfc3011 “subnet selection” or rfc3527 “subnet/link-selection sub-option” so you can request a client IP on a specified subnet using a single APM-DHCP virtual server (relay device) IP which is not homed on the target subnet but which can communicate easily with the DHCP server(s): see parameter session.dhcp.subnet below.
NOTE: The subnet(s) on which APM Network Access (VPN) tunnels are homed need not exist on any actual VLAN so long as routes to any such subnet(s) lead to your APM (BIG-IP) device. Suppose you wish to support 1000 simultaneous VPN connections and most of your corporate subnets are /24’s—but you don’t want to set up four subnets for VPN users. You could define a virtual subnet—say, 172.30.4.0/22—tell your DHCP server(s) to assign addresses from 172.30.4.3 thru 172.30.7.254 to clients, put an APM-DHCP virtual server on 172.30.4.2, and so long as your Layer-3 network knows that your APM BIG-IP is the gateway to 172.30.4.0/22, you’re golden.
When an APM Access Policy wants an IP address from DHCP, it will first set some parameters into APM session variables (especially the IP address(es) of one or more DHCP server(s)) using a Variable Assign Item, then use an iRule Event Item to invoke iRule Agent DHCP_req in ir apm policy dhcp. DHCP_req will send DHCPDISCOVERY packets to the specified DHCP server(s). The DHCP server(s) will reply to those packets via the APM-DHCP virtual-server, to which iRule ir apm dhcp must be attached. That iRule will finish the 4-packet DHCP handshake to lease an IP address. DHCP_req handles timeouts/retransmissions and copies the client IP address assigned by the DHCP server into APM session variables for the Access Policy to use.
We use the APM Session-ID as the DHCP transaction-ID XID and also (by default) in the value of chaddr to avert collisions and facilitate log tracing.
Parameters You Set In Your APM Access Policy
Required Parameters
session.dhcp.virtIP |
|
session.dhcp.servers |
|
Optional Parameters (including some DHCP Options)
NOTE: when you leave a parameter undefined or empty, a suitable value from the APM session environment may be substituted (see details below). The defaults produce good results in most cases. Unless otherwise noted, set parameters as Text values. To exclude a parameter entirely set its Text value to '' [two ASCII single-quotes] (equivalent to Custom Expression return {''} ). White-space and single-quotes are trimmed from the ends of parameter values, so '' indicates a nil value.
It is best to put “Machine Info” and “Windows Info” Items into your Access Policy ahead of your iRule Event “DHCP_req” Item (Windows Info is not available for Mac clients beginning at version 15.1.5 as they are no longer considered safe).
session.dhcp.debug |
|
session.dhcp.firepass |
|
session.dhcp.copy2var |
|
session.dhcp.dns_na_list |
|
session.dhcp.broadcast |
|
session.dhcp.vendor_class Option 60 |
|
session.dhcp.user_class Option 77 |
|
session.dhcp.client_ID Option 61 |
|
session.dhcp.hostname Option 12 |
|
session.dhcp.subscriber_ID Sub-option 6 of Option 82 |
|
session.dhcp.circuit_ID Sub-option 1 of Option 82 |
|
session.dhcp.remote_ID Sub-option 2 of Option 82 |
|
session.dhcp.subnet Option 118 Sub-option 5 of Option 82 |
|
session.dhcp.hwcode |
|
Results of DHCP Request For Use In Access Policy
session.dhcp.address <-- client IP address assigned by DHCP!
session.dhcp.message
session.dhcp.server, session.dhcp.relay
session.dhcp.expires, session.dhcp.issued
session.dhcp.lease, session.dhcp.rebind, session.dhcp.renew
session.dhcp.vinfo.N
session.dhcp.dns_servers, session.dhcp.dns_suffix
session.dhcp.xid, session.dhcp.hex_client_id, session.dhcp.hwx
If a DHCP request succeeds the client IP address appears in session.dhcp.address. If that is empty look in session.dhcp.message for an error message. The IP address of the DHCP server which issued (or refused) the client IP is in session.dhcp.server (if session.dhcp.relay differs then DHCP messages were relayed). Lease expiration time is in session.dhcp.expires. Variables session.dhcp.{lease, rebind, renew} indicate the duration of the address lease, plus the rebind and renew times, in seconds relative to the clock value in session.dhcp.issued (issued time).
See session.dhcp.vinfo.N where N is tag number for Option 43 vendor-specific information.
If the DHCP server sends client DNS server(s) and/or default search domain, those appear in session.dhcp.dns_servers and/or session.dhcp.dns_suffix.
To assist in log analysis and debugging, session.dhcp.xid contains the XID code used in the DHCP request. The client_ID value (if any) sent to the DHCP server(s) is in session.dhcp.hex_client_id. The DHCP request’s htype and chaddr values (in hex) are concatenated in session.dhcp.hwx.
Compatibility Tips and Troubleshooting
Concern | Response |
---|---|
My custom parameter seems to be ignored.
|
You should set most custom parameters as Text values (they may morph to Custom Expressions).
|
My users with Apple Mac Pro’s sometimes get no DHCP IP or a conflicting one. |
A few Apple laptops sometimes give the Machine Info Item bogus MAC addresses. Set session.dhcp.client_ID to “XIDMAC“ to use unique per-session identifiers for clients.
|
After a VPN session ends, I expect the very next session to reuse the same DHCP IP but that doesn’t happen. | Many DHCP servers cycle through all the client IP’s available for one subnet before reusing any. Also, after a session ends APM-DHCP takes a few minutes to release its DHCP IP. |
When I test APM-DHCP with APM VE running on VMware Workstation, none of my sessions gets an IP from DHCP. | VMware Workstation’s built-in DHCP server sends bogus DHCP packets. Use another DHCP server for testing (Linux dhcpd(8) is cheap and reliable). |
I use BIG-IP route domains and I notice that some of my VPN clients are getting duplicate DHCP IP addresses. | Decorate the IP addresses of your APM-DHCP virtual servers, both in the iApp and in session.dhcp.virtIP, with their route-domain ID’s in “percent notation” like “192.0.2.5%3”. |
APM-DHCP is not working. | Double-check your configuration. Look for errors in the LTM log. Set session.dhcp.debug to “true” before trying to start a VPN session, then examine DHCP debugging messages in the LTM log to see if you can figure out the problem. |
Even after looking at debugging messages in the log I still don’t know why APM-DHCP is not working. | Run “tcpdump –ne -i 0.0 -s0 port 67” to see where the DHCP handshake fails. Are DISCOVER packets sent? Do any DHCP servers reply with OFFER packets? Is a REQUEST sent to accept an OFFER? Does the DHCP server ACK that REQUEST? If you see an OFFER but no REQUEST, check for bogus multicast MAC addresses in the OFFER packet. If no OFFER follows DISCOVER, what does the DHCP server’s log show? Is there a valid zone/lease-pool for you? Check the network path for routing errors, hostile firewall rules, or DHCP relay issues. |
Endnotes
- In DHCP Option 43 (rfc2132).
- In DHCP Options 6 and 15 (rfc2132).
- Prior to version v3h, under certain circumstances with some DHCP servers, address-release delays could cause two active sessions to get the same IP address.
- And even more difficult using [listen], for those of you in the back of the room.
- A bug in some versions of VMware Workstation’s DHCP server makes this solution appear to fail. The broken DHCP server sends messages to DHCP relays in unicast IP packets encapsulated in broadcast MAC frames. A normal BIG-IP virtual server will not receive such packets.
- As of Winter 2017 the ISC, Cisco, and MS Windows Server 2016 DHCP servers support the subnet/link selection options but older Windows Server and Infoblox DHCP servers do not.
Supporting Files - Download attached ZIP File Here.
- Enrique_PernasNimbostratus
My regional support contacts at F5 confirmed today that iapp is supported for versions v16 to v17. They have also requested to update the supported versions in the article https://my.f5.com/manage/s/article/K000135007 ("K000135007: Configure dynamic DNS from a DHCP server for BIG-IP APM network access clients") and you can check that the versions v16 to v17 are already shown.
On the other hand comment also as suggested to take into account that if the DHCP windows server is used and you use rfc3011 “subnet selection” or rfc3527 “subnet/link-selection sub-option”, to avoid receiving DHCPACKs it is essential to create in the DHCP windows server a “dummy DHCP Scope” (as in: all addresses excluded) for an IP range covering all possible DHCP relay's source addresses, as it is commented here https://learn. microsoft.com/en-us/archive/msdn-technet-forums/20e50652-5a19-4dee-a6af-4c09f3fcfd1b to prevent the F5 from being considered by the windows DHCP server as a “rogue relay agent”.
- Barny_RichesAltostratus
Can I get clarification as to whether this works on BIG-IP 17.1.x? We need to migrate VPN users to our primary DHCP server, as client-based dynamic DNS registration needs to be disabled to meet security requirements.
- Man_YauCirrus
Hi Barny_Riches,
We have been running VE F5 APM on 17.1.1.2 for a year now with this Iapp. We had no issues with it, do you run into some isssues.
- Barny_RichesAltostratus
Thank you Man_Yau, that is very encouraging. I have yet to deploy the iApp but having read comments about support for v16.x I wanted to confirm whether it was possible before deploying it. Thank you for your feedback.
- Enrique_PernasNimbostratus
I'm sorry but I haven't heard back from anyone and I can't help you. I have tried it on lab VE APM 16.1.3.1 and after messing around with the configuration I managed to get it to work, even with the F5 APM machine tunnel (https://community.f5.com/kb/technicalarticles/f5-big-ip-access-policy-manager-apm-machine-tunnels-for-windows/310896).
It is advisable to check this Microsoft article to avoid conflicts and errors (RegistrationOverwite 2) in DNS registration vía DHCP:https://learn.microsoft.com/en-us/troubleshoot/windows-server/networking/dns-registration-behavior-when-dhcp-server-manages-dynamic-dns-updates
, as well as take a look at this script, if you are going to change to a dynamic DNS registration via DHCP:
https://byronwright.blogspot.com/2021/08/script-to-update-dns-record-permissions.html
I hope this message will be of some help to you.
- Barny_RichesAltostratus
Thank you for your advice Enrique. Again, your success in using this on 16.1.x is very encouraging. I appreciate the other links also.
- Enrique_PernasNimbostratus
Chase_Abbott I was wondering if there was any word about this ("DHCP with APM") being supported on v16 and v17?. BIG-IP 15.1.x will reach the End of Life (EoL) milestone on December 31, 2024 ( F5 strongly encourages us to plan ahead and upgrade to the latest BIG-IP release, 17.1.x https://my.f5.com/manage/s/article/K000139937).
Recently f5 published this article: "K000135007: Configure dynamic DNS from a DHCP server for BIG-IP APM network access clients https://my.f5.com/manage/s/article/K000135007"
which can only be applied in these versions "15.1.8, 15.1.7, 15.1.6, 15.1.5, 15.1.4, 15.1.3, 15.1.2, 15.1.1, 15.1.0, 15.1.X, 14.1.5, 14.1.4, 14.1.3, 14.1.2, 14.1.0, 14.1.X" due to the incompatibility of the DHCP APM function with the iapp template. F5, when will be avalaible a DHCP solution in F5 APM on v16 and on v17?Thanks for your response.
- JHDUKEAltostratus
I've successfully configured on 17.1.1.2 Build 0.0.10 Point Release 2 using the v4v*.zip and documentation provided.
- Enrique_PernasNimbostratus
....
- Thanawoot_SONGTEmployee
I downloaded and tested on 16 June 2023. Firstly installed to v15.1.9, working properly. Then upgraded to the latest v16.1.3.X (not publicly release yet at the wring time), working properly too. I haven't tested on v16.1.3.4 or earlier.
- Chase_AbbottEmployee
K4ZI There are a few remaining issues that are being worked on before this can be validated against v16. As for alternative solutions, I am not aware of any at this time.
If someone has one, I hope they publish it here! 😎
- K4ZINimbostratus
Chase_Abbott Awesome write up. I was wondering if there was any word on this being supported on v16? This looks to be exactly what I need to support a project I'm working on. Are there other alternatives known at this time to get this working on v16?
Also to echo JulienL question, is it known if this will work with a machine tunnel? I wouldn't think this would be an issue, but can't verify for myself as I'm on V16 🙂. - Chase_AbbottEmployee
JHDUKE and Man_Yau, thanks for the heads up on this.
We checked it out and are working on a solution for v16+. I updated the article to prevent others from running into the same issue and we'll update the article when we have a working solution for this. It may take a bit but we know where the issues are. If you haven't already, subscribe to this article so you're notified when it's updated.
Thanks again!
-ChaseA & MarkQ
- JHDUKEAltostratus
I've had success installing and configuring the necessary items to end up with a functional implementation on version 14.1*. However, I've also got an F5 VE running 16.1.2.2 Build 0.0.28 Point Release 2 that will not install the template which appears to be related to compatibility issues based on the error (see below).
----Loading configuration... Data Input Error:(/tmp/upload_template.tmpl at line: 0) Invalid version:12.0.0: Supported cli versions: 14.0.0 14.0.1 14.1.0 14.1.1 14.1.2 14.1.3 14.1.4 14.1.4.1 15.0.0 15.0.1 15.1.0 15.1.1 15.1.2 15.1.3 16.0.0 16.0.1 16.1.0 16.1.1 16.1.2 16.1.2.2 -----
On the VE running 16.1.2.2, I've manually created the necessary items that are created using the template and the client is being issued DHCP from the external source as expected. However, the client will not complete the connection and build the tunnel resulting in the session looping during the connection with this error in the session logs.
----Common:5055ac47:bdd1b3b0: TunnelStats: PPP_LISTENER_ERRORS 10,LCP_UNKNOWN_OPTIONS 1,LCP_PROTO_REJ 1,FSM_UNEXPECTED_DOWN 1,FSM_UNEXPECTED_FRAME 1,IPCP_FAILED 1,----
Has anyone had success with this version and build?
- Man_YauCirrus
Hello,
i have also installed a virtual F5, that is running version 16.1.2.2. I also get the same error message: TCL error: /Common/ir-apm-dhcp <CLIENT_ACCEPTED> - can't read "dhcp_state": no such variable while executing "log local0.info "${me}: discarding surplus BOOTREPLY for ${xid} from ${relay}, dhcp_state=${dhcp_state}""
any idea how to solve it or is the new version available?
Thanks.
Regards,
ManYau