Install with systemd

Install with systemd

Recommended for this release. The systemd package installs the node as two services, without Docker. Check the requirements first.

1. Prepare the host

• 64-bit x86 (amd64) Linux with systemd: Debian 12, Ubuntu 22.04 or later, or Fedora.
• Root access and the full iproute2 package (ip -V prints iproute2; a busybox ip is not enough for Wi-Fi calling).
• Wired Ethernet to your router is recommended.

Update the system and stop ModemManager, which competes for the module's serial ports:

sudo apt update && sudo apt full-upgrade -y        # Debian and Ubuntu
sudo systemctl disable --now ModemManager

Plug in the module (both antennas attached) and check that Linux sees it:

lsusb | grep -i -E 'quectel|2c7c|qualcomm|05c6'
ls /dev/ttyUSB* /dev/cdc-wdm*

You should see one Quectel line, four ttyUSB ports and one cdc-wdm port per module. A DJI Cellular module needs its USB identity switched once first; see the hardware page. If nothing shows up, see Troubleshooting.

2. Download and verify

Note

The first public release, v1.4.0, has not been published yet. It will come together with the Vonode app 1.4.0 on the App Store and appear on the Releases page; until then the download commands below will not work.

Find the release tag on the Releases page and set it below.

VERSION=vX.Y.Z        # replace with the release tag
BASE=https://github.com/vonode/vonode-releases/releases/download/$VERSION
curl -fLO $BASE/vonode_${VERSION}_linux_amd64_commercial.tar.gz
curl -fLO $BASE/vonode_${VERSION}_linux_amd64_commercial.tar.gz.sha256
sha256sum -c vonode_${VERSION}_linux_amd64_commercial.tar.gz.sha256
tar -xzf vonode_${VERSION}_linux_amd64_commercial.tar.gz

sha256sum -c must print OK.

Optional: check the release signature

The node program is signed with the Vonode update key (Ed25519); the node checks the signature itself at startup and before in-app updates. To check it by hand (OpenSSL 3.0 or later):

cat > vonode-update-key.pem <<'KEY'
-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEAnIDCyy4CJVQSC7a+p+OeQsF/NsPguVkmB+OL//k98OY=
-----END PUBLIC KEY-----
KEY
BIN=vonode_${VERSION}_linux_amd64_commercial/vonode
printf 'vonode-binary-v1\n%s' "$(sha256sum "$BIN" | cut -d' ' -f1)" > vonode.msg
base64 -d "$BIN.sig" > vonode.sig.bin
openssl pkeyutl -verify -pubin -inkey vonode-update-key.pem -rawin -in vonode.msg -sigfile vonode.sig.bin

The last command must print Signature Verified Successfully.

3. Run the installer

cd vonode_${VERSION}_linux_amd64_commercial
sudo ./install.sh

The installer:

• puts the program in /opt/vonode/vonode and the configuration in /opt/vonode/config/config.yaml (an existing configuration and database are kept);
• creates the system user vonode-gateway (UID and GID 10001);
• installs and starts two services: vonode, the core, and vonode-gateway, the encrypted SSH service the app connects to.

4. First start

systemctl status vonode vonode-gateway        # both should be active (running)
journalctl -u vonode -f                       # follow the node log

On first start the node creates a random administrator password and keeps only its hash in the configuration. The plain text is in /opt/vonode/config/initial-admin-password, readable by root only. You rarely need it; keep it safe.

5. Pair the app

Open TCP 2222 and show the pairing QR code with the address the phone will use:

sudo ufw allow 2222/tcp
sudo /opt/vonode/vonode pair -c /opt/vonode/config/config.yaml -host node.example.com -port 2222

Then scan it in the app. Details in Pairing the app.

Everyday operation

Task	Command
Status	systemctl status vonode vonode-gateway
Logs	journalctl -u vonode -f
Restart	sudo systemctl restart vonode (up to two minutes: the node de-registers Wi-Fi calling and closes its tunnels first)
New pairing code	sudo /opt/vonode/vonode pair -c /opt/vonode/config/config.yaml -host <address> -port 2222
Lost administrator password	sudo systemctl stop vonode, sudo /opt/vonode/vonode reset-password -c /opt/vonode/config/config.yaml, sudo systemctl start vonode (all phones pair again)

Uninstall

This deletes your data and backups:

sudo systemctl disable --now vonode-gateway vonode
sudo rm /etc/systemd/system/vonode.service /etc/systemd/system/vonode-gateway.service /etc/tmpfiles.d/vonode.conf
sudo systemctl daemon-reload
sudo rm -rf /opt/vonode /var/lib/vonode-gateway