FreeBSD GSoC 2025 Proposal

Muhammad Saheed

1. General Information

Name Muhammad Saheed
Email muhammad.saheed.iam AT gmail DOT com
Phone [REDACTED]
IRC unwrapped_monad at libera.chat
GitHub https://github.com/MainKt
Time zone Indian Standard Time, UTC+05:30

I can work full-time on the project, dedicating around 40 hours per week with no other obligations for the summer.

My semester exams are scheduled from June 9 to June 20, and I have already discussed this with my mentor. It's flexible with their schedule.

The project can begin on the official start date of June 2, with a brief pause for exams. I will resume the work on June 21.

I will stay in regular contact with my mentors and the FreeBSD community over mailing lists, IRC and discord. and I'll aim to provide a day-by-day schedule before the program starts.

1.1. Biography

I am part of The sceptix club in my college; it's a student club promoting Linux and FOSS. In my free time, I love to rice and optimize my workflow with vim, window managers and learning various CLIs but maybe it's wise to not spend too much time ricing :D. I like systems programming and building low level stuff.

My prior open-source contributions including maintaining the dk window manager package on Void Linux and fixing Swift LSP config in nvim-lspconfig. I made a FreeBSD port for dk: Bug 285874.

I have FreeBSD in my old laptop, it has been a few month and have been using it as a home-server. I have been playing around with ports and jails and really been loving the vast package collection and Makefile configurations like bsd.prog.mk. I have built the kernel and the world (buildkernel and buildworld) in my other machine in around 2 mins and 26 mins respectively.

I try to build and rewrite tools in Rust and Zig but lately found C much more cooler while going through /usr/src. I have written simple CLIs and X11 tools. I built a simple CLI WiFi util for FreeBSD called wutil in C and have been trying to build a TUI library in C based on libvaxis, shinsentui, it's still very early though. I have read the style(9) and have tried to follow it in my code.

1.2. Mentors

Getz Mikalsen will be the mentor and Aymeric Wibo will the co-mentor. We have discussed the project on IRC and mail

2. WiFi and Network Management CLI/TUI Utility

2.1. Project Description

The project aims to build a CLI with a clean looking TUI in C for easier WiFi and Network Management on FreeBSD. The project will try to avoid unnecessary dependencies so that it's possible to add it to the FreeBSD base in the future. I've built a simple CLI utility called wutil as a prototype based on GhostBSD's NetworkMgr. It currently just wraps around the ifconfig and wpa_supplicant with features like scanning, connecting/disconnecting networks, configuring wpa_supplicant.conf for the network and managing network card configurations.

But the GSoC project will aim to build a better CLI that makes use of libfconfig and possibly extend libfconfig with lacking features necessary to implement the functionalities without shell calling ifconfig. This utility will also include a REPL interface like iwctl. We will be avoiding ncurses and using terminal raw mode and escape sequences for building the TUI, The "Uncooked" Terminal IO way.

2.1.1. Technical Approach

2.1.1.1. Base features
Listing network interfaces and their status

wutil currently shell calls ifconfig and does string manipulation over it's output to retrieve the interfaces and their status. We'll switch over to libifconfig's helper utilities to get this information instead using ifconfig_foreach_iface(...), ifconfig_get_ifstatus(...) etc like shown in /usr/src/share/examples/libifconfig/status.c.

Virtual interface creation

libifconfig provides ifconfig_create_interface_vlan(...), ifconfig_destroy_interface(...) for this. So we can abstract the boring wlan0 virtual interface creation part on new FreeBSD installs when connecting to WiFi.

Enable, disable, and restart Network Interfaces

We can enable/disable an interface like ifconfig IF up/down by toggling the IFF_UP flag of the interface's ifaddrs using a SIOCSIFFLAGS ioctl(...) call. ifconfig does this internally, this should be extracted in libifconfig as a small helper function. See /usr/src/sbin/ifconfig/ifconfig.c:2071 basic_cmds and /usr/src/sbin/ifconfig/ifconfig.c:1418 setiffags(...).

Scanning for networks

