Configuration reference

The packaged controller reads its runtime environment from:

/etc/asestack/asestack.env

The installer creates /etc/asestack with mode 0700 and the environment file with mode 0600. Keep that ownership and mode: the file can contain passwords, database connection strings, backup encryption material, enrollment settings, and third-party credentials.

Edit and apply configuration

Edit the installed file as root:

sudoedit /etc/asestack/asestack.env
sudo systemctl restart asestack
sudo ase health

Restart asestack-agent separately after changing /etc/asestack/agent/agent.env on a managed host:

sudo systemctl restart asestack-agent
sudo systemctl status asestack-agent

The Settings workspace can persist a subset of controller settings. For those fields, a saved value overrides the environment default; an empty saved value falls back to the environment. Sensitive values are returned to the browser as write-only redacted placeholders. Leaving a redacted secret unchanged preserves the stored value.

Warning

Do not copy the example file over an existing installation. The installer preserves the installed environment during updates. Back it up before editing and change one group of settings at a time.

The tables below follow deploy/asestack.env.example. Empty means no value is set in the shipped example.

Core runtime

Variable	Shipped value	Purpose
ASESTACK_ADDR	127.0.0.1:15173	Controller listen address used by the service and local health checks. Keep it on loopback unless a private bind is intentional.
ASESTACK_WEB_DIR	/opt/asestack/apps/web/dist	Built dashboard asset directory.
ASESTACK_DATA_DIR	/var/lib/asestack	Controller state, users, agent CA, fallback store, and other runtime data. Back it up as sensitive data.

The normal deployment keeps the listener private and publishes it through an HTTPS reverse proxy.

Public URL and origin checks

Variable	Shipped value	Purpose
ASESTACK_PUBLIC_URL	Empty	Fixed public HTTPS origin used for enrollment URLs. When empty, URLs are inferred from the request host and proxy headers.
ASESTACK_PUBLIC_CHECK_URLS	Empty	Comma-separated public URLs for release validation helpers. Example: https://control.example.com,https://status.example.com.
ASESTACK_PUBLIC_ORIGIN_IPS	Empty	Comma-separated direct origin IPs used by origin/TLS validation. Use documentation addresses such as 203.0.113.10 only in examples.
ASESTACK_EXPECTED_PUBLIC_HOSTS	Empty	Hostnames expected during public-origin validation.
ASESTACK_EXPECTED_PUBLIC_PROXY	Empty	Expected proxy provider marker for validation, such as cloudflare.

Set ASESTACK_PUBLIC_URL to the final origin, without a security-entrance path. The security entrance is not part of the WebAuthn relying-party origin or normal enrollment base URL.

Files, sites, Nginx, and certificates

Variable	Shipped value	Purpose
ASESTACK_FILE_ROOT	/www	Root to which controller-local file operations are confined.
ASESTACK_FILE_EDIT_LIMIT_BYTES	2097152	Maximum inline edit size: 2 MiB.
ASESTACK_FILE_DOWNLOAD_LIMIT_BYTES	104857600	Maximum download size through the file API: 100 MiB.
ASESTACK_FILE_UPLOAD_LIMIT_BYTES	104857600	Maximum upload size through the file API: 100 MiB.
ASESTACK_SITE_ROOT	/www	Parent directory for managed native-site document roots.
ASESTACK_DEFAULT_SITE_GATEWAY_SERVER_ID	Empty	Optional enrolled server ID used as the public gateway for targets with a private origin. Example: gateway-01.
ASESTACK_NGINX_AVAILABLE_DIR	/etc/nginx/sites-available	Directory for managed available-site configuration.
ASESTACK_NGINX_ENABLED_DIR	/etc/nginx/sites-enabled	Directory for enabled-site symlinks.
ASESTACK_NGINX_TEST_COMMAND	nginx -t	Validation command run before Nginx reload.
ASESTACK_NGINX_RELOAD_COMMAND	systemctl reload nginx	Reload command after a successful configuration test.
ASESTACK_CERTBOT_COMMAND	certbot	Certificate client command.
ASESTACK_CERTBOT_EMAIL	Empty	Contact email required for certificate issuance.
ASESTACK_CERTIFICATE_RELOAD_COMMAND	systemctl reload nginx	Reload command after certificate issue or renewal.

Paths and shell commands in this section are privileged settings. Validate them directly on every host before enabling Nginx or certificate action guards. See Sites.

Databases and Redis

