Skip to content

Commit e973c02

Browse files
fabriziosalmifabriziosalmi
authored
Merge pull request #85 from fabriziosalmi/copilot/add-caddy-waf-plugin-installation
Document caddy add-package installation method
2 parents 8acca6e + 80ff7aa commit e973c02

File tree

6 files changed

+255
-18
lines changed

6 files changed

+255
-18
lines changed

‎CADDY_MODULE_REGISTRATION.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@ This document outlines the requirements and steps for successfully registering t
4343
- [x] **Test Suite**: Comprehensive test coverage across multiple files
4444
- [x] **CI/CD Pipeline**: GitHub Actions workflows for testing and building
4545
- [x] **Module Import**: Can be imported and used with `xcaddy build`
46+
- [x] **caddy add-package**: Compatible with `caddy add-package` command
4647

4748
## 🔍 Potential Issues and Solutions
4849

@@ -101,11 +102,17 @@ go doc -short
101102
# Test module import
102103
go list -m github.com/fabriziosalmi/caddy-waf
103104

104-
# Verify with xcaddy (if available)
105+
# Test with caddy add-package (recommended)
106+
caddy add-package github.com/fabriziosalmi/caddy-waf
107+
108+
# Verify with xcaddy (alternative method)
105109
xcaddy build --with github.com/fabriziosalmi/caddy-waf
106110