libifconfig currently doesn't have a way to scan for wireless networks but /usr/src/sbin/ifconfig/ifieee80211.c:3745 ifconfig uses lib80211_get80211len from lib80211/lib80211_ioctl.h which is a wrapper around SIOCG80211 ioctl(...) with a ieee80211req of the type IEEE80211_IOC_SCAN_RESULTS. We can cast the output buffer to a struct ieee80211req_scan_result to get all the proper offsets, SSID length, capabilities, beacon interval and noise etc. With this we can parse and retrieve SSID and 802.11 Information Elements (IEs). We will have to extract this into a libifconfig function to easily scan and retrieve these network information on wireless interfaces.

wpa_supplicant.conf configurations

Before connecting to a WiFi network, we gotta write a configuration for it in /etc/wpa_supplicant.conf. In wutil, we check for the IE, RSN to determine if it's a WPA2 network. We store configuration for all networks in /etc/wpa_supplicant.conf, which is messy when adding, removing or editing a network. For this project, I feel it's better to have separate config file for each network in /etc/wpa_supplicant/.

Connecting/disconnecting networks

In wutil, for connecting to a network, we kill all wpa_supplicant processes and set the network's SSID via ifconfig IF ssid SSID and restart wpa_supplicant with the connecting network's wpa_supplicant.conf. When disconnecting, we bring down the interface with ifconfig and set it's SSID to none and bring it back up. We will have to extract /usr/src/sbin/ifconfig/ifieee80211.c:604 set80211ssid(...), which is a wrapper around lib80211_set80211(...) for SIOCS80211 ioctl(...). from ifconfig into libifconfig.

Network interface configuration

We will be handling DNS and search domain configurations in /etc/resolv.d same as wutil and NetworkMgr. For manually configuring the IP, netmask and MAC we will have to build helpers around SIOCAIFADDR and SIOCDIFADDR ioctl(...)s in libifconfig. Option to automatically configure these with DHCP will also be provided. NetworkMgr persists these configurations with a sysrc call in rc.conf, but we will be avoiding writing to rc.conf and only print the instructions so that the user can do it themselves if they want to.

Random MAC generation

We can provide option to generate legitimate MAC address for both LAN and WLAN with OUI first three octets like how it's done in network.sh by vermaden.

I would also love to support WWAN like network.sh but I don't have a device to test it out :^).

We will be handling operations which require root like ifconfig, that is to fail the operation and handle the errors if possible.

2.1.1.2. The TUI

We will be using termios to put the terminal in non-canonical input mode and using control sequences, switch to an alternative buffer to draw the UI. The ctlseqs.zig in libvaxis lists a lot of control sequences we could use to color and design the TUI. We will poll the /dev/tty file descriptor and buffer the input for parsing. On exit, we will restore the terminal state as it was before opening the TUI. The TUI will provide all the above listed base features and will try to mimic nmtui's functionalities on linux but much more cleaner.

2.1.2. Significance for FreeBSD

A network management utility would be very helpful for everyday desktop and laptop users. Extracting the wireless interface related parts from ifconfig to libifconfig will be very useful to use these features programmatically can help in simplifying ifconfig codebase in the future. Maybe we could also extract the TUI parts into a simple library with all basic stuffs needed to build similar TUIs in the future without relying on ncurses.

I hope it will be a stepping stone to bring about the year of FreeBSD on desktop.

I am committed to becoming a long-term FreeBSD contributor, actively maintaining the contributed code and I wish to contribute drivers and even more utilities to make FreeBSD better on my main machine, It has issues like poweroff on lid close, and hope this project will be a great starting point.

2.2. Deliverables

Before the mid-term evaluation

I would be happy to work with the implementation of "Network Configuration Libraries" contributor in libifconfig :)

After the mid-term evaluation

2.3. Test Plan

As it is a WiFi utility it would be difficult to mock its functionality in code, but I will make sure to write unit tests wherever appropriate.

2.4. Project Schedule

170 hours are allocated for the project as per the GSOC guidelines for a medium project.

May 8 - June 1 Community bonding

June 2 Coding starts

June 9-20 My semester exams

June 21 Coding resumes

July 14 Midterm goals reached

July 18 Midterm evaluation deadline

August 25 - September 1 Final GSoC contributor evaluations