Variable	Shipped value	Purpose
ASESTACK_DATABASE_URL	Empty	PostgreSQL URL for persistent control-plane state. When empty, file-backed state remains available as the fallback.
ASESTACK_MYSQL_DSN	Empty	MySQL inspection/transfer DSN. Treat it as a secret.
ASESTACK_MARIADB_DSN	Empty	MariaDB inspection/transfer DSN. Treat it as a secret.
ASESTACK_REDIS_URL	Empty	Complete Redis URL. When present, it takes precedence over the separate address settings.
ASESTACK_REDIS_ADDR	Empty; example 127.0.0.1:6379	Redis address used when no URL is configured.
ASESTACK_REDIS_PASSWORD	Empty	Redis password. Treat it as a secret.
ASESTACK_REDIS_DB	Empty; example 0	Redis database number.
ASESTACK_SQL_CONSOLE	false	Enables the read-only SQL console. Returned rows remain capped.
ASESTACK_DATABASE_TRANSFER_ACTIONS	false	Enables controller-local database import/export. While false, requests are plan-only.
ASESTACK_DATABASE_TRANSFER_DIR	/var/backups/asestack/databases	Confinement directory for database import and export files.
ASESTACK_AGENT_SQL_COMMANDS	false	Allows the controller to queue selected-agent SQL commands.
ASESTACK_AGENT_DATABASE_TRANSFER_COMMANDS	false	Allows the controller to queue selected-agent database transfers.

Agent SQL and database transfers also require their corresponding flags in the managed host's agent environment. See Guarded actions.

Backups and restore

Variable	Shipped value	Purpose
ASESTACK_BACKUP_DIR	/var/backups/asestack	Local controller archive directory.
ASESTACK_BACKUP_CREDENTIAL_KEY	Placeholder	Key material used to encrypt saved provider secrets and sign operator-history evidence. Replace and protect it.
ASESTACK_BACKUP_PROVIDER_TRANSFER_ACTIONS	false	Enables live backup-provider upload/download.
ASESTACK_RESTORE_ACTIONS	false	Enables authenticated restore execution. Leave false outside a reviewed restore window.
ASESTACK_BACKUP_SCHEDULE_RUNNER	false	Runs due remote backup schedules automatically. Provider transfer actions must also be enabled for live transfers.
ASESTACK_BACKUP_SCHEDULE_INTERVAL	1m	Poll interval for due schedules.
ASESTACK_BACKUP_RETENTION_DELETE_ACTIONS	false	Deletes retention candidates after successful uploads. While false, retention is a dry run.
ASESTACK_SYSTEM_SNAPSHOT_UPLOAD_LEASE_RETENTION_DAYS	90	Age after which stale active upload leases and old completed/failed/expired lease evidence can be pruned.

ASESTACK_BACKUP_CREDENTIAL_KEY must remain available for the lifetime of any saved encrypted provider configuration or signed archive that depends on it. Back up the key separately from off-host archives, with equivalent access control. See Backups and restore.

System snapshot settings

System snapshots are selected-server, allowlisted archives rather than whole-disk images. Their controller gates are disabled when unset:

Controller variable	Default	Purpose
ASESTACK_AGENT_SYSTEM_SNAPSHOT_COMMANDS	false	Allows the controller to queue selected-agent snapshot create, transfer, staged restore, and rollback commands.
ASESTACK_AGENT_SYSTEM_SNAPSHOT_HEALTH_CHECK_COMMANDS	false	Separately allows the controller to queue allowlisted pre/post-restore health probes.
ASESTACK_SYSTEM_SNAPSHOT_UPLOAD_MAX_BYTES	10737418240	Maximum controller upload-lease archive size: 10 GiB.
ASESTACK_SYSTEM_SNAPSHOT_UPLOAD_CHUNK_BYTES	8388608	Resumable upload chunk target: 8 MiB, capped by the maximum size.

The selected managed host independently controls execution:

