Hello 👀
This is the home of a collection of open-source networking software written in Rust.
More specifically, the current projects are:
- Antennas: Raspberry Pi wifi router
- Toe Beans: DHCPv4 library, client, and server (work in progress, nearing release)
- wpa_passphrase: Rust rewrite of the wpa_passphrase program written for wpa_supplicant
Use the menu in the top-left or the arrows at the bottom of the page to see more.
Antennas
This application turns your Raspberry Pi 4b or 5 into a wireless router.
Warning: Antennas makes no assumption about the locality of where it is used and may or may not satisfy the wireless regulations of the area you live.
Getting Started
Hardware
| Hardware | Pi 4b | Pi 5 | Required | Notes |
|---|---|---|---|---|
| Raspberry Pi | Approved Resellers | Approved Resellers | Yes | |
| Power Supply | 15W | 15W or 27W | Yes | Third-party power supplies are not recommended. |
| MicroSD Card | Recommended | Recommended | Yes | Or use any you already own. Must have at least 16 Gb storage capacity. Prefer cards with at least "V30" and "A1" speeds. Beware of fake cards on Amazon and Alibaba. |
| Ethernet Cable | Recommended | Recommended | Yes | Or use any you already own. Prefer cables that are at least CAT 6, 6a, or higher. Beware of fake cables on Amazon and AliExpress. |
| Case | iUniker | Black or White | No | Optional. Metal cases are not recommended. The Pi 5 cases come with a fan and a single heatsink. |
| Cooling | 40mm case fan + heatsinks | Active Cooler | Only if overclocking | The Pi 4b case fan is too loud. |
- All links to recommended hardware are NOT sponsored, do NOT use affiliate links, and do NOT make me any money.
Additional Hardware
- To write Ubuntu Core to your MicroSD card:
- MicroSD card reader/writer (built in or via usb)
- To complete Ubuntu Core installation:
- USB keyboard
- Micro HDMI (pi) to standard HDMI (tv/monitor) cable. Tested with this.
- Monitor or television
Setup
Preparation
Antennas would ideally be installed on a dedicated Raspberry Pi. Why? Constrained computational resources aside, Antennas must change system firewall and networking rules in order to function. For example: we clear the firewall rules before setting a default drop policy and flush wlan0's ip addresses before adding some.
Ask yourself how will these side effects interact with any other firewall/networking snaps you have installed (if any). If you think it might then install Antennas on a separate MicroSD card.
Install Operating System
Ubuntu Core is officially supported. See the Common Questions for more information on supported devices and operating systems.
First, download an Operating System image:
- Ubuntu Core 24
- Our custom image - Same as above, but with Antennas preinstalled (you can skip step 2 below)
Then follow the official installation guide.
Install Antennas
Assume all commands from this point forward are run on the Raspberry Pi after SSH'ing into it.
sudo snap install antennas
All permissions should be granted automatically. Check with snap connections antennas. Otherwise, you can manually grant permissions.
Finish Setup
Setting a wifi password is the last step before Antennas is running. See the Configure section below for how to set a password.
After setting a password you should see a message that says "Enabled snap services". Congratulations Antennas is now running!
If you don't see that message after setting a password you can manually enable services with sudo snap start --enable antennas.
Configure
View all currently set or default options with sudo antennas.config get. Or get a single item with sudo antennas.config get wifi-channel.
Learn how to set options with sudo antennas.config set --help. You may change the default options. It is common to change the country, ssid, and passphrase:
sudo antennas.config set --country-code=us --wifi-ssid=Test --wifi-password
You will need to run sudo snap restart antennas if you want the config changes to take effect.
Debugging
Warnings
Antennas automatically updates to the latest version. When it does so, all of its services are restarted. This causes a roughly 30 second drop in wireless connection. Therefore, what you though was a bug might just be your system updating. Care is taken to batch up releases to prevent frequent downtime.
Using the network-manager snap is not recommended. It and other snaps that manipulate the system networking may or may not conflict with Antennas.
Tips
View all logs with snap logs -n=all antennas or view the latest logs of a specific service with snap logs -n=99 antennas.hostapd. You can increase the verbosity of logs that are available to view by enabling Antennas's debug mode with sudo antennas.config set --debug true. It is not recommended to leave debug mode on when not debugging.
To debug an Antennas build you can inspect it after building with snapcraft build --shell. Within the container you can see the state of various steps in the snap lifecycle. For example, go to /root/staging to see bin, sbin, and /usr/bin for your staged package binaries.
To debug an installed Antennas snap your can inspect it after installing with snap run --shell antennas.hostapd (where "hostapd" is the service). From there you can run commands like printenv.
To debug permissions check if permissions are assigned with snap connections antennas. Check if its using something protected by permissions with the snappy-debug snap or by checking dmesg.
To check what is inside the compressed snap, run unsquashfs ./antennas_1_arm64.snap.
To check port usage on Ubuntu Core, run sudo ss -lpnut.
Security
Security Features
Security is the top priority. Below is a table of security improvements that have been made since this project was forked from wifi-ap years ago:
| Security Feature | Antennas | wifi-ap |
|---|---|---|
| Maintenance | Actively being developed | Project abandoned in 2019. The last commit to master was on 2019-12-12 |
| Open Source | Yes, via Codeberg. Two-factor authentication and signed commits enabled. | Yes, on Launchpad |
| Hardware and Architecture | Only officially supporting Raspberry Pi 4b with arm64 and its builtin wireless chip. The overwhelming popularity of the Raspberry Pi makes it the lowest cost, yet most supported device available. Ubuntu certifies that it works with Ubuntu Core. It has the most stable wireless firmware I've ever experimented with. | Generically supports as many devices and architectures as possible. |
| Operating System | Only officially supporting Ubuntu Core which greatly improves security in ways such as an immutable base OS, confined applications, permissions, etc. Read more here and here. | Any operating system snaps can be installed on including less secure "classical" systems. |
| Base | Built with core24 (Ubuntu 24.04 LTS) as a base | Built with core16 (Ubuntu 16.04 ESM) as a base |
| Preferred Language | Rust was chosen for its memory and thread safety. Rust is compatible with ARM and snapcraft. | Go is also safe and compatible. |
| Application Interface | The application interface has been removed so that no other applications can directly control Antennas. | Allows other applications to communicate over a socket to control the access point and perform actions such as restarting the access point. |
| Unencrypted/Passwordless | Removed ability to configure an open access point. | Allows users to configure an open (passwordless) access point. Such an access point would have completely unencrypted wireless traffic. |
| Password Strength | 14 characters minimum, can't contain only numbers. | 8 characters minimum. |
| Password Storage | Stored as an encrypted PSK. | Stored as unencrypted plain text. |
| DNS | Encrypted with DNS-over-HTTPS using TLS 1.3. Pi 4b uses TLS_CHACHA20_POLY1305_SHA256 and Pi 5 uses TLS_AES_128_GCM_SHA256. DNS encryption verified with this tool. DNS-level blocking of malware. DNS rebind attacks blocked. | Unencrypted DNS through dnsmasq and default DNS. No malware blocking. |
| Third Party Software | Using updated versions of dependencies (hostapd, dnsmasq, dnscrypt, etc). Compiled from source with unused features disabled. All compilation changes are auditable from the snapcraft.yaml file. Compiled source code is downloaded directly from official source and not hosted elsewhere. Compiled source code is not built if it doesn't pass verification with sha512 checksums that have been GPG verified. | Several versions behind on software. Security vulnerabilities may be present. A copy of the dependency source code to compile is uploaded to a branch on the wifi-ap repository. Unknown amounts of code may have been changed before upload. Source code is not verified with checksums before build time. |
| Config | The only way to generate config is through the bundled rust program. Config is stored in non-executable toml format and validated before use. File permissions are limited. Must be root to set/get config via cli. | User may define shell scripts that set/override "config", and is sourced by a shell script that the access point executes. User shell script may contain or be written to with arbitrary bash code. Must be root to set/get configuration via cli. |
| Services | Separate services are defined via snapcraft.yaml, each having their minimum required permissions assigned. | One monolithic service (Go server) that runs other services (hostapd, dnsmasq). All permissions must be assigned to the group. |
| Without Password | If a password is not set by the user, hostapd will not start. A randomly generated password cannot be used because the password is stored as an encrypted PSK. | A randomly generated password is set by default. |
| Virtual Interface | No virtual interface | Sets up a single virtual interface if option is set to do so. Could be useful for isolating guest networks, but that probably isn't possible without a USB wifi adapter based on the wifi's iw list output. |
| Firewall | Uses firewall for routing. Sets default drop policies with only required traffic allowed. Rate limits ssh connection. Uses nftables instead of legacy iptables. | Only uses firewall for routing purposes. Leaves default accept policies. |
| Web Interface | No web interface. Config is only accessible through key-protected SSH. This eliminates the possibility of a website to brute-force guess the router's web interface credentials. | Same as Antennas. |
Cryptographically Secure Randomness
| Pi 4b | Pi 5 | Notes | |
|---|---|---|---|
| Hardware Random Number Generator | Yes | Yes | Can be accessed by sudo cat /dev/hwrng. /dev/hwrng should be feeding the pool that /dev/random and /dev/urandom pull from. System entropy can be checked with cat /proc/sys/kernel/random/entropy_avail. Testing the RNG on both devices outputs what I interpret to be the same results. I've tested with both rng-tool's sudo cat /dev/hwrng | rngtest -c 1000 and dieharder's dieharder -a. |
| Cryptographic Hardware Acceleration | No | Yes | The Pi 5's acceleration allows it to use AES algorithms for DNS (see table above). |
| Cryptographic Operation Benchmarks | PBKDF2-sha512 (256b): 482,769 IPS aes-cbc (128b): 94.7 MiB/s encrypt, 99.2 MiB/s decrypt aes-cbc (256b): 76.2 MiB/s encrypt, 77.9 MiB/s decrypt aes-xts (256b): 90.3 MiB/s encrypt, 102.5 MiB/s decrypt aes-xts (512b): 79.2 MiB/s encrypt, 80.0 MiB/s decrypt | PBKDF2-sha512 (256b): 958,478 IPS aes-cbc (128b): 982.1 MiB/s encrypt, 1613.4 MiB/s decrypt aes-cbc (256b): 810.3 MiB/s encrypt, 1379.9 MiB/s decrypt aes-xts (256b): 1351.7 MiB/s encrypt, 1352.9 MiB/s decrypt aes-xts (512b): 1199.8 MiB/s encrypt, 1199.3 MiB/s decrypt | Run with command: cryptsetup benchmark, which is preinstalled on most linux systems. Only a subset of results shown, run the command to see the full results. |
Unsafe
Antennas makes heavy use of the rust programming language. In rust, "unsafe" refers to code or interfaces that can't be verified as memory safe by the type system. Here is a list of our known unsafe usage:
| Unsafe | Reasoning |
|---|---|
| geteuid | To get the effective user id to require Antennas config to be run as root. Should not do anything dangerous with memory and should always succeed. I have confirmed that the source code for whoami and id both eventually call down to geteuid, so this should be as safe and easy as calling one of those commands. |
| tcsetattr | To interact with the termios (terminal) api to stop echoing a wifi password as it is being typed on the command line. This should make the application more secure by not displaying the user's wifi password. tcsetattr is not called directly by Antennas, and is called through a third-party dependency (currently dialoguer) |
| other | The setup binary makes heavy usage of calling to non-rust commands. Mostly nft and sysctl. Care is taken to only use trusted commands and to ensure a full path to the command is used. |
Other
- Verified that swap storage is off by default (via
swapon --show). This is good when without full disk encryption and without encrypted swap. - USB devices are not auto mounted.
Privacy
Updated on: August 2, 2024
Introduction
- We are in pursuit of creating products that are private, secure, and free.
- We will attempt to make this privacy policy simple and informative. However, you may need technical knowledge to understand parts of it.
- We do not implement tracking in the software we write. Therefore, we rely on you to report issues.
- We do not sell information.
- We do not monetize with advertisements.
Privacy Disclosures
- Snapcraft collects anonymous metrics when installing a snap package.
- Cloudflare, our hosting provider, collects anonymous server-side analytics when visiting this website. This does not happen when directly accessing the website through our onion service.
- Cloudflare might create cookies in some situations. However, it is likely that no cookies will have been created. No cookies are created when directly accessing the website through our onion service.
- Accessing the website will store anonymous access logs with the following information: datetime of access, url accessed, and user agent.
Application Privacy Features
- DNS is encrypted with DNS-over-HTTPS using TLS 1.3, and validated with DNSSEC. See the 1.1.1.1 Resolver Privacy Policy for more information.
- A tracking and advertisement blocklist is setup by default. Use the "blocklist" config option to change the blocklist.
- No mobile app or website registration is required to configure Antennas. However, an Ubuntu SSO account is temporarily required, when installing Ubuntu Core, in order to download a ssh public key for enhanced security.
Website Privacy Features
- Your connection is encrypted with HTTPS using TLS 1.3. Unencrypted HTTP is not allowed through the use of HSTS.
- Cloudflare Onion Service enabled.
- We also host our own onion service at tor.black-cat.us/antennas or http://vn2dhkupov6zzoktsbwtzfclap6g4rs57hr2qmlfyhl54qxywpzymgad.onion
- The Referrer header has been disabled. This slightly increases privacy by stopping external websites from knowing that this website was how the user navigated to their website.
Privacy Policy Changes
- This privacy policy may be updated at any time.
- Since we do not collect any information that we can use to notify you, you must check this website for updates periodically.
Performance
Wifi
Antennas enables wifi 5 (ac) speeds. The project it originally forked from only had wifi 4 (n) speeds.
Wireless speeds will vary based on the generation of Raspberry Pi used and whether it is overclocked or not. Speeds below are measured using fast.com.
Overclocking
You can safely overclock by enabling turbo mode. You should see performance gains of about 50%. This comes at the expense of higher energy usage.
Warning: Changing other overclock settings, other than what is listed here, may void your warranty. Overclocking, especially without proper cooling, may slightly reduce the lifespan of your device.
To enable turbo mode in Ubuntu Core you can set force_turbo=1, then restart for the change to take effect:
sudo snap set system pi-config.force-turbo=1
sudo reboot
To verify that overclocking worked you can check the CPU frequency with lscpu | grep 'MHz' which returns:
| Device | Overclocked | Min MHz | Max MHz | Observations |
|---|---|---|---|---|
| Pi 4b | No | 600 | 1500 | Wireless speed is about 80 Mbps |
| Pi 4b, Ubuntu Core 20 | Yes | 1500 | 1500 | Increases wireless speed to about 100-110 Mbps |
| Pi 4b, Ubuntu Core 22 | Yes | 1800 | 1800 | Increases wireless speed to about 110-150 Mbps |
| Pi 5, Ubuntu Core 24 | No | 1000 | 2400 | Increases wireless speed to about 245-250 Mbps |
| Pi 5, Ubuntu Core 24 | Yes | 2400 | 2400 | Increases wireless speed to about 260-270 Mbps |
Thermals
All Raspberry Pi models will throttle starting at 80 degrees celsius and throttle even more at 85 degrees celsius.
Temperature can be checked by running cat /sys/class/thermal/thermal_zone0/temp. The result will be a temperature in millidegrees celsius, so divide by 1000 to convert to celsius.
DNS
DNS caching is enabled and the size of the cache has been increased.
Instead of relaying DNS traffic from dnsmasq to dnscrypt, the dnsmasq DHCP server advertises dnscrypt directly.
Uses one of the fastest DNS resolvers: Cloudflare's 1.1.1.1.
DHCP
Rapid commit is enabled for faster ipv4 address assignment.
Energy Usage
The Raspberry Pi is very energy efficient. In general, it should use less energy than most consumer grade routers.
The following results are measured with a kill-a-watt meter:
| Device | Overclocked | Resting Watts | Peak Watts1 |
|---|---|---|---|
| Pi 4b | No | 2.7 | 4.3 |
| Pi 4b (core20) | Yes | 3.1 | 4.3 |
| Pi 4b (core22) | Yes | 3.2 | 4.6 |
| Pi 5 | No | 4.4 | 5.8 |
| Linksys WRT 3200 ACM | Unknown | 9.5 | 12.8 |
Peak watts were measured while running a speed test. Your results may vary.
Permissions
See the snapcraft.yaml file to audit which services are using which permissions by looking at the "plugs" for each.
To check which of those permissions have been granted to an installed instance of Antennas, run snap connections antennas.
| Permission | Uses | Automatic |
|---|---|---|
| network | Enables network access | Yes |
| network-bind | Allows services to listen on a port. dnsmasq listens on port 67 and dnscrypt listens on port 53 | Yes |
| network-control | Enables the configuration of networking and network namespaces | Yes* |
| firewall-control | Can make changes to the nftables firewall rules. Required for using device to forward packets correctly as a router. | Yes* |
- Normally these permissions do not automatically connect, but Antennas has been given special permission to.
If the automatic connection of network-control and firewall-control were ever to be revoked, you can manually connect them with these commands:
sudo snap connect antennas:firewall-control
sudo snap connect antennas:network-control
Common Questions
Will the Raspberry Pi 5 be supported?
Yes, it already is!
Will older versions, or other models, of the Raspberry Pi be supported?
Given most Raspberry Pi models use the same wifi chipset and due to how Antennas is packaged, yes, it would probably work on those devices. However, I don't test, certify, or endorse doing so. Only the latest version, subject to my ability to acquire the hardware, is actively tested. That is currently the Raspberry Pi 5.
What operating systems are supported?
Ubuntu Core is currently the only supported system. This is to provide the highest level of security for your wireless access point (which is usually the most vulnerable device in your home). Exceptions will be temporarily made if Ubuntu Core does not yet support the latest version of Raspberry Pi. Other operating systems that support Snaps will likely work, but I don't test, certify, or endorse doing so.
Will a heatsink worsen my wifi signal?
The wireless antennas are separate from the wireless chip. You can find the antennas by looking for a triangle next to the chip. Placing an appropriately sized heatsink on the wireless chip of your raspberry pi should not worsen signal because it doesn't block the antennas. The same should apply for the heatsink on the official raspberry pi active cooler.
Will a case worsen my wifi signal?
Most plastic cases will have no significant impact on signal, but some metal cases might act as a faraday cage.
How much RAM (memory) do I need?
A 2 or 4 GB model Raspberry Pi 4b, or a 4 GB model Raspberry Pi 5 should be more than enough. 8 GB models are not recommended. Each RAM module has the same memory speed. Therefore, purchasing Raspberry Pis with more memory will likely have no effect on performance. An entire system with Ubuntu Core and Antennas installed will only use about 151 megabytes of memory according to free --mega. Most consumer routers don't have much memory. An expensive one might have only 512 megabytes.
How much storage space do I need?
A 16 or 32 gigabyte micro sd card is enough. Focus on getting a card that is faster (at least V30 and A1). There are recommendations on the Getting Started page. All storage on a system with Ubuntu Server 23.10 and Antennas installed is only 2.7 gigabytes according to df --si .
Can I use a third-party wifi adapter?
Yes, see sudo antennas.config set --help for how to configure a custom "wifi-interface". Then rerun the "antennas.setup-ap" service. Be warned that the firmware for the third-party wifi adapter will likely be proprietary and buggy leading to a lot of issues. I highly recommend just using the built-in wifi because it has the most stable firmware I've been able to find.
Development
Build device and architecture
It is recommended that you have a dedicated Raspberry Pi to build the Antennas snap. Ideally the build pi would have at least 4gb of memory.
This snap must be built and run on arm64. If you build the snap, or any parts, for a different architecture, you will receive a runtime error similar to this: cannot execute binary file: Exec format error.
I've previously, successfully setup a build pi on a Raspberry Pi 4b running Ubuntu Desktop 22.04 LTS, and on a Raspberry Pi 5 running Ubuntu Server 23.10 using the instructions below.
Build tools
Install snapcraft if you haven't already:
sudo snap install --classic snapcraft
As of 2021-10-10, multipass candidate on arm64 ubuntu-desktop doesn't work when running snapcraft. Install and configure lxd instead:
snapcraft --use-lxd # then enter "y"
Set this environment variable in your ~/.bashrc to use lxd by default: SNAPCRAFT_BUILD_ENVIRONMENT=lxd instead of passing --use-lxd every time.
Run snapcraft clean && snapcraft for a fresh build. If you are sure you only changed a specific part, you can clean only that part with snapcraft clean part to save time on subsequent builds.
Installing the built snap
It is recommended that you have a dedicated Raspberry Pi to test this snap. Follow instructions on Getting Started.
Transfer the built snap from your "build pi" to the "test pi" with sftp.
If you have previously installed this snap, remove it:
sudo snap remove --purge antennas
Since your snap was built locally and not signed/asserted by the snap store, you must install it with the dangerous flag:
sudo snap install --dangerous ./antennas_1_arm64.snap
Tip: Add some aliases to your test pi's ~/.bashrc (reconnect via ssh for changes to take effect):
alias resnap="reinstall && repermission && repassword && reenable"
alias reinstall="sudo snap remove --purge antennas && sudo snap install --dangerous antennas_1_arm64.snap"
alias repermission="sudo snap connect antennas:firewall-control && sudo snap connect antennas:network-control"
alias repassword="sudo antennas.config set --country-code=us --wifi-ssid=Test --wifi-password"
alias reenable="sudo snap start --enable antennas"
Overclocking (Optional)
Warning: This has only been tested on a Raspberry Pi 4b. It has not been tested on a Raspberry Pi 5 (yet).
If you have decent cooling on your build pi then you can overclock it for faster build times. The instructions are similar to overclocking Ubuntu Core except you will have to manually add force_turbo=1 to /boot/firmware/config.txt and then reboot.
Roadmap
Project status: active
In Progress:
- Raspberry Pi 5 support
- Upgrade from Core 22 to 24
- Upgrade from hostapd 2.10 to 2.11
- Use nftables for firewall
- DHCP improvements (nearing beta testing)
Toe Beans
This project is a DHCPv4 library, client, and server.
It is a work in progress that is nearing integration into Antennas.