Configuration File

Your config.php file controls how FOSSBilling behaves after installation. You will find it in the installation root of a running instance.

This page highlights the settings administrators most commonly change. For the full inline reference, use the sample config linked below.

Configuration Options

Security Settings

Control security behavior:

Setting	Default	Description
`security.mode`	`strict`	`strict` (recommended) or `regular`. Strict enables `SameSite=Strict` and `HttpOnly` cookies.
`security.force_https`	`true`	Force HTTPS connections. Recommended for production.
`security.session_lifespan`	`7200`	Session duration in seconds (default: 2 hours).
`security.session_regeneration_grace_period`	`300`	Grace period in seconds before a regenerated session ID takes full effect.
`security.perform_session_fingerprinting`	`true`	Verify browser fingerprint on each request to help prevent session hijacking.
`security.debug_fingerprint`	`false`	Log fingerprint checks for debugging (enable temporarily only).

Trusted Proxies

Configure reverse-proxy support so FOSSBilling correctly detects the visitor's IP and protocol:

'security' => [
    'trusted_proxies' => [
        'enabled' => false,
        'proxies' => [],
        'headers' => 'x_forwarded',
    ],
],

Setting	Default	Description
`trusted_proxies.enabled`	`false`	Enable trusted proxy detection
`trusted_proxies.proxies`	`[]`	List of trusted proxy IPs or CIDR ranges
`trusted_proxies.headers`	`x_forwarded`	Header type: `x_forwarded` (standard) or `forwarded` (RFC 7239)

Encryption Key

salt — Used for reversible encryption. Keep this secret and don't change it after installation.

URLs

url — Your FOSSBilling URL with trailing slash (e.g., https://billing.example.com/).
admin_area_prefix — Admin panel path (default: /admin)

Debugging

debug — Show detailed error messages. Disable in production.
log_stacktrace — Include stack traces in logs (requires debug: true)
stacktrace_length — Maximum stack trace length

Updates

update_branch — Which updates to receive:
- "release" — Stable releases only (recommended for production)
- "preview" — Development builds (may have bugs)

Maintenance Mode

Temporarily disable public access. Use allowed_urls for endpoints that must stay reachable and allowed_ips for trusted networks that should bypass maintenance mode.

'maintenance_mode' => [
    'enabled' => true,
    'allowed_urls' => ['/api/guest/*'],
    'allowed_ips' => ['192.168.1.0/24'],
],

Cron Settings

disable_auto_cron — Disable automatic cron execution when admins log in

Localization

Setting	Default	Notes
`i18n.locale`	`en_US`	Default language code
`i18n.timezone`	`UTC`	Default timezone
`i18n.date_format`	`medium`	Options: `none`, `short`, `medium`, `long`
`i18n.time_format`	`short`	Options: `none`, `short`, `medium`, `long`
`i18n.datetime_pattern`	—	Custom date/time pattern
`i18n.auto_detect_locale`	`true`	Automatically detect visitor's preferred language from browser settings

Data & Logging

Setting	Description
`path_data`	Where sensitive data is stored
`path_logs`	Log file location
`log_to_db`	Also log to database (not fully implemented)

Database

'db' => [
    'driver' => 'pdo_mysql',
    'host' => '127.0.0.1',
    'port' => '3306',
    'name' => 'fossbilling',
    'user' => 'fossbilling_user',
    'password' => 'your_password',
],

Twig (Templates)

Setting	Description
`twig.debug`	Enable Twig debug mode
`twig.auto_reload`	Auto-reload templates on changes
`twig.cache`	Template cache directory

API Settings

Control API access.

Use require_referrer_header to lock browser-originated requests to your install URL, and allowed_ips for explicit allowlists.
Keep CSRFPrevention enabled. The bundled JavaScript API wrapper handles CSRF tokens for session-authenticated browser calls.

'api' => [
    'require_referrer_header' => false,
    'allowed_ips' => [],
    'CSRFPrevention' => true,
],

Rate Limiter

FOSSBilling includes a built-in rate limiter which depends on Symfony's rate limiter component.

policies is an empty array by default and inherits sensible defaults from FOSSBilling\Security\RateLimiter::getDefaultConfig().

Any policy you explicitly set in the policies array will override the default one. We have included an example below. You can refer to Symfony's documentation on creating rate limiter policies.

'rate_limiter' => [
    'enabled' => true,
    'whitelist_ips' => [], // Array of whitelisted IP addresses and CIDRs
    'policies' => [
        'client_signup' => ['policy' => 'fixed_window', 'limit' => 5, 'interval' => '1 hour'],
    ],
],

Environment Variables

Some settings can be overridden via environment variables:

APP_ENV=dev        # Enable development mode
APP_DEBUG=true     # Enable debug mode
DB_HOST=db.example.com   # Override database host
DB_NAME=fossbilling      # Override database name
DB_USER=myuser           # Override database user
DB_PASS=mypass           # Override database password
DB_PORT=3306             # Override database port

Making Changes

Edit config.php with a text editor
Save the file
Clear the cache: System → Tools → Clear cache (or delete /data/cache/)
Test your changes