Installing on Debian 13
cmnSense is a set of packages for Debian 13 (trixie) on amd64 and arm64. Installing them turns the machine into a cmnSense firewall and hands its network configuration over to cmnSense.
Install
The keyring package installs the repository's signing key and its APT source in one step. Debian 13 has no apt-key: the key is trusted only for this repository, through the source's Signed-By field.
shell
# 1. The repository key and source curl -fsSLO https://apt.cmnsense.org/cmnsense-archive-keyring.deb sudo apt install ./cmnsense-archive-keyring.deb # 2. Package lists; apt verifies the repository signature sudo apt update # 3. cmnSense; add cmnsense-vpn for IPsec sudo apt install cmnsense
Check the key before step 2 if you want to be sure it is the right one: the fingerprints are published here.
What happens to the network
Step 3 hands the machine's network over to cmnSense without dropping your SSH session:
- apt removes the network tools cmnSense replaces and whose removal leaves the network as it is: cloud-init, netplan, systemd-resolved, ifupdown, dhclient and similar.
- The current interfaces, addresses, routes and name servers are recorded. NetworkManager, ConnMan, dhcpcd and systemd-networkd are stopped and masked, and anything they removed on the way out is put back.
- The recorded state is imported into the cmnSense configuration and saved. An address that came from DHCP becomes
ip address dhcp, so the cmnSense DHCP client keeps renewing it. - Interface names are pinned to their MAC addresses, so they stay the same on the next boot.
Log in
The installation creates the cmnsense-admin user with a random password. It is not called admin, because cloud images (Debian on AWS, among others) already have a local account of that name:
shell
sudo cat /var/lib/cmnsense/initial-admin-password ssh cmnsense-admin@<address> # or https://<address>/
Change it after the first login, from the user menu in the web interface or with username cmnsense-admin password ... in the CLI, or create your own administrators and remove it. On the machine itself, sudo cmnsense-cli gives an administrator CLI without a password. Then continue with the first steps.
PPPoE and the cloud kernel
PPPoE needs the kernel's PPP drivers, which Debian's cloud kernel (used by the cloud images) leaves out. To use a PPPoE uplink on such a system, install the standard kernel and reboot; show pppoe tells you when it is missing. The installer ISO uses the standard kernel already.
shell
sudo apt install linux-image-amd64 # or linux-image-arm64
The packages
cmnsense | The metapackage: installs everything below except the VPN package |
cmnsense-server | The management server, the network and firewall engine, the DHCP client |
cmnsense-cli | The CLI, and the SSH and PAM wiring that puts users into it |
cmnsense-ui | The web interface, served by nginx |
cmnsense-ha | VRRP and connection state synchronisation |
cmnsense-frr | Dynamic routing with FRR |
cmnsense-dhcp | DHCPv4 and DHCPv6 servers with Kea |
cmnsense-dns | The DNS resolver |
cmnsense-vpn | IPsec with strongSwan (WireGuard is built in) |
cmnsense-archive-keyring | The repository signing key and APT source |
Updates
cmnSense updates arrive with Debian's, through apt. A running configuration is never replaced by an upgrade.
shell
sudo apt update && sudo apt upgrade
Setting up the repository by hand
Without the keyring package, the same result takes a few more lines:
shell
sudo curl -fsSLo /usr/share/keyrings/cmnsense-archive-keyring.pgp \
https://apt.cmnsense.org/cmnsense-archive-keyring.pgp
gpg --show-keys /usr/share/keyrings/cmnsense-archive-keyring.pgp
sudo tee /etc/apt/sources.list.d/cmnsense.sources >/dev/null <<'EOF'
Types: deb
URIs: https://apt.cmnsense.org
Suites: trixie
Components: main
Signed-By: /usr/share/keyrings/cmnsense-archive-keyring.pgp
EOF
sudo apt update