Alpine_5G/README.md

# Alpine 5G Router - Raspberry Pi 5 + Fibocom FM350-GL

A complete 5G router setup using Alpine Linux on Raspberry Pi 5 with a Fibocom FM350-GL modem.

## ✅ Status: Working

The 5G modem is fully operational with CYTA Cyprus SIM card.

## Documentation

| File | Description |
|------|-------------|
| [README.md](README.md) | This file – overview and reference |
| [docs/QUICKSTART.md](docs/QUICKSTART.md) | **Quick start** – clone → install script → config → start |
| [docs/DEPLOY.md](docs/DEPLOY.md) | First-time SSH and key-based deploy |
| [docs/DNS.md](docs/DNS.md) | DNS (resolv.conf, dnsmasq) for router and LAN |
| [5G_MODEM_TROUBLESHOOTING.md](5G_MODEM_TROUBLESHOOTING.md) | Modem AT commands and troubleshooting |
| [configure_fm350_5g.sh](configure_fm350_5g.sh) | Manual configuration script (uses `/etc/5g-router.conf`) |
| [CHANGELOG.md](CHANGELOG.md) | Version and feature notes |
| [docs/WEBGUI.md](docs/WEBGUI.md) | Web GUI – login (admin/support), permissions, install |

## Hardware

- **Board:** Raspberry Pi 5
- **Modem:** Fibocom FM350-GL (USB ID: 0e8d:7126)
- **OS:** Alpine Linux v3.23.3
- **SIM:** CYTA Cyprus (APN: `internet`)

## Network Architecture

```
Internet (CYTA 5G)
        │
        ▼
  FM350-GL Modem
   (RNDIS eth1)
        │
        ▼
  Raspberry Pi 5
   Alpine Linux
        │
        ▼
   eth0.100 VLAN
   (192.168.1.1)
        │
        ▼
   LAN Clients
```

## Quick Start (new device)

For a **single-command flow** from a fresh device, see **[docs/QUICKSTART.md](docs/QUICKSTART.md)**. Summary:

1. Clone or copy this repo to the device.
2. Install packages: `apk add iptables libmbim-tools qmi-utils` (and optionally dnsmasq, speedtest-cli).
3. Run **`./scripts/install.sh`** – installs scripts, OpenRC service, firewall rules, and `/etc/5g-router.conf`.
4. Edit `/etc/5g-router.conf` if needed (APN, interfaces).
5. Start: `service 5g-router start` or `/usr/local/bin/connect-5g.sh`.

For SSH and key setup: **[docs/DEPLOY.md](docs/DEPLOY.md)**.

---

## Manual Quick Start (step-by-step)

### 1. Install Required Packages

```bash
# Enable community repository
sed -i 's|#.*community|http://mirrors.neterra.net/alpine/v3.23/community|' /etc/apk/repositories
apk update

# Install packages
apk add modemmanager dnsmasq iptables libmbim-tools qmi-utils
```

### 2. Configure and Connect Modem

```bash
# Set APN for CYTA
cat /dev/ttyUSB1 & CAT_PID=$!
sleep 0.3
echo -e 'AT+CGDCONT=1,"IP","internet"\r' > /dev/ttyUSB1
sleep 2
kill $CAT_PID

# Activate connection
cat /dev/ttyUSB1 & CAT_PID=$!
sleep 0.3
echo -e 'AT+CGACT=1,1\r' > /dev/ttyUSB1
sleep 3
kill $CAT_PID

# Get modem IP
cat /dev/ttyUSB1 & CAT_PID=$!
sleep 0.3
echo -e 'AT+CGPADDR=1\r' > /dev/ttyUSB1
sleep 2
kill $CAT_PID
# Note the IP address returned (e.g., 10.156.167.104)
```

### 3. Configure Network Interface

```bash
# Replace MODEM_IP with the IP from AT+CGPADDR=1
MODEM_IP="10.156.167.104"

ip link set eth1 up
ip addr flush dev eth1
ip addr add $MODEM_IP/32 dev eth1
ip route add default dev eth1 metric 50

# Test connectivity
ping -c 3 8.8.8.8
```

### 4. Setup NAT for LAN

```bash
# Enable IP forwarding
echo 1 > /proc/sys/net/ipv4/ip_forward

# Configure NAT
iptables -t nat -A POSTROUTING -o eth1 -j MASQUERADE
iptables -A FORWARD -i eth0.100 -o eth1 -j ACCEPT
iptables -A FORWARD -i eth1 -o eth0.100 -m state --state RELATED,ESTABLISHED -j ACCEPT

# Save rules
iptables-save > /etc/iptables/rules.v4
```

