# Configuration

Runtime settings live in SQLite (`settings` table, JSON with a revision number) and are edited in the panel.
Saving in the panel applies them **immediately** (no restart): the IMAP pool and login cache are cleared and DAV
HTTP clients are rebuilt.

From the command line:

```bash
active-push config get                    # secrets masked as "__SET__"
active-push config get --with-secrets
active-push config validate file.json
active-push config apply file.json        # partial JSON - only the given keys change (deep merge)
```

Startup parameters (listen addresses, data directory, panel TLS) come from `/etc/active-push/environment` or
flags (`active-push --help`).

| Variable | Default | Meaning |
|---|---|---|
| `ACTIVE_PUSH_DATA_DIR` | `/var/lib/active-push` | database directory |
| `ACTIVE_PUSH_EAS_LISTEN` | `127.0.0.1:8081` | ActiveSync + Autodiscover + `/healthz` |
| `ACTIVE_PUSH_ADMIN_LISTEN` | `127.0.0.1:9091` | panel |
| `ACTIVE_PUSH_ALLOW_REMOTE_ADMIN` | `false` | allow the panel on a non-loopback address |
| `ACTIVE_PUSH_ADMIN_TLS_CERT/KEY` | - | panel TLS |
| `ACTIVE_PUSH_EAS_TLS_CERT/KEY` | - | ActiveSync TLS (without a reverse proxy) |
| `ACTIVE_PUSH_LOG_JSON` | `false` | JSON logs |
| `RUST_LOG` | `active_push=info,warn` | log filter |
| `ACTIVE_PUSH_PANEL_LOG` | `active_push=info,warn` | filter for the panel log viewer |

## Z-Push equivalents

| Z-Push | ActivePush (`section.key`) |
|---|---|
| `TIMEZONE` | `general.default_timezone` |
| `USE_FULLEMAIL_FOR_LOGIN` | `general.login_format` (`as_given` / `local_part` / `full_email`) + `general.default_domain` |
| `IMAP_DEFAULTFROM` | `general.email_template` (`{login}`, `{local}@{domain}`, `{local}@example.com`) |
| `IMAP_SERVER`, `IMAP_PORT`, `IMAP_OPTIONS` | `imap.host`, `imap.port`, `imap.security` (`none`/`start_tls`/`tls`), `imap.verify_tls` |
| `IMAP_FOLDER_*`, `IMAP_FOLDER_PREFIX` | `imap.folder_*`, `imap.folder_prefix`, `imap.use_special_use` |
| `IMAP_EXCLUDED_FOLDERS` | `imap.excluded_folders` (list, `prefix*` allowed) |
| `IMAP_AUTOSEEN_ON_DELETE`, `IMAP_INLINE_FORWARD` | `imap.autoseen_on_delete`, `imap.inline_forward` |
| `IMAP_SMTP_METHOD`, `IMAP_SMTP_PARAMS` | `smtp.method`, `smtp.host`, `smtp.port`, `smtp.security`, `smtp.auth` |
| `CALDAV_*` | `caldav.enabled`, `caldav.base_url`, `caldav.path`, `caldav.include_regex`, `caldav.exclude_regex` |
| `CARDDAV_*`, `CARDDAV_GAL_PATH`, `CARDDAV_GAL_MIN_LENGTH` | `carddav.*`, `carddav.gal_path`, `carddav.gal_min_length` |
| `SYNC_MAX_ITEMS`, `SYNC_FILTERTIME_MAX`, `SYNC_CONFLICT_DEFAULT` | `sync.max_items`, `sync.filter_time_max`, `sync.server_wins` |
| `SYNC_CONTACTS_MAXPICTURESIZE` | `carddav.max_picture_kb` |
| `PING_INTERVAL`, `PING_*_BOUND_LIFETIME` | `ping.check_interval_secs`, `ping.lifetime_min/max` |
| `RETRY_AFTER_DELAY`, `SEARCH_WAIT`, `SEARCH_MAXRESULTS` | `sync.retry_after_secs`, `sync.search_wait_secs`, `sync.search_max_results` |
| `PROVISIONING`, `LOOSE_PROVISIONING`, `policies.ini` | `provisioning.enabled`, `provisioning.loose`, `provisioning.policies[]`, `provisioning.user_policies[]` |
| `LOGAUTHFAIL`, `LOGUSERLEVEL` | `security.log_auth_failures`, `logging.debug_users` |
| `ZPUSH_HOST` (autodiscover) | `autodiscover.server_url` |
| `STATE_MACHINE`, `IPC_PROVIDER` | not needed - states in SQLite, IPC in process |

DAV paths accept `%u` (login), `%l` (local part) and `%d` (domain).

## Settings without a Z-Push counterpart

- `security.auth_fail_max / auth_fail_window_secs / lockout_secs` - password guessing protection.
- `security.trusted_proxies`, `security.real_ip_header` - real client IP behind a proxy.
- `security.eas_allowed_networks`, `panel.allowed_networks` - network allow lists.
- `security.allowed_users`, `blocked_users`, `blocked_device_types`, `require_device_approval`.
- `security.auth_cache_secs` - successful login cache (HMAC with a random per-process key, never the password).
- `smtp.enforce_from` - sender always equals the account address.
- `sync.loop_detection` - detects devices replaying an old SyncKey (shrinks the window, reported in the panel).
- `imap.pool_*` - pool of authenticated IMAP connections reused between requests.
- `panel.prometheus_token`, `panel.device_inactive_days`, `logging.*` - see [LOGS.md](LOGS.md).

## Time zones

Devices send the zone as a 172-byte Windows `TIME_ZONE_INFORMATION` structure. ActivePush maps it to an IANA
zone, preferring `general.default_timezone` (comparing this year's DST rules). Recurring events are stored in
CalDAV with `TZID` and a generated `VTIMEZONE`; single events in UTC (unless the original used `TZID`, in which
case the format is kept).