Agent variable	Default	Purpose
ASESTACK_AGENT_SYSTEM_SNAPSHOT_ACTIONS	false	Allows guarded snapshot archive creation, upload, staging, restore execution, rollback preparation, and rollback application.
ASESTACK_AGENT_SYSTEM_SNAPSHOT_HEALTH_CHECKS	false	Allows only the separately queued, allowlisted health probes.
ASESTACK_AGENT_SYSTEM_SNAPSHOT_STAGING_DIR	/var/lib/asestack/system-snapshots/staging	Root-only working directory for archive creation.
ASESTACK_AGENT_SYSTEM_SNAPSHOT_RESTORE_STAGING_DIR	/var/lib/asestack/system-snapshots/restore-plan	Unique staging trees used for reviewed restore contents.
ASESTACK_AGENT_SYSTEM_SNAPSHOT_RESTORE_ROLLBACK_DIR	/var/lib/asestack/system-snapshots/rollback-plan	Rollback archives, checksums, and manifests created before overwrite.

Keep the command and action gates disabled outside a reviewed backup or restore window. The restore workflow also requires approval digests, operator assertions, prepared rollback evidence, and exact final confirmation tokens; these environment gates do not bypass those checks.

Deployment-validation provider inputs

These variables support optional release/deployment validation. They are not a replacement for saved production provider profiles.

Variable	Shipped value	Purpose
ASESTACK_DEPLOYMENT_CHECK_PROVIDER_ENV_FILE	Empty	Root-only file loaded after the runtime environment for disposable provider fixtures. Recommended path: /etc/asestack/deployment-provider-check.env.
ASESTACK_BACKUP_PROVIDER_CHECK_SUMMARY_FILE	Empty	Optional sanitized provider-preflight JSON output.
ASESTACK_RELEASE_CHECK_EXPECT_EXTERNAL_PROVIDERS	Empty	Comma-separated provider list shared by release preflight and guarded validation. Supported values: google-drive, webdav, sftp, dropbox, onedrive.
ASESTACK_RELEASE_CHECK_BACKUP_PROVIDER_SUMMARY_FILE	Empty	Sanitized provider-preflight output path used by ase release-check.
ASESTACK_DEPLOYMENT_CHECK_EXPECT_EXTERNAL_PROVIDERS	Empty	Providers that must complete live upload/download proof during the guarded deployment check.

The fixture file is rejected when it is group- or world-readable:

sudo install -m 600 /dev/null /etc/asestack/deployment-provider-check.env
sudoedit /etc/asestack/deployment-provider-check.env
sudo ase backup-provider-check

Never publish fixture URLs, usernames, passwords, client secrets, refresh tokens, or private keys.

Evidence retention and R2 sync

Variable	Shipped/default value	Purpose
ASESTACK_EVIDENCE_PACKET_DIR	$ASESTACK_DATA_DIR/evidence-packets/deployment-checks	Protected local packet directory. Custom paths outside the data/config roots are included explicitly by control-plane backup creation.
ASESTACK_EVIDENCE_PACKET_RETENTION_DAYS	90	Local time-based retention.
ASESTACK_EVIDENCE_PACKET_RETENTION	0	Optional newest-packet count cap; 0 disables the cap.
ASESTACK_EVIDENCE_REQUIRE_OFFHOST	false	Makes ase evidence-policy fail until an off-host target is documented.
ASESTACK_EVIDENCE_OFFHOST_TARGET	Empty	Human-readable provider/path or runbook note for the off-host audit target. It does not perform a sync by itself.
ASESTACK_EVIDENCE_R2_BUCKET	asestack-evidence	Private R2 bucket used by ase evidence-sync.
ASESTACK_EVIDENCE_R2_PREFIX	deployment-evidence/<hostname>	Controller-specific object prefix.
ASESTACK_EVIDENCE_R2_ACCOUNT_ID	Empty	Cloudflare account ID for the R2 endpoint.
ASESTACK_EVIDENCE_R2_ACCESS_KEY_ID	Empty	S3-compatible R2 object-access key ID. Secret.
ASESTACK_EVIDENCE_R2_SECRET_ACCESS_KEY	Empty	S3-compatible R2 object-access secret. Secret.
ASESTACK_EVIDENCE_R2_LIFECYCLE_ENV_FILE	/etc/asestack/evidence-r2-lifecycle.env	Optional root-only file for lifecycle API settings.
ASESTACK_EVIDENCE_R2_LIFECYCLE_API_TOKEN	Empty	Cloudflare management API token used to inspect or change lifecycle rules. Secret.
ASESTACK_EVIDENCE_R2_API_TOKEN	Empty	Legacy alias for the lifecycle API token.
ASESTACK_EVIDENCE_R2_JURISDICTION	Empty	Optional R2 jurisdiction header: default, eu, or fedramp.
ASESTACK_EVIDENCE_R2_LIFECYCLE_DAYS	365	Expected off-host retention window.
ASESTACK_EVIDENCE_R2_LIFECYCLE_PREFIX	Same as object prefix	Object prefix covered by the lifecycle rule.
ASESTACK_EVIDENCE_R2_LIFECYCLE_REQUIRED	false	Makes lifecycle check fail when credentials or a matching rule are missing.
ASESTACK_EVIDENCE_SYNC_INCLUDE_BACKUP	false	Includes the latest local backup archive and checksum in evidence sync.

