# bunny2fmc - Installation Guide

## Quick Install (3 commands)

```bash
sudo apt install pipx
pipx install bunny2fmc
bunny2fmc --setup
```

---

## Before You Start

### Server Requirements

- [ ] Linux server (Ubuntu/Debian recommended)
- [ ] Python 3.8+ installed
- [ ] sudo access
- [ ] cron available
- [ ] Network access to FMC and internet

### Cisco FMC Setup (IMPORTANT!)

Create a **dedicated API user** in FMC before installation:

1. **System → Users → Add User**
2. Fill in:
   - Username: `bunny2fmc_sync`
   - Password: [choose strong password - save it!]
   - Role: **Network Admin** (or Maintenance User)
   - Authentication: **Local**
3. Click **Save**

**IMPORTANT:** Don't use your admin account - API login logs out the web UI session!

### Have Ready for Setup

```
FMC Hostname:        [e.g., fmc.company.com]
FMC Username:        bunny2fmc_sync
FMC Password:        [the password you chose]
Dynamic Object Name: BunnyCDN_Dynamic
Sync Interval:       [in minutes]
```

---

## Detailed Installation

### 1. Install pipx

**Ubuntu/Debian:**
```bash
sudo apt install pipx
pipx ensurepath
```

**macOS:**
```bash
brew install pipx
pipx ensurepath
```

Open a new terminal after `ensurepath`.

### 2. Install bunny2fmc

```bash
pipx install bunny2fmc
```

### 3. Run Setup

```bash
bunny2fmc --setup
```

You will be asked:
- **FMC IP/hostname** - e.g., `192.168.1.100` or `fmc.company.com`
- **FMC username** - use `bunny2fmc_sync`
- **FMC password** - stored securely in OS keyring
- **Dynamic Object name** - e.g., `BunnyCDN_Dynamic`
- **IPv6** - y/n (default: n)
- **Sync interval** - enter minutes between syncs
- **Enable scheduled sync** - y/n (enables automatic cron job)

### 4. Test

```bash
bunny2fmc --run      # Run sync now
bunny2fmc --logs     # See what happened
```

---

## Using the Dynamic Object

Once bunny2fmc creates and syncs the Dynamic Object with BunnyCDN IP addresses, you can use it in firewall rules.

### Adding to Access Rules

1. **FMC → Policies → Access Control**
2. Create or edit an access rule
3. In the rule definition, add the Dynamic Object:
   - **Source** - Leave as "Any" or specify your network
   - **Destination** - Click "Add" → select your Dynamic Object (e.g., `BunnyCDN_Dynamic`)
   - **Service/Port** - HTTP (80), HTTPS (443), or custom
   - **Protocol** - TCP

### 5-Tuple Matching

The firewall rule matches traffic using these 5 components:

| Component | Example | Purpose |
|-----------|---------|---------|
| **Source IP** | Internal network (Any) | Where traffic originates |
| **Destination IP** | BunnyCDN_Dynamic | Where traffic goes (Dynamic Object) |
| **Source Port** | Any | Which port traffic leaves from |
| **Destination Port** | 80, 443 | Which port traffic reaches |
| **Protocol** | TCP | Transport protocol (TCP/UDP) |

### Example Rule

**Allow internal users to BunnyCDN:**
- Source: `Internal-Networks` (or Any)
- Destination: `BunnyCDN_Dynamic` (your Dynamic Object)
- Service: `HTTPS` (port 443, TCP)
- Action: **Allow**

The Dynamic Object will automatically update every time bunny2fmc syncs, keeping your rules current with BunnyCDN's latest edge servers without manual changes.

---

## File Locations

Everything is stored in `~/bunny2fmc/`:

```
~/bunny2fmc/
├── config.json     # Configuration
├── logs/           # Log files
└── guide/          # Documentation
```

---

## Commands

| Command | Description |
|---------|-------------|
| `bunny2fmc --setup` | Interactive configuration |
| `bunny2fmc --run` | Run sync now |
| `bunny2fmc --start` | Start cron job |
| `bunny2fmc --stop` | Stop cron job |
| `bunny2fmc --config` | Show configuration |
| `bunny2fmc --logs` | View logs |
| `bunny2fmc --help` | All commands |

---

## Troubleshooting

**pipx not found:**
```bash
pipx ensurepath
source ~/.bashrc
```

**bunny2fmc not found:**
```bash
export PATH="$PATH:$HOME/.local/bin"
```

**Can't connect to FMC:**
- Check firewall allows port 443
- Check FMC hostname/IP is correct
- Test: `curl -k https://fmc.company.com/api/fmc_platform/v1/info`

**Dynamic Object not created:**
- Check cron is running: `crontab -l`
- Check logs: `bunny2fmc --logs`
- Run manually: `bunny2fmc --run`

**Upgrade:**
```bash
pipx upgrade bunny2fmc
```

**Uninstall:**
```bash
pipx uninstall bunny2fmc
rm -rf ~/bunny2fmc/
```
