# VeloraMesh Linux Client Install

Run these commands from this extracted package.

## Easiest Interactive Install

```bash
sudo bash ./install-linux-client.sh
```

The installer opens a guided menu when no advanced parameters are supplied:

```text
1) Guided install/update
2) Network operations
3) Service operations
4) Fresh install/reset client
5) Uninstall service, keep files/config
6) Purge client install and config
0) Exit
```

`Guided install/update` asks for API host/domain, API HTTPS port, network name, device name, network join secret, edge discovery host/domain, edge UDP port, and whether the background tunnel service should be installed.

Join secrets entered through the installer must be 24-256 characters. Short or overlong secrets are rejected locally before a control-plane join request is sent.

`Network operations` can join, leave, connect/disconnect, list peers, rename the device, and run doctor without remembering client CLI commands.

`Service operations` can show service status, start, stop, restart, and run doctor.

`Fresh install/reset client` removes the systemd service, installed files, and config before running the guided install flow.

The installed systemd service sets `VELORAMESH_SECRET_DIR=/etc/veloramesh/secrets`, keeping service private-key lookup independent from a login user's `HOME`.

Optional hardening: set `VELORAMESH_CONTROL_PLANE_SPKI_PIN` to `sha256/<base64-SHA256-SPKI>` before install and preserve it through sudo if you want the saved client config to pin the HTTPS control-plane certificate/public-key path.

## Install And Start Tunnel Service

```bash
printf '%s' '<network-join-secret>' > ./veloramesh-join.secret
chmod 600 ./veloramesh-join.secret
sudo bash ./install-linux-client.sh \
  --background \
  --replace-service \
  --status \
  --network-name home \
  --device-name "$(hostname)" \
  --join-secret-file ./veloramesh-join.secret \
  --discovery edge.veloramesh.com:3478
rm ./veloramesh-join.secret
```

## LAN Discovery Broadcasts

Direct IP access uses the peer's VeloraMesh virtual IP and does not need LAN browser discovery support.

For LAN server-browser tests, enable discovery from the Ubuntu server manager or admin CLI:

```bash
sudo /opt/veloramesh/veloramesh-server admin networks broadcast -network home -mode all
```

Return to the safer default after testing:

```bash
sudo /opt/veloramesh/veloramesh-server admin networks broadcast -network home -mode filtered
```

Custom local UDP ports/ranges can still be supplied for diagnostics with `--forward-broadcast-udp`, for example `2300-2400,6073`.

When the server administrator sets the network to `broadcast_mode=all`, local custom UDP port allowlists are not required for that network's UDP discovery broadcasts.

## Status

```bash
sudo systemctl status veloramesh-client --no-pager
sudo journalctl -u veloramesh-client -n 100 --no-pager
```

## Doctor

Run this after install to verify local identity, server auth, joined networks, peer visibility, MTU, and TUN prerequisites:

```bash
sudo /opt/veloramesh/veloramesh-client doctor \
  -config /etc/veloramesh/client.json \
  -network home
```

For a sanitized support bundle:

```bash
sudo /opt/veloramesh/veloramesh-client doctor \
  -config /etc/veloramesh/client.json \
  -network home \
  -bundle /tmp/veloramesh-doctor.zip
```

The guided installer also runs a non-blocking doctor self-test after setup. Linux service logs are managed by journald.

## Network Administration

Network creation, join-secret rotation, member removal, and device block/unblock are intentionally server-local operations. Use the Ubuntu server package's `manage-veloramesh-server.sh` menu or `/opt/veloramesh/veloramesh-server admin ...` on the server.

## Uninstall

Keep config and installed files:

```bash
sudo bash ./install-linux-client.sh --uninstall
```

Remove service, installed files, and config:

```bash
sudo bash ./install-linux-client.sh --uninstall --purge
```

Fresh reset and guided reinstall:

```bash
sudo bash ./install-linux-client.sh --fresh
```