porta-rs 0.1.1

# Porta Guide

A friendly guide to using Porta.

## Table of Contents

- [Installation](#installation)
- [First Time Setup](#first-time-setup)
- [Managing Ports](#managing-ports)
- [Running the Service](#running-the-service)
- [Monitoring](#monitoring)
- [Troubleshooting](#troubleshooting)

---

## Installation

### Install from source

```bash
# 1. Install Rust (if you don't have it)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 2. Clone the repository
git clone https://github.com/brzb0/Porta.git
cd Porta

# 3. Build
cargo build --release

# 4. Install
sudo cp target/release/porta /usr/local/bin/
```

### Install WireGuard

Porta needs WireGuard to create the encrypted tunnel.

```bash
# Ubuntu / Debian
sudo apt update && sudo apt install wireguard

# Fedora
sudo dnf install wireguard-tools

# Arch Linux
sudo pacman -S wireguard-tools
```

---

## First Time Setup

### Server Setup (VPS with public IP)

```bash
sudo porta setup --role server
```

The wizard will ask you:

| Prompt | Example | Description |
|--------|---------|-------------|
| Listen port | `51820` | WireGuard port (default: 51820) |
| Interface name | `wg-porta` | Network interface name |
| VPN IP | `10.0.0.1/24` | Server IP in the VPN |
| Data dir | `/var/lib/porta` | Where to store data |

After setup, you'll see the **server public key**. Save it - you'll need it for the client.

### Client Setup (Machine behind CGNAT)

```bash
sudo porta setup --role client
```

The wizard will ask you:

| Prompt | Example | Description |
|--------|---------|-------------|
| Server IP | `203.0.113.50` | Public IP of your VPS |
| Server port | `51820` | WireGuard port on the server |
| VPN IP | `10.0.0.2/32` | Client IP in the VPN |
| Client ID | `my-pc` | A name for this machine |
| Interface | `wg-porta` | Network interface name |

After setup, you'll see the **client public key** and **HMAC secret**. Add them to the server config.

### Link Client to Server

Edit `/etc/porta/server.toml` on the server:

```toml
[server.auth]
allowed_clients = [
    { id = "my-pc", pubkey = "CLIENT_PUBLIC_KEY", hmac_secret = "CLIENT_HMAC_SECRET" }
]
```

---

## Managing Ports

### Add a port

```bash
sudo porta add-port --remote 8080 --local 3000 --protocol tcp --desc "My web app"
```

| Flag | Required | Description |
|------|----------|-------------|
| `--remote` | Yes | Port on the VPS (public side) |
| `--local` | Yes | Port on your local machine |
| `--protocol` | No | `tcp` (default) or `udp` |
| `--desc` | No | Description for this rule |
| `--no-ufw` | No | Skip creating firewall rule |

### Remove a port

```bash
sudo porta remove-port port-8080
```

The ID is the port number prefixed with `port-` (e.g., `port-8080`).

### List all ports

```bash
sudo porta status
```

Example output:

```
Port Forwardings:

  Remote          Local           Protocol   Status     Description
  ------          -----           --------   ------     -----------
  :8080           :3000           tcp        Active     My web app
  :443            :443            tcp        Active     HTTPS
```

---

## Running the Service

### Using systemd (recommended)

```bash
# Enable and start
sudo systemctl enable --now porta-server   # on server
sudo systemctl enable --now porta-client   # on client

# Check status
sudo systemctl status porta-server

# View logs
sudo journalctl -u porta-server -f

# Restart
sudo systemctl restart porta-server
```

### Running manually

```bash
# Start the service
sudo porta run

# With debug logging
RUST_LOG=debug sudo porta run
```

Press `Ctrl+C` to stop.

---

## Monitoring

### View metrics

```bash
sudo porta metrics
```

Shows traffic statistics: bytes sent/received, packets, connections.

### View logs

```bash
# Last 100 lines
sudo porta logs

# Follow in real-time
sudo porta logs --follow

# Filter by level
sudo porta logs --filter warning
```

---

## Troubleshooting

### "No configuration found"

Run setup first:
```bash
sudo porta setup --role server   # or --role client
```

### "WireGuard module not loaded"

```bash
sudo modprobe wireguard
echo "wireguard" | sudo tee /etc/modules-load.d/wireguard.conf
```

### "Port already in use"

Check what's using the port:
```bash
sudo ss -tlnp | grep :8080
sudo lsof -i :8080
```

### "Connection refused"

1. Check if the service is running:
   ```bash
   sudo systemctl status porta-server
   ```

2. Check WireGuard status:
   ```bash
   sudo wg show
   ```

3. Check firewall:
   ```bash
   sudo ufw status
   ```

### "Authentication failed"

Make sure the client's HMAC secret in the server config matches the client's config.

### Reset everything

```bash
# Remove configs
sudo rm -rf /etc/porta
rm -rf ~/.config/porta

# Remove service
sudo systemctl stop porta-server
sudo systemctl disable porta-server
sudo rm /etc/systemd/system/porta-server.service
sudo systemctl daemon-reload
```

---

## Tips

1. **Test locally first**: Use WSL or a local VM before deploying to production
2. **Use static IPs**: Assign static IPs to your WireGuard peers
3. **Monitor logs**: Keep `journalctl -u porta -f` open while testing
4. **Firewall rules**: Porta creates UFW rules automatically, but verify with `sudo ufw status`
5. **Multiple clients**: You can connect multiple machines to the same server

---

## Need help?

```bash
porta --help
porta setup --help
porta add-port --help
```