[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!

Log in to reply