## Key Configuration Details

### Modem USB Modes

| Mode | USB ID | Description | Status |
|------|--------|-------------|--------|
| 40 | 0e8d:7126 | RNDIS mode | ✅ Working |
| 41 | 0e8d:7127 | Extended mode | ❌ AT broken |

**Important:** Stay in Mode 40 - AT commands work on `/dev/ttyUSB1`.

### Working AT Commands

| Command | Description |
|---------|-------------|
| `AT` | Test communication |
| `AT+CSQ` | Signal strength |
| `AT+CGDCONT=1,"IP","internet"` | Set APN |
| `AT+CGACT=1,1` | Activate connection |
| `AT+CGPADDR=1` | Get assigned IP |
| `AT+CGCONTRDP=1` | Get DNS servers |
| `AT+GTUSBMODE?` | Check USB mode |

### CYTA Cyprus Network Info

- **APN:** `internet`
- **DNS Primary:** 195.14.130.220
- **DNS Secondary:** 195.14.154.100

## Services

The following services are configured to start on boot:

```bash
# Check service status
rc-status

# Services enabled:
# - dnsmasq (DHCP/DNS)
# - iptables-restore (firewall rules)
# - 5g-router (connection script)
```

## Files on Device (after install)

| Path | Purpose |
|------|---------|
| `/etc/5g-router.conf` | Config (APN, interfaces, failover, watchdog) – from repo `etc/5g-router.conf.example` |
| `/usr/local/bin/connect-5g.sh` | Connection script (run by service or manually) |
| `/usr/local/bin/status-5g.sh` | Status (modem, interface, route, last speedtest) |
| `/usr/local/bin/healthcheck-5g.sh` | Health check for monitoring (exit 0/1) |
| `/usr/local/bin/speedtest-5g.sh` | Optional speedtest cron target |
| `/usr/local/bin/rotate-5g-log.sh` | Optional log rotation for 5g-router.log |
| `/etc/init.d/5g-router` | OpenRC service |
| `/etc/init.d/iptables-restore` | Firewall restore service |
| `/etc/iptables/rules.v4` | Saved firewall rules (from repo `etc/iptables/rules.v4`) |
| `/etc/dnsmasq.conf` | DHCP configuration (if using dnsmasq) |
| `/var/log/5g-router.log` | Connection log |
| `/var/log/speedtest-5g.log` | Optional speedtest log |

## Troubleshooting

### Modem not up (WAN down, no IP)

**On the device**, run the modem/WAN diagnostic:

```bash
/usr/local/bin/diag-modem-up.sh
```

It reports service status, modem USB (Mode 40 vs 41), WAN interface state, AT port, last log lines, and suggested fixes. See [docs/WEBGUI.md](docs/WEBGUI.md) → Troubleshooting: Modem not up.

### Modem not responding to AT commands

1. Check modem is in Mode 40: `lsusb | grep 7126`
2. Use `/dev/ttyUSB1` for AT commands
3. Don't use `stty` - send commands directly

### DHCP not working on eth1

This is normal - RNDIS mode doesn't provide DHCP. Configure IP manually using the address from `AT+CGPADDR=1`.

### Connection drops

Re-run the connection script:
```bash
/usr/local/bin/connect-5g.sh
```

Or restart the service:
```bash
service 5g-router restart
```

## Verification Commands

```bash
# Status script (modem, interface, default route, last speedtest)
/usr/local/bin/status-5g.sh
/usr/local/bin/status-5g.sh --json

# Diagnostics (run on device to debug modem/WAN or AT port)
/usr/local/bin/diag-modem-up.sh    # why modem not up
/usr/local/bin/diag-at-port.sh     # why no AT data in Web GUI

# Health check (for Nagios / Uptime Kuma)
/usr/local/bin/healthcheck-5g.sh

# Manual checks
lsusb | grep -i fibocom
ip addr show eth1
ip route show
ping -c 3 8.8.8.8
iptables -t nat -L -n -v
tail -f /var/log/5g-router.log
```

## Optional: scheduled speedtest and log rotation

```bash
# Cron: speedtest every 6 hours, log rotation daily
# Add to crontab -e (root):
# 0 */6 * * * /usr/local/bin/speedtest-5g.sh
# 0 3 * * * /usr/local/bin/rotate-5g-log.sh
```