# PSOPNSenseAPI

PowerShell module for interacting with the OPNSense API to configure firewalls.

## Overview

PSOPNSenseAPI is a PowerShell module that provides cmdlets for managing OPNSense firewalls through their API. The module is built as a binary module in C# and is compatible with both PowerShell 5.1 and PowerShell 7.

## Features

- Connect to OPNSense firewalls using API credentials
- Manage firewall rules (create, read, update, delete)
- Configure NAT rules and port forwarding
- Manage aliases (host, network, port, URL, etc.)
- Manage network interfaces and VLANs
- Configure DNS settings, overrides, and forwarding
- Configure system DNS servers
- Backup, restore, export, and import configurations
- Manage plugins (install, uninstall, enable, disable)
- Manage users and permissions
- Update and upgrade firmware
- Reboot firewall with wait for reconnection
- Create VLANs from subnet divisions
- Configure DHCP servers, static mappings, leases, and options
- Manage cron jobs
- Configure and manage Tailscale VPN (with auto-installation)
- Manage gateways and static routes
- Network calculation utilities (subnet, supernet, CIDR conversion)
- Apply and revert configuration changes
- Extensive logging and error handling
- Compatible with both PowerShell 5.1 and PowerShell 7

## Requirements

- PowerShell 5.1 or PowerShell 7+
- .NET Framework 4.7.2+ (for PowerShell 5.1)
- .NET Core 3.1+ (for PowerShell 7)

## Installation

```powershell
# Install from PowerShell Gallery (when published)
Install-Module -Name PSOPNSenseAPI

# Or install manually
# 1. Download the module
# 2. Extract to a directory in your PSModulePath
# 3. Import the module
Import-Module PSOPNSenseAPI
```

## Quick Start