107111
# Check latest version/tag
108112
git describe --tags --abbrev=0
113+
114+
# Verify module is loaded
115+
caddy list-modules | grep waf
109116
```
110117

111118
## 📞 Support Information

‎README.md‎

Lines changed: 33 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,25 @@ curl -fsSL -H "Pragma: no-cache" https://raw.githubusercontent.com/fabriziosalmi
6262

6363
## 🚀 Installation
6464

65-
### Prerequisites
65+
### Option 1: Using `caddy add-package` (Recommended)
66+
67+
If you already have Caddy installed, you can add this plugin directly using the `caddy add-package` command:
68+
69+
```bash
70+
caddy add-package github.com/fabriziosalmi/caddy-waf
71+
```
72+
73+
This command will:
74+
- Download a new Caddy binary with the WAF module included
75+
- Keep your existing modules intact
76+
- Safely replace your current Caddy binary
77+
- Create a backup of your previous binary (use `--keep-backup` to retain it)
78+
79+
**Note:** This is an experimental Caddy feature. The command uses Caddy's remote build service to compile and download a custom binary with the module included.
80+
81+
### Option 2: Build from Source
82+
83+
#### Prerequisites
6684

6785
- [Go](https://golang.org/dl/) **1.25** or higher
6886
- [Caddy](https://caddyserver.com/docs/install) **v2.10.x** or higher (for building with this plugin)
@@ -158,19 +176,20 @@ For complete documentation, including configuration options, rule format details
158176
### 📑 Table of Contents
159177

160178
1. [**Installation**](docs/installation.md) - *Instructions for installing the Caddy WAF middleware.*
161-
2. [**Configuration Options**](docs/configuration.md) - *Detailed explanation of all available configuration settings.*
162-
3. [**Rules Format (`rules.json`)**](docs/rules.md) - *A comprehensive guide to defining custom rules using the JSON format.*
163-
4. [**Blacklist Formats**](docs/blacklists.md) - *Documentation of the formats used for defining IP and DNS blacklists.*
164-
5. [**Rate Limiting**](docs/ratelimit.md) - *How to configure rate limiting, including parameters and usage.*
165-
6. [**Country Blocking and Whitelisting**](docs/geoblocking.md) - *Details on how to configure country-based blocking and whitelisting.*
166-
7. [**Protected Attack Types**](docs/attacks.md) - *An overview of the wide range of web-based threats that the Caddy WAF is designed to protect against.*
167-
8. [**Dynamic Updates**](docs/dynamicupdates.md) - *How to dynamically update the WAF rules and other settings without downtime.*
168-
9. [**Metrics**](docs/metrics.md) - *Details about the WAF's metrics endpoint and the different metrics collected.*
169-
10. [**Prometheus Metrics**](docs/prometheus.md) - *Instructions on how to expose WAF metrics using the Prometheus format.*
170-
11. [**ELK Observability**](https://github.com/fabriziosalmi/caddy-waf/blob/main/docs/caddy-waf-elk.md) - *Instructions on how to configure caddy-waf ELK stack observability.*
171-
12. [**Rule/Blacklist Population Scripts**](docs/scripts.md) - *Documentation on the provided scripts to automatically fetch, update and generate rules and blacklists.*
172-
13. [**Testing**](docs/testing.md) - *Guidance on how to test the WAF's effectiveness using the provided testing tools.*
173-
14. [**Docker Support**](docs/docker.md) - *Instructions on how to build and run the WAF using Docker.*
179+
2. [**Using `caddy add-package`**](docs/add-package-guide.md) - *Quick guide for installing with the `caddy add-package` command.*
180+
3. [**Configuration Options**](docs/configuration.md) - *Detailed explanation of all available configuration settings.*
181+
4. [**Rules Format (`rules.json`)**](docs/rules.md) - *A comprehensive guide to defining custom rules using the JSON format.*
182+
5. [**Blacklist Formats**](docs/blacklists.md) - *Documentation of the formats used for defining IP and DNS blacklists.*
183+
6. [**Rate Limiting**](docs/ratelimit.md) - *How to configure rate limiting, including parameters and usage.*
184+
7. [**Country Blocking and Whitelisting**](docs/geoblocking.md) - *Details on how to configure country-based blocking and whitelisting.*
185+
8. [**Protected Attack Types**](docs/attacks.md) - *An overview of the wide range of web-based threats that the Caddy WAF is designed to protect against.*
186+
9. [**Dynamic Updates**](docs/dynamicupdates.md) - *How to dynamically update the WAF rules and other settings without downtime.*
187+
10. [**Metrics**](docs/metrics.md) - *Details about the WAF's metrics endpoint and the different metrics collected.*
188+
11. [**Prometheus Metrics**](docs/prometheus.md) - *Instructions on how to expose WAF metrics using the Prometheus format.*
189+
12. [**ELK Observability**](https://github.com/fabriziosalmi/caddy-waf/blob/main/docs/caddy-waf-elk.md) - *Instructions on how to configure caddy-waf ELK stack observability.*
190+
13. [**Rule/Blacklist Population Scripts**](docs/scripts.md) - *Documentation on the provided scripts to automatically fetch, update and generate rules and blacklists.*
191+
14. [**Testing**](docs/testing.md) - *Guidance on how to test the WAF's effectiveness using the provided testing tools.*
192+
15. [**Docker Support**](docs/docker.md) - *Instructions on how to build and run the WAF using Docker.*
174193

175194
---
176195

‎doc.go‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,12 @@
1616
//
1717
// Installation:
1818
//
19+
// Option 1 - Using caddy add-package (recommended if Caddy is already installed):
20+
//
21+
// caddy add-package github.com/fabriziosalmi/caddy-waf
22+
//
23+
// Option 2 - Building from source with xcaddy:
24+
//
1925
// xcaddy build --with github.com/fabriziosalmi/caddy-waf
2026
//
2127
// Basic usage in Caddyfile:

‎docs/README.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,9 @@ This documentation provides everything you need to deploy and manage the Caddy W
88

99
### 🚀 Getting Started
1010

11-
1. **[Introduction](introduction.md)** - *Overview of the Caddy WAF, its purpose, and key benefits.
11+
1. **[Introduction](introduction.md)** - *Overview of the Caddy WAF, its purpose, and key benefits.*
1212
2. **[Installation](installation.md)** - *Instructions for installing the Caddy WAF middleware.*
13+
3. **[Using caddy add-package](add-package-guide.md)** - *Quick guide for installing with the `caddy add-package` command.*
1314

1415
### ⚙️ Core Configuration
1516

‎docs/add-package-guide.md‎

Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
# Using `caddy add-package` to Install Caddy WAF
2+
3+
This guide demonstrates how to install the Caddy WAF module using Caddy's built-in `caddy add-package` command.
4+
5+
## Prerequisites
6+
7+
- Caddy v2.7 or higher already installed on your system
8+
- Internet connection (to download the custom binary)
9+
- Appropriate permissions to replace the Caddy binary
10+
11+
## Quick Installation
12+
13+
To add the Caddy WAF module to your existing Caddy installation:
14+
15+
```bash
16+
caddy add-package github.com/fabriziosalmi/caddy-waf
17+
```
18+
19+
That's it! The command will:
20+
1. Detect your current Caddy installation and modules
21+
2. Send a build request to Caddy's remote build service
22+
3. Download a new binary with the WAF module included
23+
4. Backup your current Caddy binary
24+
5. Replace the binary with the new one
25+
26+
## Verification
27+
28+
After installation, verify the module is loaded:
29+
30+
```bash
31+
caddy list-modules | grep waf
32+
```
33+
34+
Expected output:
35+
```
36+
http.handlers.waf
37+
```
38+
39+
You can also check the full list of modules:
40+
```bash
41+
caddy list-modules --packages
42+
```
43+
44+
## Usage Example
45+
46+
Once installed, you can use the WAF module in your Caddyfile:
47+
48+
```caddyfile
49+
{
50+
auto_https off
51+
admin localhost:2019
52+
}
53+
54+
:8080 {
55+
log {
56+
output stdout
57+
format console
58+
level INFO
59+
}
60+
61+
route {
62+
waf {
63+
metrics_endpoint /waf_metrics
64+
rule_file rules.json
65+
ip_blacklist_file ip_blacklist.txt
66+
dns_blacklist_file dns_blacklist.txt
67+
anomaly_threshold 10
68+
69+
rate_limit {
70+
requests 100
71+
window 60s
72+
cleanup_interval 300s
73+
}
74+
}
75+
76+
respond "Hello, World!" 200
77+
}
78+
}
79+
```
80+
81+
## Advanced Options
82+
83+
### Keep Backup
84+
85+
By default, the command deletes the backup after successful replacement. To keep the backup:
86+
87+
```bash
88+
caddy add-package --keep-backup github.com/fabriziosalmi/caddy-waf
89+
```
90+
91+
The backup will be saved as `caddy.backup` in the same directory.
92+
93+
### Version Pinning
94+
95+
To install a specific version of the module:
96+
97+
```bash
98+
caddy add-package github.com/fabriziosalmi/caddy-waf@vX.Y.Z
99+
```
100+
101+
Replace `vX.Y.Z` with the desired version tag (e.g., `v0.1.3`). You can find available versions on the [GitHub releases page](https://github.com/fabriziosalmi/caddy-waf/releases).
102+
103+
## Troubleshooting
104+
105+
### Command Not Found
106+
107+
If the `caddy add-package` command is not available, you may be using an older version of Caddy:
108+
109+
```bash
110+
caddy version
111+
```
112+
113+
You need Caddy v2.7 or higher. To update Caddy, visit [caddyserver.com/download](https://caddyserver.com/download) and follow the instructions for your operating system and architecture.
114+
115+
### Permission Denied
116+
117+
If you get a permission denied error, run the command with sudo:
118+
119+
```bash
120+
sudo caddy add-package github.com/fabriziosalmi/caddy-waf
121+
```
122+
123+
### Build Service Unavailable
124+
125+
If Caddy's remote build service is unavailable, you can build from source instead:
126+
127+
```bash
128+
# Install xcaddy
129+
go install github.com/caddyserver/xcaddy/cmd/xcaddy@latest
130+
131+
# Build with the module
132+
xcaddy build --with github.com/fabriziosalmi/caddy-waf
133+
```
134+
135+
### Module Already Exists
136+
137+
If you get an error that the package already exists, the module is already installed. To update:
138+
139+
```bash
140+
# Remove the package first
141+
caddy remove-package github.com/fabriziosalmi/caddy-waf
142+
143+
# Then add it again
144+
caddy add-package github.com/fabriziosalmi/caddy-waf
145+
```
146+
147+
## Removing the Module
148+
149+
To remove the Caddy WAF module:
150+
151+
```bash
152+
caddy remove-package github.com/fabriziosalmi/caddy-waf
153+
```
154+
155+
## Comparison with Other Installation Methods
156+
157+
| Method | Pros | Cons |
158+
|--------|------|------|
159+
| `caddy add-package` | Simple, no build tools needed, keeps existing modules | Requires internet, depends on remote build service |
160+
| `xcaddy build` | Full control, works offline (after dependencies cached), good for development | Requires Go and build tools, more complex |
161+
| Quick script | Automated setup with sample configs | Downloads and builds from source, requires build tools |
162+
163+
## Next Steps
164+
165+
- Read the [Configuration Guide](configuration.md) to customize your WAF rules
166+
- Learn about [Rate Limiting](ratelimit.md) configuration
167+
- Explore [GeoIP Blocking](geoblocking.md) features
168+
- Check out the [Metrics](metrics.md) endpoint for monitoring
169+
170+
## References
171+
172+
- [Caddy Command Line Documentation](https://caddyserver.com/docs/command-line)
173+
- [Caddy Module System](https://caddyserver.com/docs/extending-caddy)
174+
- [xcaddy Build Tool](https://github.com/caddyserver/xcaddy)

‎docs/installation.md‎

Lines changed: 32 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,34 @@
11
# Installation
22

3-
## Quick Start
3+
## Method 1: Using `caddy add-package` (Recommended)
4+
5+
If you already have Caddy installed, you can add the WAF plugin directly:
6+
7+
```bash
8+
caddy add-package github.com/fabriziosalmi/caddy-waf
9+
```
10+
11+
This command will download and install a new Caddy binary with the WAF module included. It uses Caddy's remote build service to compile a custom binary with the module.
12+
13+
**Advantages:**
14+
- No need to install Go or build tools
15+
- Keeps your existing Caddy modules intact
16+
- Automatic backup of your current binary
17+
- Quick and simple installation
18+
19+
**Options:**
20+
- `--keep-backup` - Keep the backup of your previous Caddy binary
21+
22+
**Note:** This is an experimental Caddy feature introduced in Caddy v2.7.
23+
24+
After installation, verify the module is loaded:
25+
```bash
26+
caddy list-modules | grep waf
27+
```
28+
29+
You should see `http.handlers.waf` in the output.
30+
31+
## Method 2: Quick Script Installation
432

533
```bash
634
curl -fsSL -H "Pragma: no-cache" https://raw.githubusercontent.com/fabriziosalmi/caddy-waf/refs/heads/main/install.sh | bash
@@ -20,7 +48,9 @@ INFO Rules loaded {"file": "rules.json", "total_rules": 70, "invalid_rules
2048
INFO WAF middleware provisioned successfully
2149
```
2250

23-
## Step by step installation
51+
## Method 3: Build from Source (Advanced)
52+
53+
For development or if you need full control over the build process:
2454

2555
```bash
2656
# Step 1: Clone the caddy-waf repository from GitHub

0 commit comments

Comments
 (0)