S3-compatible access keys upload objects. The management API token is separate and is used only for lifecycle operations. Prefer the root-only lifecycle file instead of putting the management token in the controller runtime environment.

Set both local retention values to 0 only when another protected audit handoff already captures the same evidence.

ASESTACK_EVIDENCE_R2_LIFECYCLE_CONFIRM=apply is a one-command confirmation guard, not a setting to leave in the environment.

Authentication and browser security

Variable	Shipped value	Purpose
ASESTACK_ADMIN_EMAIL	[email protected]	Initial owner email used when creating the user store.
ASESTACK_ADMIN_PASSWORD	Placeholder; randomized by installer	Initial owner password used only when creating/resetting the owner. Secret.
ASESTACK_SECURE_COOKIES	true	Marks session and related cookies secure for HTTPS.
ASESTACK_SESSION_TTL	12h	Authenticated session lifetime.
ASESTACK_TRUSTED_ORIGINS	http://127.0.0.1:15173	Extra trusted browser origins for CSRF checks. Add the final HTTPS origin when required by the deployment.
ASESTACK_LOGIN_WINDOW	10m	Login failure-rate window.
ASESTACK_LOGIN_MAX_FAILURES	8	Failed attempts allowed in the window before throttling.
ASESTACK_TURNSTILE_SITE_KEY	Empty	Browser-visible Turnstile site key. Turnstile is enabled only when both keys exist.
ASESTACK_TURNSTILE_SECRET_KEY	Empty	Server-side Turnstile secret. Secret.
ASESTACK_TURNSTILE_VERIFY_URL	Cloudflare siteverify endpoint	Optional verification endpoint override.
ASESTACK_TURNSTILE_TIMEOUT	3s	Server-side verification timeout.
ASESTACK_REQUIRE_MFA	false	Requires MFA for password login and prevents disabling MFA. Enable only after an owner is enrolled.
ASESTACK_SECURITY_ENTRANCE_MODE	disabled	disabled or required. The entrance is concealment, not authentication.
ASESTACK_SECURITY_ENTRANCE_CODE	Empty	Secret random URL path component: 8–128 letters, numbers, hyphens, or underscores. Never include it in public docs or monitoring URLs.
ASESTACK_SECURITY_ENTRANCE_RESPONSE_CODE	401	Response for requests that have not used the entrance. Allowed: 200, 400, 401, 403, 404, 408, 416, 444.

See Security before changing MFA, Turnstile, trusted origins, or the security entrance.

Agent enrollment and local agent

Variable	Shipped value	Purpose
ASESTACK_AGENT_TOKEN_TTL	2160h	Default enrollment token/client-certificate authentication lifetime before re-enrollment.
ASESTACK_AGENT_UPDATE_URL	https://cdn.asestack.dev/update-agent.sh	Agent-only updater embedded in generated install/update commands.
ASESTACK_LOCAL_AGENT_AUTO	true	Automatically enrolls the controller host during CDN installation. Changing it later does not remove an existing enrollment.
ASESTACK_LOCAL_AGENT_SERVER_ID	localhost	Inventory ID for the automatically enrolled local host.
ASESTACK_LOCAL_AGENT_ADDRESS	localhost	Display/address value for the local host.
ASESTACK_LOCAL_AGENT_REGION	local	Region label for the local host.
ASESTACK_AGENT_PRIVATE_ORIGIN_ADDRESS	Empty	Private address reported by an agent for gateway-to-origin site routing. Configure it in the relevant agent environment. Example: 10.0.0.20.

Generated enrollment commands contain tokens and mTLS material. Treat them as secrets. Follow Enroll a managed server instead of hand-building the agent environment.

Action gates

All common action gates in the shipped controller example are false. The system snapshot gates above are also false when unset.