```powershell
# Connect to an OPNSense firewall
Connect-OPNSense -Server "https://firewall.example.com" -ApiKey "your_api_key" -ApiSecret "your_api_secret" -SkipCertificateCheck

# Get all firewall rules
Get-OPNSenseFirewallRule

# Create a new firewall rule
New-OPNSenseFirewallRule -Description "Allow HTTP" -Protocol TCP -SourceNet "192.168.1.0/24" -DestinationPort 80 -Action Pass

# Apply changes
Apply-OPNSenseFirewallChanges

# Manage aliases
Get-OPNSenseAlias
New-OPNSenseAlias -Name "WebServers" -Type host -Content "192.168.1.10,192.168.1.11" -Description "Web Servers" -Apply
New-OPNSenseAlias -Name "WebPorts" -Type port -Content "80,443" -Protocol TCP -Description "Web Ports" -Apply
Set-OPNSenseAlias -Uuid "9e4ec4f0-9dd1-4fa3-8c1d-8a8e9d772b0f" -Content "192.168.1.10,192.168.1.11,192.168.1.12" -Apply

# Manage interfaces
Get-OPNSenseInterface
Set-OPNSenseInterface -Name "lan" -Description "Local Network" -IpAddress "192.168.1.1" -SubnetMask "24"

# Create VLANs from subnet divisions
New-OPNSenseSubnetVLANs -ParentInterface "em0" -Network "192.168.0.0/24" -SubnetMaskBits 27 -StartingVlanId 10 -VlanIdIncrement 10 -EnableDHCP

# Configure DNS
Set-OPNSenseDNSServer -Forwarding -Forwarders "8.8.8.8","8.8.4.4" -Apply
New-OPNSenseDNSOverride -Hostname "server" -Domain "local" -IpAddress "192.168.1.10"

# Manage plugins
Get-OPNSensePlugin -Installed
Install-OPNSensePlugin -Name "os-acme-client" -Wait

# Manage users
New-OPNSenseUser -Username "john" -Password "P@ssw0rd" -FullName "John Doe" -Groups "admins"

# Configure DHCP
Get-OPNSenseDHCPServer
Set-OPNSenseDHCPServer -Interface "lan" -RangeFrom "192.168.1.100" -RangeTo "192.168.1.200" -Apply
New-OPNSenseDHCPStaticMapping -Interface "lan" -MacAddress "00:11:22:33:44:55" -IpAddress "192.168.1.50" -Hostname "printer"
Get-OPNSenseDHCPLease
Remove-OPNSenseDHCPLease -MacAddress "00:11:22:33:44:55" -Apply
Get-OPNSenseDHCPOption -Interface "lan"
New-OPNSenseDHCPOption -Interface "lan" -Number 66 -Value "192.168.1.10" -Description "TFTP Server" -Apply

# Manage cron jobs
Get-OPNSenseCronJob
New-OPNSenseCronJob -Description "Daily backup" -Command "/usr/local/bin/backup.sh" -Minutes "0" -Hours "2" -Apply

# Configure and manage Tailscale
Get-OPNSenseTailscaleStatus -IncludeInterfaces
Enable-OPNSenseTailscale -AcceptDns -AcceptRoutes -Force
# Advertise subnet routes to Tailscale network
Enable-OPNSenseTailscale -AdvertiseRoutes -SubnetRoutes "192.168.1.0/24","10.0.0.0/8" -Force
Connect-OPNSenseTailscale -AuthKey "tskey-auth-abcdef123456" -InstallIfMissing -Force

# Manage DNS forwarding
Get-OPNSenseDNSForwarding
Set-OPNSenseDNSForwarding -Enabled -DnsServers "8.8.8.8","8.8.4.4" -Apply
New-OPNSenseDNSForwardingHost -Domain "example.com" -Server "192.168.1.10" -Apply

# Configure system DNS
Get-OPNSenseSystemDNS
Set-OPNSenseSystemDNS -Hostname "firewall" -Domain "example.com" -DnsServers "1.1.1.1","1.0.0.1" -Apply

# Manage gateways and routes
Get-OPNSenseGateway -IncludeStatus
New-OPNSenseGateway -Name "WAN2_GW" -Interface "opt1" -IpAddress "203.0.113.1" -Description "Secondary WAN" -Apply
Get-OPNSenseRoute
New-OPNSenseRoute -Network "192.168.100.0/24" -Gateway "WAN2_GW" -Description "Remote Office" -Apply

# Network utilities
Invoke-OPNSenseNetworkCalculation -Network "192.168.1.0/24" -Operation Info
Invoke-OPNSenseNetworkCalculation -Network "10.0.0.0/16" -Operation Subnet -PrefixLength 24
ConvertTo-OPNSenseNetworkNotation -CIDR 24  # Returns "255.255.255.0"

# Advanced supernetting
Invoke-OPNSenseNetworkCalculation -Network "192.168.1.0/24" -Operation Supernet -AdditionalNetworks "192.168.2.0/24"
Invoke-OPNSenseNetworkCalculation -Network "10.0.0.0/24" -Operation SupernetSummarize -AdditionalNetworks "10.0.1.0/24","10.0.2.0/24"

# Firmware management
Update-OPNSenseFirmware -Wait

# Major firmware upgrade
Start-OPNSenseFirmwareUpgrade -Wait -Timeout 1200

# Reboot firewall
Restart-OPNSenseFirewall -Wait -Timeout 300

# Configuration management
Get-OPNSenseConfig | Restore-OPNSenseConfig -Force  # Get and restore configuration in one line
$config = Get-OPNSenseConfig  # Get configuration as XML document
Export-OPNSenseConfig -Path (New-Object System.IO.FileInfo "C:\Backups\opnsense-config.xml")
Import-OPNSenseConfig -Path (New-Object System.IO.FileInfo "C:\Backups\opnsense-config.xml") -Force
```

## Documentation

For detailed documentation, see the [docs](./docs) directory or use PowerShell's built-in help:

```powershell
Get-Help Connect-OPNSense -Full
```

## Development

### Build and Test

To build and test the module locally:

```powershell
# Run tests
.\build\test.ps1

# Build the module
.\build\build.ps1

# Build a release version with automatic versioning
.\build\build-release.ps1 -Clean -Test -Package
```

### Versioning

The module uses a versioning scheme of `yyyy.MM.dd.HHmm` for releases, which is automatically generated during the build process.

### CI/CD

The project uses GitHub Actions for continuous integration and deployment:

- Builds and tests are run on every push to the main branch
- Release packages are automatically created with the versioning scheme
- Release artifacts are uploaded to GitHub Releases

## Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Run tests to ensure they pass
5. Commit your changes (`git commit -m 'Add some amazing feature'`)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request

## License

This project is licensed under the MIT License - see the LICENSE file for details.
