FoxyFy Server — Documentation
FoxyFy Server is configured through a JSON file. This file defines global parameters and per-host settings.
Config File Location
- /etc/ffs/ffs.conf
Global Parameters
Parameter | Type | Example | Description |
|---|---|---|---|
license | string | "X123ABE4RF" | License key for FFS. |
http_port | int | 80 (default: 80) | Port for HTTP. |
https_port | int | 443 (default: 443) | Port for HTTPS (TLS). |
http3_port | int (opt.) | 443 (default: https_port) | Port for HTTP/3 (QUIC). |
quic_safe | bool (opt.) | true (default: false) | Safe-mode for QUIC — enables compatibility if needed, default: false. |
php_mode | string (opt.) | "unix" or "tcp" | How to connect to PHP-FPM. |
php_addr | string (opt.) | "/run/php/php-fpm.sock" | PHP-FPM socket path or TCP address. |
mysql_addr | string | "/tmp/mysql.sock" | MySQL socket or TCP address. |
mysql_user | string (opt.) | "root" | MySQL user for internal tasks. |
mysql_pwd | string (opt.) | "root1984" | MySQL password. |
api_key | string (opt.) | "ABC123XYZ789" | API key (10–32 alphanumeric chars). Enables API. |
api_endpoint | string (opt.) | "api" (default: disbaled) | Relative path (no "/") for API endpoint, e.g. /api. |
shield_enabled | bool (optional) | true (default: false) | Enables bot shield feature. |
acme_enabled | bool (opt.) | true (default: false) | Enables automatic certificate issuance via Let's Encrypt (ACME). |
Notes:
- If acme_enabled is true, FFS manages certs in /etc/ffs/certs/<host>/.
- If acme_enabled is false, FFS assumes external certificate management (Certbot/webroot).
- If api_key is invalid, API is disabled automatically.
️ Hosts Configuration (aka virtual hosts)
Parameter | Type | Example | Description |
|---|---|---|---|
domain | string | "mydomain.com" | Domain name served by this vhost. |
path | string | "/var/www/mydomain.com" | Root directory of site. Created automatically if missing. |
https | bool (opt.) | true (default: false) | Enable HTTPS. Requires cert + key. |
cert | string (opt.) | "/etc/ffs/certs/mydomain.com/fullchain.pem" | TLS certificate file path. |
key | string (opt.) | "/etc/ffs/certs/mydomain.com/privkey.pem" | TLS private key file path. |
csp | string (opt.) | "default-src 'self'" | Content-Security-Policy header. |
xfo | string (opt.) | "DENY" ("*" → "SAMEORIGIN") | X-Frame-Options (DENY, SAMEORIGIN, or empty for allow). |
ref | string (opt.) | "no-referrers" ("*" → "strict-origin-when-cross-origin") | Referrer-Policy. |
corp | string (opt.) | "same-origin" ("*" → "cross-origin") | Cross-Origin-Resource-Policy. |
coop | string (opt.) | "same-origin" | Cross-Origin-Opener-Policy. |
coep | string (opt.) | "require-corp" | Cross-Origin-Embedder-Policy. |
auth | array (opt.) | "auth": [ { "dir": "", "user": "demo", "pwd": "demo123" } ] | Enables password protection for a specfic directory. |
redirect | array (opt.) | "redirect": [ { "from": "/old", "to": "/new", "code": 301 } ] | Defines URL redirection rules (source → target), supporting permanent (301) or temporary (302) types. |
permalinks | bool (opt.) | true (default: false) | Enables permalink support (for WordPress) – equivalent to apache .htaccess rewrites. |
Notes:
- If HTTPS is enabled but cert/key are missing, FFS rejects the config.
- On first run, FFS auto-creates index.html inside the vhost path as a success message.
- Permalinks: Automatically rewrites pretty URLs to index.php (like Apache’s .htaccess rules), no web server config or .htaccess required. Works in subdirectory installs, preserves query strings, and never rewrites existing files or directories.
️ Redirect — Domain based
Parameter | Redirect |
|---|---|
"domain": "test.foxyfy.net", "path": "301:/var/www/html/foxyfy.net/test.html" | File redirect: https://test.foxyfy.net/anything gets 301 → https://foxyfy.net/test.html |
"domain": "www.foxyfy.net", "path": "308:/var/www/html/foxyfy.net/" | Site-root redirect: https://foxyfy.net/page.html gets 308 → https://foxyfy.net/page.html Redirects everything to the canonical host, preserving the path and query. |
"domain": "old.foxyfy.net", "path": "301:https://foxyfy.net/" | External redirect: https://old.foxyfy.net/anything gets 301 → https://foxyfy.net/ |
️ Redirect — path variations
Parameter | Redirect |
|---|---|
"redirect": [ { "from": "/old", "to": "/new", "code": 301 } ] | Exact path redirect: https://foxyfy.net/old → 301 → https://foxyfy.net/new Query string is preserved: /old?x=1 → /new?x=1. |
"redirect": [ { "from": "/blog/", "to": "/news/", "code": 308 } ] | Prefix redirect (preserves suffix): https://foxyfy.net/blog/post.html → 308 → https://foxyfy.net/news/post.html Trailing slash in "from" means prefix rule; the remainder of the path is appended to "to". Query is preserved. |
redirect": [ { "from": "/docs/", "to": "https://docs.foxyfy.net/", "code": 301 } ] | External prefix redirect: https://foxyfy.net/docs/intro → 301 → https://docs.foxyfy.net/intro Preserves suffix and query across hosts. |
Unique feature:
- FoxyFy handles redirects directly at the virtual-host level — no .htaccess, no rewrite engine. Each rule is parsed once at config load, cached in memory, and applied instantly on request. This architecture eliminates per-request file I/O and regex parsing, making FoxyFy’s redirects over 100× faster than traditional .htaccess-based rewrites.
️ Password protection
Parameter | Protection |
|---|---|
"auth": [ { "dir": "", "user": "demo", "pwd": "demo123" } ] | Whole-site protection ("dir" is empty): Any URL on this vhost requires Basic Auth. |
"auth": [ { "dir": "admin", "user": "root", "pwd": "s3cr3t", "realm": "Admin" } ] | Directory protection: Protects /admin/ and all subpaths below it (e.g. /admin/logs/, /admin/tools.html). Other paths remain public. |
"auth": [ { "dir": "admin/reports", "user": "ana", "pwd": "report123" }, { "dir": "admin", "user": "root", "pwd": "s3cr3t" } ] | Multiple zones (first match wins): /admin/reports/ uses the first rule, /admin/other/ uses the second. Overlapping rules are allowed; the first match applies. |
Unique feature:
- FoxyFy enforces authentication directly at the virtual-host level — no .htpasswd, no external modules. Each access rule is parsed once at config load, cached entirely in memory, and validated instantly on request. This design removes per-request file lookups and password decoding, making FoxyFy’s Basic Auth over 100× faster than traditional .htaccess-based authentication.
- Each rule is evaluated in O(1) time — a single boolean and string comparison — keeping password checks effectively cost-free even under heavy load.
Hot Reloading
- ffs.conf reloads when modified.
- TLS certificates reload automatically when updated.
Defaults & effective behavior
- Auto-creates vhost directories if missing.
- Compression: Enabled (br, gzip, zstd) — no config needed.
- WebP conversion: Auto‑detected on boot (if cwebp is available).
- API: Enabled only if api_key is a 10–32 char alphanumeric and api_endpoint is a relative path (no "/"). Served at /<api_endpoint>.
- Shield: When shield_enabled: true, bot shield hooks are activated.
- QUIC/HTTP3: Served on http3_port. quic_safe: true applies compatibility safeguards.
- Ensures ACME challenge folders exist if using webroot.
Example Config
{
"license": "",
"http_port": 80,
"https_port": 443,
"http3_port": 443,
"php_mode": "unix",
"php_addr": "/run/php/php-fpm-ffs.sock",
"shield_enabled": false,
"quic_safe": true,
"api_key": "myapikey1984",
"api_endpoint": "mycp",
"hosts": [
{
"domain": "mydomain.com",
"path": "/var/www/html/mydomain.com",
"https": true,
"cert": "/etc/ffs/certs/mydomain.com/fullchain.pem",
"key": "/etc/ffs/certs/mydomain.com/privkey.pem",
"csp": "default-src 'self'",
"xfo": "SAMEORIGIN",
"ref": "strict-origin-when-cross-origin",
"corp": "same-origin",
"coop": "same-origin",
"coep": "require-corp",
"corp": "cross-origin"
}
]
}