Reference proměnných prostředí
Kompletní reference konfiguračních proměnných MazeVault
Verze dokumentu: 1.0.0
Poslední aktualizace: 2026-04-26
Všechny komponenty MazeVault se konfigurují pomocí proměnných prostředí. Tato stránka poskytuje centralizovanou referenci pro všechny podporované proměnné napříč backendem, agentem, gateway a frontendem.
Citlivé hodnoty
Proměnné označené 🔐 obsahují tajemství. Ukládejte je do správce tajemství nebo zapečetěných Kubernetes secrets — nikdy je necommitujte do správy verzí.
1. Základní / Povinné
Tyto proměnné musí být nastaveny pro spuštění backendu.
| Proměnná |
Příklad |
Popis |
🔐 MAZEVAULT_MASTER_KEY |
base64:... |
Hlavní šifrovací klíč pro všechna tajemství v klidu |
🔐 MAZEVAULT_JWT_KEY |
base64:... |
JWT podepisovací klíč pro přístupové tokeny |
🔐 DATABASE_URL |
postgres://user:pass@host:5432/mazevault |
Připojovací řetězec PostgreSQL |
MAZEVAULT_LISTEN_ADDR |
:8443 |
Adresa a port pro naslouchání backendu |
MAZEVAULT_BASE_URL |
https://vault.example.com |
Veřejně dostupná URL platformy |
2. Databáze
| Proměnná |
Výchozí |
Popis |
🔐 DATABASE_URL |
— |
Úplný připojovací řetězec PostgreSQL |
DB_MAX_OPEN_CONNS |
25 |
Maximální počet otevřených spojení |
DB_MAX_IDLE_CONNS |
5 |
Maximální počet neaktivních spojení |
DB_CONN_MAX_LIFETIME |
5m |
Maximální životnost spojení |
🔐 ORACLE_PASSWORD |
— |
Heslo databáze Oracle (vyžadováno při použití Oracle SQL integrace) |
3. Autentizace a SSO (Entra ID)
| Proměnná |
Výchozí |
Popis |
ENTRA_ENABLED |
false |
Povolení Entra ID (Azure AD) SSO |
ENTRA_TENANT_ID |
— |
Azure AD tenant ID |
ENTRA_CLIENT_ID |
— |
Application (client) ID |
🔐 ENTRA_CLIENT_SECRET |
— |
Application client secret |
ENTRA_REDIRECT_URI |
— |
OAuth2 redirect URI |
ENTRA_SCOPES |
openid profile email |
Požadované OAuth2 scopes |
ENTRA_AUTO_CREATE_USERS |
true |
Automatické vytváření uživatelů při prvním SSO přihlášení |
ENTRA_DEFAULT_ROLE |
viewer |
Výchozí role pro automaticky vytvořené uživatele |
4. TLS
| Proměnná |
Výchozí |
Popis |
MAZEVAULT_TLS_ENABLED |
true |
Povolení TLS pro backend |
MAZEVAULT_TLS_CERT_FILE |
— |
Cesta k TLS certifikátu PEM |
MAZEVAULT_TLS_KEY_FILE |
— |
Cesta k privátnímu klíči TLS PEM |
MAZEVAULT_TLS_CA_FILE |
— |
Cesta ke CA bundle pro mTLS ověření |
MAZEVAULT_TLS_MIN_VERSION |
1.2 |
Minimální verze TLS (1.2 nebo 1.3) |
5. Šifrovaný trezor secrets (Volitelné)
Proměnné pro povolení šifrovaného souboru vault jako alternativy k .env pro citlivá tajemství. Viz Šifrovaný trezor secrets pro úplné informace.
| Proměnná |
Výchozí |
Popis |
MAZEVAULT_VAULT_FILE |
— |
Cesta k šifrovanému souboru secrets.vault. Pokud není nastaveno, používá se starší režim .env |
MAZEVAULT_VAULT_KEY_FILE |
vault.key |
Cesta k souboru s heslem vault (on-premise režim) |
MAZEVAULT_VAULT_AKV_URL |
— |
URL Azure Key Vault pro načtení hesla vault (Azure režim) |
MAZEVAULT_VAULT_AKV_SECRET |
mazevault-vault-key |
Název AKV secret obsahujícího heslo vault |
6. Email / SMTP
| Proměnná |
Výchozí |
Popis |
SMTP_ENABLED |
false |
Povolení SMTP odesílání emailů |
SMTP_HOST |
— |
Hostname SMTP serveru |
SMTP_PORT |
587 |
Port SMTP serveru |
SMTP_FROM |
— |
Adresa odesílatele |
🔐 SMTP_USERNAME |
— |
Uživatelské jméno pro SMTP autentizaci |
🔐 SMTP_PASSWORD |
— |
Heslo pro SMTP autentizaci |
SMTP_TLS |
true |
Použití TLS pro SMTP spojení |
Office 365 (Volitelné — má přednost před SMTP, pokud je povoleno)
| Proměnná |
Výchozí |
Popis |
O365_EMAIL_ENABLED |
false |
Povolení Office 365 Graph API pro odesílání emailů (má přednost před SMTP) |
O365_TENANT_ID |
— |
Azure AD tenant ID |
O365_CLIENT_ID |
— |
Client ID registrace aplikace (vyžaduje oprávnění Mail.Send) |
🔐 O365_CLIENT_SECRET |
— |
Client secret (pro metodu autentizace client_secret) |
O365_SENDER_EMAIL |
— |
Adresa odesílatele (uživatel nebo sdílená schránka) |
O365_AUTH_METHOD |
client_secret |
Metoda autentizace: client_secret, certificate, managed_identity |
O365_CERTIFICATE_PATH |
— |
Cesta k certifikátu PFX/PEM (pro autentizaci certificate) |
🔐 O365_CERTIFICATE_PASSWORD |
— |
Heslo certifikátu (pro autentizaci certificate) |
O365_MANAGED_IDENTITY_CLIENT_ID |
— |
Client ID Managed Identity (pro autentizaci managed_identity v Azure) |
7. Cache (Redis)
| Proměnná |
Výchozí |
Popis |
REDIS_URL |
— |
Připojovací řetězec Redis (redis://host:6379) |
🔐 REDIS_PASSWORD |
— |
Heslo Redis (pokud je povolena autentizace) |
CACHE_TTL |
300 |
Výchozí TTL cache v sekundách |
8. Azure Gateway Mode
Proměnné pro provoz MazeVault backendu v režimu gateway, připojeného k primárnímu on-premise backendu.
8.1 Základní gateway
| Proměnná |
Výchozí |
Popis |
MAZEVAULT_MODE |
primary |
Nastavte na gateway pro spuštění v režimu gateway |
PRIMARY_BACKEND_URL |
— |
URL primárního on-premise backendu (povinné v režimu gateway) |
🔐 GATEWAY_BOOTSTRAP_TOKEN |
— |
Jednorázový token pro počáteční registraci (vygenerujte z admin UI primárního serveru) |
GATEWAY_NAME |
— |
Čitelný název této gateway instance |
MAZEVAULT_PRIMARY_ENVIRONMENTS |
— |
Čárkou oddělený seznam prostředí obsluhovaných přímo primárním backendem (volitelné — nastaví se při prvním spuštění; následné změny přes UI → Nasazení → Gateway) |
8.2 Multi-Gateway identita
| Proměnná |
Výchozí |
Popis |
MAZEVAULT_GATEWAY_ENVIRONMENT |
— |
Prostředí, které tato gateway obsluhuje (NPR, PRO) |
MAZEVAULT_GATEWAY_ENVIRONMENTS |
— |
Multi-env režim: čárkami oddělený seznam (přepisuje singulární) |
MAZEVAULT_GATEWAY_ROLE |
primary |
Role gateway: primary nebo dr-standby |
MAZEVAULT_GATEWAY_STATE_FILE |
/etc/mazevault/gateway-state.json |
Cesta k souboru s perzistentním stavem gateway |
MAZEVAULT_VERSION |
— |
Verze softwaru reportovaná v heartbeatech |
8.3 Azure Managed Identity
| Proměnná |
Výchozí |
Popis |
AZURE_MANAGED_IDENTITY_CLIENT_ID |
— |
Client ID Azure Managed Identity pro přístup do Key Vault |
8.4 mTLS a zabezpečení
| Proměnná |
Výchozí |
Popis |
MAZEVAULT_MTLS_CA_FILE |
— |
Cesta k vlastnímu CA certifikátu pro mTLS ověření |
MAZEVAULT_CA_FILE |
— |
PEM soubor (cesta uvnitř backend kontejneru) s CA, která vydala serverový certifikát MazeVault. Vkládá se do generovaných instalačních skriptů agenta, které s ní stahují agenta a instalují ji jako server_ca_file agenta. Nechte prázdné, pokud hostitelé agentů serverovému certifikátu už důvěřují (podniková CA): instalátory i agenti pak používají systémové úložiště důvěryhodných certifikátů. Pořadí hledání: MAZEVAULT_MTLS_CA_FILE, MAZEVAULT_CA_FILE, MAZEVAULT_CERT_FILE. V Compose kitu soubor umístěte do CUSTOM_CERT_DIR (./certs) a nastavte /custom-certs/ca.crt |
GATEWAY_BOOTSTRAP_TTL |
24h |
TTL pro bootstrap tokeny (min 5m, max 24h) |
9. Agent
Viz také Průvodce nasazením agenta pro úplné detaily.
| Proměnná |
Výchozí |
Popis |
MAZEVAULT_SERVER_URL |
— |
URL backendu pro komunikaci agenta |
🔐 MAZEVAULT_BOOTSTRAP_TOKEN |
— |
Jednorázový registrační token |
MAZEVAULT_AGENT_NAME |
hostname |
Zobrazovaný název agenta v UI |
MAZEVAULT_PROJECT_ID |
— |
Project scope pro tajemství |
MAZEVAULT_CERT_STORE_PATH |
/var/lib/mazevault/certs |
Adresář úložiště certifikátů |
MAZEVAULT_STATE_DIR |
/etc/mazevault |
Adresář konfigurace a stavu |
MAZEVAULT_LOG_LEVEL |
info |
Úroveň logování (debug, info, warn, error) |
MAZEVAULT_LOG_FORMAT |
text |
Formát logů (text, json) |
SYNC_INTERVAL_SECONDS |
300 |
Interval synchronizace tajemství v sekundách |
MAZEVAULT_AGENT_INSTALL_CHAIN_TO_TRUSTSTORE |
true |
Nainstalovat interní CA řetězec do systémového úložiště důvěryhodných certifikátů na hostu agenta |
MAZEVAULT_AGENT_TRUST_STORE_PATH |
auto |
Přepsat výchozí systémový adresář trust store (pouze Linux; pokud je prázdné, auto-detekováno) |
10. OCSP Responder
| Proměnná |
Výchozí |
Popis |
OCSP_ENABLED |
false |
Povolení OCSP responderu |
OCSP_LISTEN_ADDR |
:8888 |
Adresa pro naslouchání OCSP responderu |
OCSP_CACHE_TTL |
300 |
Doba cache OCSP odpovědí v sekundách |
CACHE_TTL |
1m |
Jak dlouho se OCSP odpověď cachuje (Go duration); zároveň nejdelší doba, po kterou může revokace zůstat neviditelná |
CA_REFRESH_INTERVAL |
5m |
Jak často responder znovu načítá certifikační autority (0 = jen při startu) |
TRUSTED_PROXIES |
— |
IP adresy/CIDR reverzních proxy oddělené čárkou, jejichž X-Forwarded-For rate limiter OCSP respektuje (prázdné = jen adresa protistrany) |
11. Multi-Datacenter
| Proměnná |
Výchozí |
Popis |
MAZEVAULT_DC_NAME |
— |
Identifikátor datacentra |
MAZEVAULT_DC_PRIMARY |
true |
Zda se jedná o primární DC |
MAZEVAULT_DC_REPLICAS |
— |
Čárkou oddělené URL replik |
MAZEVAULT_DC_SYNC_INTERVAL |
30s |
Interval replikace mezi DC |
12. Frontend (Vite)
Proměnné frontendu se vkládají při buildu. Musí být prefixovány VITE_.
| Proměnná |
Výchozí |
Popis |
VITE_API_URL |
/api |
Základní URL backend API |
VITE_WEBSOCKET_URL |
— |
URL WebSocket endpointu |
VITE_ENTRA_ENABLED |
false |
Zobrazení SSO přihlašovacího tlačítka |
VITE_DOCS_URL |
— |
Odkaz na dokumentační portál |
VITE_SUPPORT_URL |
— |
Odkaz na portál podpory |
Kontejner frontendu navíc čte jednu proměnnou za běhu (bez nového buildu):
| Proměnná |
Výchozí |
Popis |
DOCS_URL |
https://${MAZEVAULT_DOMAIN}:8088 (Compose kit) |
Odkaz na dokumentační portál předaný UI při startu kontejneru; nastavují ho oba instalátory, docker-compose.yml i Helm chart |
13. Bezpečnostní příznaky
| Proměnná |
Výchozí |
Popis |
MAZEVAULT_CORS_ORIGINS |
— |
Povolené CORS originy (čárkou oddělené) |
MAZEVAULT_RATE_LIMIT |
100 |
API požadavků za minutu na klienta |
MAZEVAULT_SESSION_TIMEOUT |
30m |
Časový limit neaktivity relace |
MAZEVAULT_MFA_REQUIRED |
false |
Vyžadování MFA pro všechny uživatele |
TRUSTED_PROXY_CIDRS |
(prázdné) |
CIDR reverzních proxy oddělené čárkou. Jen od nich se přijímá X-Forwarded-For (IP klienta pro role s omezením CIDR) a hlavičky mTLS X-Client-Cert / ssl-client-cert; proxy musí tyto hlavičky z požadavků klientů odstraňovat |
MAZEVAULT_AUDIT_RETENTION_DAYS |
365 |
Retence auditních logů ve dnech |
14. Režim nasazení
| Proměnná |
Výchozí |
Popis |
MAZEVAULT_ENV |
production |
Název prostředí (development, staging, production) |
MAZEVAULT_DEBUG |
false |
Povolení debug režimu (nepoužívejte v produkci) |
MAZEVAULT_LOG_LEVEL |
info |
Úroveň logování backendu |
MAZEVAULT_LOG_FORMAT |
json |
Formát logů backendu |
SWAGGER_ENABLED |
true |
Povolení Swagger UI na /swagger/index.html |
FRONTEND_URL |
https://localhost |
Veřejná URL frontendu — používá se pro SSO redirect URI a CORS konfiguraci |
15. Registrace licence / organizace
Proměnné identifikující organizaci na licenčním serveru MazeVault při prvním spuštění. Licenční server odpovídá i na kontrolu nových verzí (viz Údržba); GitHub token není potřeba.
| Proměnná |
Výchozí |
Popis |
MAZEVAULT_CUSTOMER_NAME |
— |
Název organizace (pro registraci licence) |
MAZEVAULT_CUSTOMER_EMAIL |
— |
Kontaktní email administrátora |
MAZEVAULT_COMPANY_ID |
— |
IČO společnosti |
MAZEVAULT_VAT_ID |
— |
DIČ — alternativa k MAZEVAULT_COMPANY_ID |
MAZEVAULT_INSTANCE_ID |
auto |
Unikátní identifikátor instance (auto-generován, pokud je prázdný) |
MAZEVAULT_REGION |
EU |
Geografický region pro soulad s licencí (EU, US, APAC) |
16. Režim Orchetrátora
Rídí, zda MazeVault ukládá citlivé hodnoty lokálně nebo je přenáší do externího poskytovatele. Neměnné po první inicializaci.
Viz Šifrování — Režim Orchetrátora pro úplné detaily.
| Proměnná |
Výchozí |
Popis |
MAZEVAULT_ORCHESTRATOR_MODE |
false |
Povolení režimu Orchetrátora — secrets a soukromé klíče jsou přenášeny do Azure Key Vault; lokálně se ukládají pouze metadata |
Neměnné po inicializaci
Jakmile je platforma inicializována s MAZEVAULT_ORCHESTRATOR_MODE=true, toto nastavení nelze změnit. Plánujte režim nasazení před prvním spuštěním.
17. ACME DNS-01
Volitelné proměnné pro automatizaci wildcard certifikátů přes DNS-01 challenge.
| Proměnná |
Výchozí |
Popis |
MAZEVAULT_ACME_DNS_PROVIDER |
none |
DNS poskytovatel pro ACME DNS-01 challenges (cloudflare, none) |
🔐 MAZEVAULT_ACME_DNS_API_TOKEN |
— |
API token pro DNS poskytovatele (šifrován v klidu) |
18. Správa KeyTab (v1.0.36+)
Volitelné proměnné pro správu životního cyklu Kerberos KeyTab.
| Proměnná |
Výchozí |
Popis |
MAZEVAULT_KEYTAB_ENABLED |
true |
Povolení modulu správy KeyTab |
MAZEVAULT_KEYTAB_MAX_SIZE_MB |
10 |
Maximální velikost nahrávaného keytab souboru v MB |
MAZEVAULT_KEYTAB_DEFAULT_EXPIRY_DAYS |
365 |
Výchozí doba exspirace pro nově importované keytaby |
19. Binárky agenta
Backend servíruje agentům podepsané binárky. Hledá je v tomto pořadí: adresář přibalený v image backendu (/opt/mazevault/agent-binaries/<verze>/), disková cache, potom MazeVault Harbor (OCI artefakt) s dočasnými přístupovými údaji od licenčního serveru. V backendu se žádné přihlašovací údaje k registru nenastavují. Gateway licenci nemá: chybějící verze místo z Harboru stahuje od svého primary, proto na ní AGENT_BINARY_REPOSITORY nemá žádný vliv.
| Proměnná |
Výchozí |
Popis |
AGENT_BINARY_CACHE_DIR |
/data/agent-binaries |
Lokální disková cache pro stažené binárky |
AGENT_BINARY_REPOSITORY |
agents/agent-binaries |
OCI repozitář s binárkami agenta v Harboru; balíčky agenta (deb, rpm, msi) se čtou z agent-packages ve stejném projektu a cachují v <AGENT_BINARY_CACHE_DIR>/packages |
AGENT_VERSION |
latest |
Zastaralé. Výchozí cílová verze obou kanálů politiky verzí agenta (latest = žádná) |
AGENT_MAX_ALLOWED_VERSION |
— |
Zastaralé. Výchozí strop verze v politice verzí agenta |
AGENT_ROLLOUT_PERCENTAGE |
100 |
Zastaralé. Výchozí procento rolloutu obou kanálů (0–100) v politice verzí agenta |
AGENT_MAX_CONCURRENT_DOWNLOADS |
10 |
Maximální počet paralelních stahování binárek |
MAZEVAULT_SERVER_URL |
— |
Veřejné URL backendu — fallback pro self-update odkazy agenta, když reverse proxy nepropaguje hlavičky Origin/Host |
Jakou verzi agenta který agent dostane, určuje politika verzí agenta (Deployment → Agents → Version policy, nebo GET/PUT /api/v1/agents/version-policy): cílová verze, procento rolloutu a pozastavení pro každý aktualizační kanál (early, stable), strop verze, spodní hranice pro rollback min_rollback_version a přiřazení prostředí ke kanálům. AGENT_VERSION, AGENT_MAX_ALLOWED_VERSION a AGENT_ROLLOUT_PERCENTAGE se při dotazech už nečtou: jen při prvním startu primary, dokud není politika uložená, z nich vznikne její výchozí podoba, a dokud jsou nastavené, backend loguje varování o zastarání. Gatewaye je ignorují a řídí se politikou z primary. Po nastavení politiky je odstraňte. Nastavení těchto proměnných poté, co politika existuje, jen zapíše varování o zastarání. Pozor na downgrade: přišpendlené hodnoty AGENT_VERSION / AGENT_MAX_ALLOWED_VERSION se stanou cílovými verzemi a stropem politiky, takže agentům s vyšší verzí bude nabídnut downgrade na ně; abyste tomu předešli, v politice verzí smažte cíle a strop nebo nastavte minimální verzi pro rollback (min_rollback_version).
20. Stack pro gateway
Backend pro každé nasazení gateway vygeneruje Docker Compose stack a instalátor.
| Proměnná |
Výchozí |
Popis |
MAZEVAULT_IMAGE_REGISTRY |
registry.mazevault.com/mazevault |
Registr image backendu ve vygenerovaném stacku gateway; nastavte vlastní zrcadlo, pokud gateway nemůže stahovat z MazeVault Harboru. Compose kit ho výchozí nastaví na IMAGE_REGISTRY instalace a Helm chart na registr z backend.image.repository. Tag image odpovídá verzi primary. |
Vygenerovaný stack vyžaduje MAZEVAULT_GATEWAY_ENVIRONMENT (viz sekce o režimu gateway): instalátor spusťte jako root příkazem sudo MAZEVAULT_GATEWAY_ENVIRONMENT=prod bash install.sh (proměnná patří za sudo, které prostředí volajícího zahazuje), hodnotu uloží do .env stacku.
21. SCEP
| Proměnná |
Výchozí |
Popis |
🔐 SCEP_CHALLENGE_PASSWORD |
— |
Sdílené challengePassword (RFC 8894), které musí poslat každý SCEP enrollment na /api/v1/scep/<ca_id>; platí pro všechny interní CA. Prázdná hodnota odmítne každý SCEP enrollment; GetCACaps a GetCACert fungují dál. V Helmu se nastavuje přes global.keyVault.secretKeys.scepChallengePassword. Nastavením se SCEP zapne pro interní CA všech organizací a kdokoli, kdo hodnotu zná, se může zaregistrovat u kterékoli z nich: v nasazení s více organizacemi ji nastavte jen tehdy, když si všechny organizace navzájem důvěřují, jinak nechte SCEP vypnutý. |
Související