Freedive

Dive into FreeBSD with Freedive!

Freedive emerges as an innovative standalone tool for FreeBSD, offering a graphical user interface (GUI) that revolutionizes the way systems are managed, enabling both newcomers and experienced users to administer their FreeBSD installations with ease.

This GUI, accessible through a mobile-friendly web interface, democratizes the use of FreeBSD by allowing beginners to engage with the operating system without the need to delve into the complexities of the command-line shell. Designed with responsiveness in mind, Freedive's interface adapts seamlessly to various screen sizes, ensuring that system administrators can perform essential tasks from virtually any device, be it a smartphone, tablet, or desktop.

The intuitive design of Freedive's web interface lowers the barrier to entry for managing FreeBSD systems, making it more approachable for users who may not be familiar with Unix-like environments. By providing a full spectrum of system management capabilities through its GUI, Freedive empowers users to perform tasks ranging from user account management to service configuration, all without writing a single line of shell code.

Freedive stands as a testament to the versatility of FreeBSD, extending its appeal beyond the traditional tech-savvy audience to a broader range of users who can now leverage the power of FreeBSD with the convenience of a modern web-based interface.

Features

Made by and for users of FreeBSD as their:

• Home lab
  • Tailscale / Wireguard VPN
  • Manage PF rules (firewall)
  • Manage Jails via Bastille
• Network attached storage
  • Samba shares
  • Backups via Restic
  • Manage ZFS datasets, snapshots and backups
• Personal/ public web server
  • Manage domains and TLS certificates
  • Host static sites
  • Reverse proxy to any jail:port

Freedive works in immediate mode:

• Queries host, caches some results in memory
• No database except for acounts
• Executes commands when actions taken in UI

Status: planning/alpha. You can use Freedive to manage system services. Package management coming soon. Other features will be developed as time/help is available. This is currently a hobby project and makes no guarantees about what features will be implemented and when.

Screenshots

Quick Steps

Binaries

For a quick test you can just use the generated FreeBSD pkgs to try Freedive:

• freedive-0.1.0.pkg [hosted at gyptazy.ch]

Build & Deploy

Requirements

Building Freedive requires some additional packages like gmake, gcc and especially elixir (>= 1.16.0). This also requires you to switch to the latest ports/pkgs branch instead of the quarterly.

This is not needed when you are already using the latest repository. However, switching to the latest ports/pkgs branch can be easily done with the following steps:

mkdir -p /usr/local/etc/pkg/repos
echo "FreeBSD: { url: \"pkg+http://pkg.freebsd.org/\${ABI}/latest\" }" > /usr/local/etc/pkg/repos/FreeBSD.conf
pkg -y upgrade -f

If you are fully running on pkg instead of ports you need to copy a file which is referenced and used by Freedive. If you have ports active on your system, this step can be skipped - if not, simply run the following commands:

mkdir -p /usr/ports/Keywords/
curl -O /usr/ports/Keywords/ https://raw.githubusercontent.com/freebsd/freebsd-ports/main/Keywords/sample.ucl

You may also want to setup your own doas account (passwordless) by running:

echo "permit nopass <USERNAME> as root" >> /usr/local/etc/doas.conf

Within the last step, the needed dependencies can be installed from the pkg repository:

pkg install git inotify-tools gmake elixir gcc doas

Building

Freedive can be simply build by running the following commands:

pkg install -y git inotify-tools gmake elixir gcc doas
git clone https://brew.bsd.cafe/hiway/freedive.git
mix setup

Packaging

If you also want to create and build a distributable .pkg file, simply run the following command afterwards:

mix package

This creates you the file freedive-0.1.0.pkg within your build directory.

Usage (compile)

After building, you can directly start Freedive. Freedive can be started by running mix or inside IEx by executing:

mix phx.server
or
iex -S mix phx.server

Now you can visit localhost:4000 from your browser.

Registering accounts via browser is enabled in dev envronment.

Visit /users/register to create an account. Then visit /dev/mailbox to confirm the account.

Now, you can ue these credentials to log in and explore Freedive.

Usage (pkg)

Another solution directly leads into using the built package. This can be installed by running:

pkg install -U -y freedive-0.1.0.pkg

Afterwards, the configuration should be adjusted in /usr/local/etc/freedive/freedive.env where the following settings should be defined:

HOST="hostname"
BIND="ip-to-bind"
PORT=3443

Ensure that the host is set to whatever hostname you'll use to access the service from browser. For example, if you bind to the Tailscale/Wireguard IP, use the hostname that'll point to this IP. Port can be anything suitable in your environmet that's open and accessible from your mobile/laptop.

Enable Freedive

• service freedive enable

Initialize Freedive

• service freedive init

Create an account for yourself

• service freedive account_create

Accounts have full access to every part of the system via Freedive, do NOT create accounts for people you do not trust to have root access on this machine.

Start Freedive

• service freedive start

Check logs

• tail -f /var/log/freedive/freedive.log

Visit https://hostname:port from your browser and log in with the account created above.

Chat / Community

The chat and community is based in the Matrix channel hosted at the BSD.cafe:

• #BSDCafe:bsd.cafe

You can also join by simply clicking the following link: https://matrix.to/#/#BSDCafe:bsd.cafe