[HOW TO] usb tether on pfsense 2.4 as router

  • This is a short guide on how to usb tether a android phone to pfsense and then have pfsense provide internet access to your lan over the tethered connection.

    This sadly requires a custom kernel, I can provide the kernel here for download (pfsense 2.4) if permission is granted by the pfsense staff.

    1 - Prepare a FreeBSD 11.0 machine to use for building the kernel, it can be physical or virtual doesnt matter.  No ports or packages need to be installed, it can be built using base tools in the OS.

    2 - Download/clone the pfsense fork of the freebsd src-tree from github, located here, make sure to use master branch https://github.com/pfsense/FreeBSD-src to the build machine.

    3 - cd in the FreeBSD-src folder, in my case its '/root/work/pfsense/pfsense/tmp/FreeBSD-src' as I cloned into /root/work

    4 - run this command 'make buildkernel KERNCONF=pfSense' this will compile the kernel so wait a while.

    5 - then run this command after its done to copy the kernel somewhere, e.g. to /root/work/pfsense/kernel 'make installkernel KERNCONF=pfSense KODIR=/root/work/pfsense/kernel'

    6 - cd into the directory above the kernel so e.g. 'cd /root/work/pfsense'

    7 - tarball the kernel ' tar -zcvf kernel.tar.gz kernel'

    8 - put the tarball on your pfsense unit in /boot

    9 - rename current kernel to something like kernel.stock so 'mv kernel kernel.stock'  this means if for some reason the kernel doesnt boot you can still manually boot to the stock kernel.

    10 - untar the kernel and delete the tarball, so 'tar -zxvf kernel.tar.gz' and 'rm kernel.tar.gz'

    11 - reboot

    At this point you are booted into the new kernel.  The difference between this kernel and the stock is you now have all the modules, the actual kernel is the same.

    12 - load the following 2 modules as follows
    'kldload if_urndis'
    'kldload if_ipheth'

    13 - Plugin in the phone to a usb port.

    14 - Enable mobile data mode and then enable usb tether on the phone.  At this point a ue0 device should appear in ifconfig but it wont have an ip address yet.

    15 - In the pfsense gui navigate to interface assigments and assign one of the OPT devices to ue0.

    16 - Now edit the OPT device and select DHCP for ipv4, then save and apply.  At this point ue0 should get an ip address.

    17 - Navigate to routing settings.

    18 - Choose edit for the OPT_DHCP device, and tick default gateway box, save and apply.

    19 - you should now be online on the pfsense unit and lan devices that use pfsense as their gateway.

    Additional notes.

    1 - You may need to add a firewall rule for the opt device to allow traffic,
    2 - If you dont want it as the default gateway then you can adjust the gateway settings differently.

  • Have you verified that a custom kernel is actually needed? Last time I tested USB tethering on pfSense I was able to just copy the kernel modules from a FreeBSD distribution set and load them into pfSense without any modifications anywhere.

  • well what you did would work also.

    by custom kernel I meant custom kernel package, so the kernel and the modules.

    Generally its not a good idea to just grab modules from elsewhere that have not been compiled with the same kernel.

    Feel free to add the steps to do what you did to help others.

  • As far as I know pfSense makes no modifications to the KPI/KBI (kernel programming/binary interface) so it is safe to grab modules from the matching FreeBSD version and use them. Modules compiled for a different version of FreeBSD is not adviseable of course.

  • Word of warning.

    I rebooted my pfsense box earlier, and pfsense flipped out over a interface mismatch, it wouldnt finish booting without me reassigning the interfaces (same as on a first boot), I assume this occured as I had opt3 assigned to ue0, but ue0 didnt exist during the boot process.  After it booted all my previous OPT interfaces had been lost, I restored them from a backup.

    I will test tomorrow if its ok rebooting after first manually removing ue0 from its OPT interface.

  • You can add these lines to /boot/loader.conf.local to make the modules load automatically on boot:


    There's still one more caveat. The phone must be in USB tethering mode when system is booted or no interface will be created and you again get an interface mismatch on boot.

  • yep, sadly my phone auto disables tethering during the reboot tho as when it detects a usb disconnection it auto flips it to off.

    For me its not a big deal, but I just posted the warning for others.  What I do now is just remove the opt device, I can keep the gateway preserved in the routing settings no problem tho.  So on a new tether I only need to add the OPT3 again.

  • Reviving this older thread to ask two –almost certainly noob'ish --questions:

    1. is it possible to find the pre-compiled kernel modules anywhere (IE: anywhere trusted)?
    2. are kernel modules platform-specific? I assume so
      2.5) assuming so - anyone know of a place to find them for the ARM chip used in the SG-1000? Or...
      2.5.5) are there virtual platforms (like virtual box) where one could download the ARM compatible source for the kernel and compile the modules oneself?


    edited to add - resolved for now :)
    Got some good insight here https://www.reddit.com/r/PFSENSE/comments/7xtyo0/any_way_to_tether_an_iphone_to_a_sg1000_looking/

    While I got gung-ho to learn some new BSD skills, it seems like the best move is to wait for a bit to see if this module makes it way into a stable build for the ARM platform.

    Thanks everyone for the work you are doing!

  • Hi, I just made an account to say thanks for this helpful thread, and to let others who might land here know that, as of pfSense 2.4.5, you no longer need to compile the kernel modules - the if_urndis and if_ipheth modules are now included by default.

    Also, regarding the phone switching off USB tethering when the pfSense box reboots, recent versions of Android allow you to automatically turn on USB tethering when a USB device is connected. First you have to enable Developer Mode, then in Developer Options you can change the "Default USB configuration" to tethering / hotspot. This should activate tethering as soon as the USB connection is made, so the ue0 device will hopefully be present by the time the the system boots and tries to use the interface. I'm not sure what Android version this was added in; so far I've only confirmed that it works on a Pixel 3a running Android 10.

    Cheers :)

  • very useful information. Thank you very much!!

  • @yusef
    can you confirm if you still have to do the following to make this work :

    @kpa said in [HOW TO] usb tether on pfsense 2.4 as router:

    You can add these lines to /boot/loader.conf.local to make the modules load automatically on boot:


    There's still one more caveat. The phone must be in USB tethering mode when system is booted or no interface will be created and you again get an interface mismatch on boot.

  • @yusef I don't see the modules in 2.4.5_1. I have tried manually loading them and including the load configs in /boot/loader.conf.local, and they are not being loaded. Are you sure these are included now?

  • @ServerTeam I can verify that on 2.4.5-RELEASE-p1 (amd64)
    built on Tue Jun 02 17:51:17 EDT 2020
    FreeBSD 11.3-STABLE you do NOT need to use the lines in /boot/loader.conf.local


    I usb tethered without it from my android device.

  • @good4y0u I wonder if this is the difference between arm and amd64. I have a SG-3100 appliance and I can't get the ue0 interface to come up.

    [2.4.5-RELEASE][root@system]/root: uname -a
    FreeBSD system 11.3-STABLE FreeBSD 11.3-STABLE #238 885b1ed26b6(factory-RELENG_2_4_5): Tue Jun  2 17:52:40 EDT 2020     root@buildbot1-nyi.netgate.com:/build/factory-crossbuild-245-armv6/obj/armv6/kJlGauaG/arm.armv6/build/factory-crossbuild-245-armv6/sources/FreeBSD-src/sys/pfSense-SG-3100  arm
    [2.4.5-RELEASE][root@system]/root: cat /etc/version

    It really appears these modules are not included in this build.

Log in to reply