Variable	Enables
ASESTACK_DOCKER_ACTIONS	Controller-local container start, stop, and restart.
ASESTACK_DOCKER_PRUNE_ACTIONS	Controller-local Docker system prune.
ASESTACK_DOCKER_EXEC_ACTIONS	Controller-local Docker exec.
ASESTACK_AGENT_DOCKER_ACTION_COMMANDS	Queueing selected-agent container start, stop, and restart.
ASESTACK_AGENT_DOCKER_EXEC_COMMANDS	Queueing selected-agent Docker exec.
ASESTACK_AGENT_NGINX_ACTION_COMMANDS	Queueing selected-agent Nginx apply, disable, rollback, and cleanup.
ASESTACK_AGENT_CERTIFICATE_ACTION_COMMANDS	Queueing selected-agent certificate issue and renewal.
ASESTACK_NGINX_ACTIONS	Controller-local native Nginx mutation.
ASESTACK_FIREWALL_ACTIONS	Controller-local validated UFW allow/deny execution.
ASESTACK_CLAMAV_SCAN_ACTIONS	Controller-local ClamAV scan execution.
ASESTACK_AGENT_WRITE_COMMANDS	Queueing selected-agent file writes.

ASESTACK_CLAMAV_SCAN_ROOT defaults to /www and confines local malware scan requests. Use the narrowest readable path.

Controller queue gates do not bypass managed-host execution gates. The agent must independently allow the matching action. Review the full paired-guard matrix in Security.

CLI-only overrides

These values control a single helper invocation. Prefer passing them only to the command that needs them instead of storing them in the service environment.

Variable	Default	Purpose
ASESTACK_UPDATE_CONFIRM	Empty	Set to yes or true for a confirmed noninteractive ase update.
ASESTACK_REPAIR_RESTART	true	Set false to repair without restarting services.
ASESTACK_REPAIR_LOCAL_AGENT	auto	Use false to skip local-agent repair or true to require it.
ASESTACK_REPAIR_SMOKE_CHECK	false	Set true to run the post-repair smoke check.
ASESTACK_PASSKEY_CHECK_URL	ASESTACK_PUBLIC_URL	Explicit origin, or an entrance URL supplied only at execution time.
ASESTACK_PASSKEY_CHECK_REQUIRE_TURNSTILE	true	Fails preflight when the deployed login policy does not require Turnstile.
ASESTACK_PASSKEY_CHECK_ALLOW_INSECURE	false	Allows HTTP only for local development checks; never use for production evidence.
ASESTACK_PASSKEY_CHECK_SUMMARY_FILE	Empty	Writes a sanitized JSON passkey-preflight summary.
ASESTACK_BACKUP_PROVIDER_CHECK_REQUIRE	Empty	Comma-separated provider groups that must be fully configured.
ASESTACK_RELEASE_CHECK_URL	ASESTACK_PUBLIC_URL	Public URL used by release checks. Supply any entrance path only at execution time.
ASESTACK_RELEASE_CHECK_RUN_SMOKE	true	Runs the installed smoke check.
ASESTACK_RELEASE_CHECK_RUN_DEPLOYMENT	false	Opts into the separately guarded deployment check.
ASESTACK_RELEASE_CHECK_RUN_EVIDENCE_SYNC	false	Opts into R2 check, dry run, and upload.
ASESTACK_RELEASE_CHECK_RUN_EVIDENCE_LIFECYCLE	true	Runs the read-only lifecycle check when available.
ASESTACK_RELEASE_CHECK_RUN_CLEANUP_SUMMARY	true	Runs the non-destructive deployment-cleanup summary.
ASESTACK_RELEASE_CHECK_RUN_BACKUP_PROVIDER_CHECK	true	Runs provider credential-completeness preflight.
ASESTACK_RELEASE_CHECK_REQUIRE_HOST_HARDENING	false	Makes UFW, fail2ban, and ClamAV smoke gaps fail the check.
ASESTACK_DEPLOYMENT_CHECK_CLEANUP_BACKUP	true	Set false only when guarded cleanup already has a verified backup.
ASESTACK_ARCHIVE_VERIFY_KEY	Empty	Offline operator-history verification key override. Prefer a protected key file.

Other custom path variables shown by ase help <command> are intended for packaging, development, or recovery. Keep the installed defaults unless a documented custom layout requires an override.

Validate a change

After changing runtime configuration:

sudo systemctl restart asestack
sudo ase health
sudo ase status
sudo ase logs-app

Then test the public health endpoint and the affected workflow from an external client. For a failed restart, use the steps in Troubleshooting.