Průvodce nasazením agenta¶

Instalace, konfigurace a provoz agentů MazeVault

Verze dokumentu: 1.1.0
Poslední aktualizace: 2026-10-26

1. Přehled¶

MazeVault Agent je lehký Go binární soubor nasazený na infrastrukturních uzlech. Poskytuje:

Synchronizace tajemství — Automatické doručování tajemství do lokálních aplikací
Objevování certifikátů — Skenování infrastruktury pro certifikáty (souborový systém, JKS, Windows cert store)
Životní cyklus certifikátů — Automatizovaná obnova a nasazení spravovaných certifikátů
Real-time aktualizace — WebSocket připojení pro okamžitá push oznámení
Lokální proxy — Bezpečný proxy pro přístup aplikací k tajemstvím bez přímých API volání
Odolnost při výpadku — Lokální cache zajišťuje provoz během výpadků sítě

2. Podporované platformy¶

Platforma	Architektura	Poznámky
Linux	x86_64, ARM64	Ubuntu, RHEL, Rocky Linux, Debian, Alpine
Windows	x86_64	Windows Server 2019+
Kubernetes	—	Kontejnerový obraz agenta neexistuje; agenta spusťte na uzlech/VM (viz 3.3)

3. Instalace¶

3.1 Linux — Způsoby instalace¶

Způsob	Kdy ho použít
Instalační skript (Deployment → Deploy)	Jednotlivé stroje; stáhne a ověří agenta, nainstaluje službu a zapíše stroj
Balíčky `.deb` / `.rpm` (sekce 3.6)	Flotily spravované vlastními nástroji (Ansible, Puppet, obrazy)
Ruční instalace (sekce 3.2)	Jen tam, kde nejde použít ani jedno z předchozích

Všechny způsoby instalují stejnou podepsanou binárku s rozložením ze sekce 3.2.1.

3.2 Linux — Ruční instalace¶

Dodržte rozložení ze sekce 3.2.1: binárka musí zůstat v /opt/mazevault-agent/bin, kam uživatel agenta smí zapisovat kvůli samoaktualizaci. Ručně stažená binárka není ověřená podpisem; instalační skript i balíčky ji ověřují.

# Uživatel služby a adresáře
sudo useradd --system --no-create-home --shell /usr/sbin/nologin mazevault-agent
sudo install -d -o mazevault-agent -g mazevault-agent -m 0750 \
  /opt/mazevault-agent/bin /etc/mazevault /etc/mazevault/certs /var/lib/mazevault /var/log/mazevault

# Binárka agenta (na ARM linux-arm64)
curl -fsSL https://vault.example.com/api/v1/agents/download/linux-amd64 -o mazevault-agent
sudo install -o mazevault-agent -g mazevault-agent -m 0755 mazevault-agent /opt/mazevault-agent/bin/mazevault-agent

Vytvořte /etc/systemd/system/mazevault-agent.service (stejná unita jako u instalačního skriptu a balíčků):

[Unit]
Description=MazeVault Certificate Management Agent
Documentation=https://mazevault.com
After=network-online.target
Wants=network-online.target
# A package install without configuration stays idle until agent.yaml or an enrollment file exists.
ConditionPathExists=|/etc/mazevault/agent.yaml
ConditionPathExists=|/etc/mazevault/enroll.conf

[Service]
Type=simple
User=mazevault-agent
Group=mazevault-agent
ExecStart=/opt/mazevault-agent/bin/mazevault-agent -config /etc/mazevault/agent.yaml
Restart=always
RestartSec=5s
# Exit code 78 is an invalid configuration: a restart cannot fix it.
RestartPreventExitStatus=78
LimitNOFILE=65536

# Security hardening
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=read-only
ReadWritePaths=/opt/mazevault-agent/bin /var/lib/mazevault /var/log/mazevault /etc/mazevault
PrivateTmp=true

Environment=MAZEVAULT_LOG_LEVEL=info

[Install]
WantedBy=multi-user.target

Potom stroj zapište (sekce 3.5); enroll zapíše agent.yaml a spustí službu:

sudo systemctl daemon-reload
sudo systemctl enable mazevault-agent
sudo /opt/mazevault-agent/bin/mazevault-agent enroll --server https://vault.example.com --token mvbt_xxxxxxxxxxxxx

3.2.1 Linux — Rozložení instalované nasazovacím skriptem¶

Instalační skript generovaný v Nasazení → Nasadit (a balíček rpm/deb) používá toto rozložení. Je navržené pro hardened hostitele (CIS/STIG baseline), kde jsou /var a /tmp připojeny s noexec a SELinux je v režimu enforcing.

Cesta	Účel	Vlastník / práva
`/opt/mazevault-agent/bin/mazevault-agent`	Binárka agenta. Mimo `/var` (`noexec`), výchozí SELinux label `bin_t`. Adresář je zapisovatelný pro uživatele agenta, protože self-update připravuje novou binárku vedle běžící a runner vzdálené odinstalace spouští její kopii odtud	`mazevault-agent`, `0750` adresář / `0755` soubor
`/etc/mazevault/agent.yaml`	Konfigurace a stav (`agent.crt`, `agent.key`)	`mazevault-agent`, `0640`
`/etc/mazevault/certs`	Nasazené certifikáty (`cert_store_path`)	`mazevault-agent`, `0750`
`/var/log/mazevault`	Logy	`mazevault-agent`, `0750`
`/etc/systemd/system/mazevault-agent.service`	Unita: `ProtectSystem=strict`, `ReadWritePaths=/opt/mazevault-agent/bin /var/lib/mazevault /var/log/mazevault /etc/mazevault`	`root`, `0644`

Skript je idempotentní a lze jej bezpečně spustit opakovaně: před povolením služby ověří hostitele a migruje hostitele instalované s předchozím rozložením (binárka v /var/lib/mazevault/bin, drop-in přepisy ExecStart).

Krok	Chování
Preflight	Přítomnost potřebných nástrojů; `/opt/mazevault-agent/bin` není na `noexec` připojení; detekce režimu SELinux
Stažení	Ověření certifikátu se nikdy nevypíná. S CA MazeVault (`MAZEVAULT_CA_FILE` na serveru) ji stažení použije a při neúspěchu přejde na systémové úložiště důvěryhodných certifikátů; bez ní se použije systémové úložiště a žádný `ca.crt` se nezapisuje (`server_ca_file` zůstane prázdné)
Ověření	Kontrola ELF a velikosti; cosign podpis zaslaný serverem (`X-Signature`, `X-Signature-Key-Id`) se ověří proti podpisovým klíčům vloženým ve skriptu a `X-SHA256` se porovná se staženým souborem, takže nepodepsaný, pozměněný nebo useknutý přenos je odmítnut. Při neúspěšném stažení (včetně přenosu přerušeného po HTTP 200) se vypíše HTTP stav a tělo odpovědi serveru
Zkušební spuštění	Nová binárka se připraví jako `mazevault-agent.new` vedle cílové cesty a spustí se jako `mazevault-agent` (`mazevault-agent version`) před tím, než nahradí nainstalovanou binárku a než se zapíše unita — `noexec` připojení, zamítnutí SELinuxem nebo binárka sestavená pro novější glibc instalátor zastaví, dříve nainstalovaného agenta nechá nedotčeného a systemd nikdy neskončí v restartovací smyčce
SELinux	V režimu enforcing a s dostupným `semanage` se `/opt/mazevault-agent/bin` explicitně označí jako `bin_t`
Start	`systemctl enable` + `restart`; vypíše se výsledný stav a poslední řádky journalu s redigovanými tokeny a UUID

Návratové kódy: 2 selhal preflight, 3 selhalo stažení nebo ověření binárky, 4 služba se nespustila.

Hardened hostitelé

Nepřesouvejte binárku do adresáře vlastněného rootem, např. /usr/local/bin: self-update potřebuje adresář zapisovatelný uživatelem agenta a uvedený v ReadWritePaths.
Agenti před verzí 1.0.61 byli dynamicky linkovaní a vyžadovali glibc ≥ 2.34; na RHEL/Rocky/AlmaLinux 8 neběží (GLIBC_2.34 not found). Od 1.0.61 je agent linkován staticky.
Vzdálená odinstalace (Nasazení → Agenti) vyžaduje běh agenta jako root; agenti instalovaní skriptem běží jako mazevault-agent, použijte proto ruční kroky v kapitole 9, Životní cyklus agenta.

3.3 Kubernetes¶

MazeVault nepublikuje kontejnerový obraz agenta a režim agenta sidecar není podporovaný. Pro správu certifikátů, které používají workloady v Kubernetes, spusťte agenta na uzlech nebo VM, kde certifikáty leží (sekce 3.1), nebo použijte integrace MazeVault pro Kubernetes secrety. Binárka agenta se vždy stahuje z vašeho MazeVault backendu (/api/v1/agents/download/...), který servíruje podepsané binárky z MazeVault Harboru.

3.4 Windows — služba¶

Na Windows běží agent jako služba MazeVaultAgent (automatický start, LocalSystem, automatický restart při selhání). Instalační skript generovaný v Nasazení → Deploy používá toto rozložení:

Cesta	Účel
`C:\Program Files\MazeVault Agent\mazevault-agent.exe`	Binárka agenta
`C:\ProgramData\MazeVault\`	Konfigurace (`agent.yaml`, `ca.crt`), certifikáty a stav
`C:\ProgramData\MazeVault\logs\agent.log`, `audit.log`	Logy

Skript spouštějte z PowerShellu s právy správce. Lze jej bezpečně spustit opakovaně: opětovné spuštění aktualizuje agenta na místě a instalace z dřívějšího rozložení skriptu (binárka v ProgramData) se migruje. Na hostu, kde je agent nainstalován z balíčku MSI, skript odmítne běžet.

Skript i mazevault-agent enroll omezí přístup k C:\ProgramData\MazeVault\ na SYSTEM a Administrators (dědění oprávnění z ProgramData se zruší), protože adresář obsahuje bootstrap token, privátní klíč agenta a pre-seed soubor. Opětovné spuštění skriptu na existujícím hostu to uplatní i na soubory, které tam už jsou.

Binárka agenta má také podpříkazy install a uninstall, které službu zaregistrují a odeberou; spouštějte je z příkazového řádku s právy správce.

Starší verze

Instalační skript starších verzí selhával s chybou neznámého příkazu install a agent nemohl běžet jako služba Windows. Na takových hostech spusťte nový skript znovu.

3.5 Zápis agenta (`enroll`)¶

mazevault-agent enroll zaregistruje host na serveru jedním krokem:

sudo /opt/mazevault-agent/bin/mazevault-agent enroll --server https://vault.example.com --token mvbt_xxxxxxxxxxxxx --ca-file ./ca.crt

Plná cesta je nutná, protože /opt/mazevault-agent/bin není ve vyhledávací cestě sudo. Na Windows spusťte příkaz z příkazového řádku se zvýšenými oprávněními (Spustit jako správce):

& "C:\Program Files\MazeVault Agent\mazevault-agent.exe" enroll --server https://vault.example.com --token mvbt_xxxxxxxxxxxxx --ca-file .\ca.crt

Na Windows musí být služba už zaregistrovaná (instalátorem MSI nebo příkazem mazevault-agent.exe install); jinak přidejte --no-start a službu zaregistrujte až potom.

Linuxové balíčky

Balíčky .deb/.rpm (sekce 3.6) nevytvářejí agent.yaml, takže enroll i předvyplněný soubor fungují hned po instalaci balíčku. Balíčky dřívějších verzí vytvářely zástupný agent.yaml; na takovém hostu spusťte enroll s --force.

Příkaz zapíše agent.yaml (režim 0640) s výchozími cestami platformy, při zadání --ca-file zkopíruje soubor CA do konfiguračního adresáře jako ca.crt (jinak se použije systémové úložiště důvěry) a poté povolí a restartuje službu.

Volba	Popis
`-config <cesta>`	Globální volba před `enroll`: cesta k zapisovanému `agent.yaml`
`--server <url>`	URL serveru MazeVault; musí být `https`
`--token <token>`	Bootstrap (nasazovací) token
`--ca-file <cesta>`	Certifikát privátní CA, která podepsala certifikát serveru
`--force`	Přepíše existující instalaci (viz níže)
`--no-start`	Pouze zapíše konfiguraci; službu nepovolí ani nerestartuje

enroll odmítne běžet, pokud agent.yaml už existuje. S --force smaže konfiguraci, klientský certifikát a klíč a stav agenta, takže se agent zapíše znovu s novou identitou (certifikát, klíč a recovery token). Server ponechá stejný záznam agenta, pokud se shoduje hostname a ID stroje. --force nemaže ca.crt ani předvyplněný soubor.

Předvyplněný soubor pro automatizované instalace¶

Pro bezobslužné instalace (image, správa konfigurace) umístěte vedle agenta INI soubor místo spuštění enroll:

Platforma	Cesta
Linux	`/etc/mazevault/enroll.conf`
Windows	`C:\ProgramData\MazeVault\enroll.ini`

[enroll]
server_url = https://vault.example.com
bootstrap_token = mvbt_xxxxxxxxxxxxx
server_ca_file = /etc/mazevault/ca.crt

server_ca_file je volitelný. Soubor uložte v kódování ASCII nebo UTF-8 (značka pořadí bajtů – BOM – je přípustná); UTF-16, výchozí kódování některých editorů ve Windows a příkazu Out-File ve Windows PowerShell 5.1, není podporováno. Agent soubor při startu načte, jen pokud agent.yaml neexistuje, převede ho na agent.yaml a smaže; vedle existujícího agent.yaml ho při startu smaže bez načtení (jinak by na disku zůstal token). Neplatný nebo neúplný soubor zůstane zachován a agent se zastaví s chybou konfigurace (kód ukončení 78 na Linuxu; služba Windows se zastaví čistě a nerestartuje se).

3.6 Instalace z balíčků (`.deb`, `.rpm`, `.msi`)¶

Pro instalaci vlastními nástroji (Ansible, Intune, SCCM, GPO, dpkg -i) stáhněte balíčky v Nasazení → Nasadit → Instalace z balíčků (nebo GET /api/v1/agent-packages, oprávnění deployment:read). Každý balíček obsahuje stejnou podepsanou binárku agenta jako instalační skript; MazeVault ověří podpis balíčku dřív, než ho nabídne. Balíčky neobsahují adresu serveru ani token, takže jeden balíček slouží všem hostům. Panel nabízí nejnovější verzi agenta (nebo uvede, že ukazuje přibalenou, když nejnovější nemá dostupné balíčky) a upozorní, když by politika verzí (kanál early nebo stable: cíl nebo strop) agenty z balíčků hned po zápisu přepnula na jinou verzi; před nasazením politiku zkontrolujte.

Balíček	Platformy
`mazevault-agent_<verze>_amd64.deb`, `_arm64.deb`	Debian, Ubuntu
`mazevault-agent-<verze>.x86_64.rpm`, `.aarch64.rpm`	RHEL, Rocky Linux, AlmaLinux, SUSE
`mazevault-agent-<verze>-x64.msi`	Windows Server 2019+ (x64). Windows na ARM: použijte instalační skript

Linux:

sudo apt-get install ./mazevault-agent_1.4.0_amd64.deb        # nebo: sudo dnf install ./mazevault-agent-1.4.0.x86_64.rpm
sudo /opt/mazevault-agent/bin/mazevault-agent enroll --server https://vault.example.com --token mvbt_xxxxxxxxxxxxx

Balíček vytvoří uživatele mazevault-agent a rozložení ze sekce 3.2.1 (unita je v /usr/lib/systemd/system/mazevault-agent.service). Bez agent.yaml nebo předvyplněného souboru je služba povolená, ale zůstane nečinná. Pokud /etc/mazevault/enroll.conf existuje už před instalací balíčku, instalace agenta spustí a ten se sám zapíše; předvyplněný soubor umístěný až po instalaci se načte při dalším startu, proto spusťte sudo systemctl start mazevault-agent (nebo restartujte stroj).

Windows (tichá instalace):

msiexec /i mazevault-agent-1.4.0-x64.msi /qn SERVER_URL=https://vault.example.com BOOTSTRAP_TOKEN=mvbt_xxxxxxxxxxxxx

Vlastnost MSI	Význam
`SERVER_URL`	URL serveru MazeVault (`https`)
`BOOTSTRAP_TOKEN`	Nasazovací token; v logu MSI je skrytý
`SERVER_CA_FILE`	Volitelná cesta k certifikátu privátní CA

MSI je zapíše do předvyplněného souboru C:\ProgramData\MazeVault\enroll.ini, jen když jsou zadány SERVER_URL i BOOTSTRAP_TOKEN, omezí C:\ProgramData\MazeVault\ na SYSTEM a Administrators a spustí službu MazeVaultAgent. Bez těchto vlastností se služba kvůli chybějící konfiguraci čistě zastaví; enroll.ini přidaný později se načte při dalším spuštění služby (Start-Service MazeVaultAgent). Upgrade nebo oprava s vlastnostmi na zapsaném hostu nic nezmění (agent enroll.ini, který tím vznikne, při dalším startu smaže); na jiný server ho přesměrujete příkazem enroll --force.

MSI není podepsané Authenticode

MSI ani .exe agenta zatím nejsou podepsané Authenticode: Windows SmartScreen při interaktivním otevření MSI varuje a AppLocker nebo WDAC mohou vyžadovat pravidlo podle hashe nebo cesty. Jejich integritu chrání podpis MazeVault, který backend ověří dřív, než balíček nabídne.

Jeden token pro mnoho hostů: vytvořte deployment s potřebnou platností a limitem použití (Platnost tokenu, Maximální počet použití; v API expires_in_days, max_uses; v Terraformu mazevault_deployment). Token bez expirace a bez limitu použití umožní zapsat agenta komukoli, kdo ho má; UI na to upozorní.

Aktualizace a správce balíčků: po instalaci se agent aktualizuje sám podle politiky verzí (sekce 6) a binárku nahrazuje na místě. Správce balíčků přitom eviduje verzi nainstalovaného balíčku, takže rpm -V / dpkg --verify hlásí binárku jako změněnou; to je očekávané. Reinstalace nebo upgrade balíčku může nakrátko vrátit binárku z balíčku; agent se při další kontrole aktualizací vrátí na verzi podle politiky.

Odinstalace: sudo apt-get remove mazevault-agent (purge smaže i konfiguraci, identitu, logy a uživatele), sudo dnf remove mazevault-agent (konfigurace a identita zůstanou), na Windows msiexec /x mazevault-agent-<verze>-x64.msi. Vzdálená odinstalace z Nasazení → Agenti u instalací z MSI použije Windows Installer; na Linuxu u instalací z balíčku dostupná není (agent neběží jako root), viz sekce 9.

4. Konfigurace¶

Agent čte agent.yaml (Linux /etc/mazevault/agent.yaml, Windows C:\ProgramData\MazeVault\agent.yaml, případně cestu zadanou přes -config). enroll, předvyplněný soubor i instalační skript do něj zapíšou nastavení potřebná pro připojení; vše ostatní je volitelné. Po změně službu restartujte (sudo systemctl restart mazevault-agent, Restart-Service MazeVaultAgent); mazevault-agent -config <cesta> -validate soubor zkontroluje bez spuštění agenta. S neplatným souborem se agent zastaví s chybou konfigurace (na Linuxu kód ukončení 78).

4.1 Reference `agent.yaml`¶

Výchozí hodnoty platí pro Linux; hodnota pro Windows je uvedena, kde se liší.

Připojení a identita

Klíč	Výchozí	Popis
`server_url`	— (povinné)	URL backendu nebo gatewaye MazeVault. Musí být `https://`; `http://` jen pro `localhost` a loopback adresy
`server_ca_file`	— (systémové úložiště důvěry)	Certifikát CA, která podepsala certifikát serveru (privátní CA)
`cert_pins`	—	Seznam SHA-256 hashů veřejného klíče certifikátu serveru (SPKI), Base64. Když je nastaven, TLS spojení se kromě kontroly CA přijme jen pro uvedený klíč
`bootstrap_token`	—	Nasazovací (bootstrap) token pro první registraci
`client_cert_file`, `client_key_file`	`/etc/mazevault/agent.crt`, `agent.key` (Windows `C:\ProgramData\MazeVault\…`)	Identita agenta (mTLS) vydaná při registraci
`license_key_file`	—	JSON soubor s OAuth klientskými údaji (`oauthClientId`, `oauthClientSecret`), alternativa k bootstrap tokenu
`agent_name`	hostname	Zobrazovaný název v UI

Nastavený musí být aspoň jeden z bootstrap_token, client_cert_file + client_key_file nebo license_key_file.

Úložiště a zápisy

Klíč	Výchozí	Popis
`cert_store_path`	`/var/lib/mazevault/certs` (`enroll` a instalační skript zapisují `/etc/mazevault/certs`; Windows `C:\ProgramData\MazeVault\certs`)	Adresář nasazených certifikátů; pro agenta vždy zapisovatelný. Musí být absolutní
`allowed_write_paths`	viz Povolené adresáře pro zápis (sekce 6)	Adresáře nebo soubory, do kterých smí backend nechat agenta zapisovat; nastavení nahradí výchozí seznam. Jen absolutní cesty
`state_dir`	`/etc/mazevault` (Windows `C:\ProgramData\MazeVault`)	Stav agenta (identita, recovery token, spodní hranice verze)
`install_chain_to_trust_store`	`true`	Instalovat CA a mezilehlé certifikáty nasazených certifikátů do úložiště důvěry OS
`trust_store_path`	zjištěno automaticky	Linuxový adresář kotev důvěry pro `install_chain_to_trust_store`
`allowed_commands`	—	Další regulární výrazy pro příkazy po instalaci, které smí backend po nasazení spustit (navíc k vestavěnému seznamu: `systemctl restart\|reload <unit>`, `service <jméno> restart\|reload`, `nginx -s reload`, `apachectl graceful\|restart`, `iisreset`, `Restart-WebAppPool`); neplatné výrazy se s varováním ignorují

Chování

Klíč	Výchozí	Popis
`sync_interval_seconds`	`3600`	Interval pravidelné synchronizace certifikátů; nejméně `10`
`min_rollback_version`	—	Lokální spodní hranice pro rollback (`[v]X.Y.Z[-pre]`): agent nikdy nenainstaluje nižší verzi, ať politika verzí říká cokoli
`orchestrator_mode`	`false`	Po každé synchronizaci také zjišťovat změny certifikátů provedené mimo MazeVault a hlásit je

Discovery (blok discovery:)

Klíč	Výchozí	Popis
`filesystem_paths`	všechny lokální disky (náhradně `/etc`, `/opt`, `/home`, `/var/lib`, `/srv`; Windows `C:\`)	Adresáře prohledávané na soubory certifikátů a klíčů
`exclude_paths`	—	Cesty, které prohledávání souborů vynechá
`jks_paths`	jako `filesystem_paths`	Adresáře prohledávané na Java keystory
`jks_passwords`	—	Hesla zkoušená při otevírání nalezených keystorů
`windows_stores`	`My`, `Root`, `CA`, `TrustedPublisher`	Prohledávaná úložiště certifikátů Windows (jen Windows)

Logování, health a metriky

Klíč	Výchozí	Popis
`log_level`	`info`	`debug`, `info`, `warn` nebo `error`; na Linuxu ho přebije `MAZEVAULT_LOG_LEVEL` z unity (sekce 4.2)
`log_format`	`text`	`text` nebo `json`
`log_file`	— (stderr, tj. journal; Windows `C:\ProgramData\MazeVault\logs\agent.log`)	Soubor logu; rotuje se při 100 MB, ponechá se 5 souborů
`enable_audit_log`	`false`	Zapisovat lokální auditní log přístupů k souborům a operací backendu
`audit_log_path`	`/var/log/mazevault/audit.log` (Windows `C:\ProgramData\MazeVault\logs\audit.log`)	Soubor auditního logu
`health_listen_addr`	`127.0.0.1:8081`	Adresa lokálního health endpointu (sekce 8)
`metrics_enabled`	`false`	Vystavit metriky pro Prometheus
`metrics_addr`	`127.0.0.1:9090`	Adresa endpointu metrik

Klíče, které agent přijme, ale v této verzi nemají vliv (zůstávají kvůli starším konfiguračním souborům): project_id, windows_store_location, gateway_discovery (enabled, mode, static_urls, dns_pattern, prefer_local), discovery.max_depth, discovery.scan_interval_minutes.

Příklad volitelných nastavení:

server_url: https://vault.example.com
server_ca_file: /etc/mazevault/ca.crt
log_level: info
log_format: json
sync_interval_seconds: 1800
allowed_write_paths:
  - /etc/ssl
  - /opt/tomcat/conf
discovery:
  filesystem_paths: [/etc, /opt]
  exclude_paths: [/opt/backup]
  jks_paths: [/opt/tomcat/conf]
metrics_enabled: true

4.2 Proměnné prostředí¶

Tyto proměnné přebíjejí odpovídající klíče agent.yaml. Unita systemd nastavuje MAZEVAULT_LOG_LEVEL=info, takže na Linuxu log_level v agent.yaml nemá vliv, dokud proměnnou nepřepíšete. Proměnné přidávejte nebo měňte přes sudo systemctl edit mazevault-agent ([Service] Environment=…), ne úpravou unity, kterou instalace nebo upgrade balíčku přepíše.

Proměnná	Přebíjí
`MAZEVAULT_SERVER_URL`	`server_url`
`MAZEVAULT_SERVER_CA_FILE`	`server_ca_file`
`MAZEVAULT_BOOTSTRAP_TOKEN`	`bootstrap_token`
`MAZEVAULT_LICENSE_KEY_FILE`	`license_key_file`
`MAZEVAULT_CLIENT_CERT_FILE`, `MAZEVAULT_CLIENT_KEY_FILE`	`client_cert_file`, `client_key_file`
`MAZEVAULT_AGENT_NAME`	`agent_name`
`MAZEVAULT_PROJECT_ID`	`project_id` (bez vlivu)
`MAZEVAULT_CERT_STORE_PATH`	`cert_store_path`
`MAZEVAULT_STATE_DIR`	`state_dir`
`MAZEVAULT_LOG_LEVEL`, `MAZEVAULT_LOG_FORMAT`, `MAZEVAULT_LOG_FILE`	`log_level`, `log_format`, `log_file`
`MAZEVAULT_HEALTH_ADDR`	`health_listen_addr`
`MAZEVAULT_AGENT_INSTALL_CHAIN_TO_TRUSTSTORE`	`install_chain_to_trust_store` (`true`/`1`)
`MAZEVAULT_AGENT_TRUST_STORE_PATH`	`trust_store_path`

5. Bootstrap a registrace¶

Agent používá dvoufázový autentizační model:

Fáze 1: Bootstrap (jednorázový)¶

Vygenerujte bootstrap token ve webovém UI MazeVault: Nastavení → Nasazení → Agenti → Vygenerovat Bootstrap token
Nakonfigurujte agenta s MAZEVAULT_SERVER_URL a MAZEVAULT_BOOTSTRAP_TOKEN
Spusťte agenta — automaticky se zaregistruje přes POST /api/v1/agents/register

Fáze 2: mTLS (průběžná)¶

Po úspěšné registraci agent obdrží:

Klientský certifikát — Pro mutual TLS autentizaci
CA certifikát — Pro ověření serveru
Heartbeat interval — Doporučená frekvence hlášení stavu
Sync interval — Frekvence synchronizace tajemství

Veškerá další komunikace probíhá přes mTLS. Bootstrap token již není potřeba a může být odvolán.

┌──────────┐          ┌───────────────┐
│  Agent   │──────────│  MazeVault    │
│          │ Bootstrap│  Backend      │
│          │  Token   │               │
│          │◀─────────│               │
│          │ mTLS Cert│               │
│          │          │               │
│          │──────────│               │
│          │ mTLS     │               │
│          │ (průběžně)│               │
└──────────┘          └───────────────┘

Pravidla registrace¶

Nasazovací token nemůže znovu zaregistrovat agenta, který patří jiné organizaci.
Agenti odesílají hashované ID stroje. Dva stroje se stejným hostname, ale různým ID stroje se stávají samostatnými agenty (u agentů této verze).
Agent, který ztratil lokální stav, se může znovu zaregistrovat původním nasazovacím tokenem i po jeho vypršení, ale pouze na stejném stroji a ve stejné organizaci.
Recovery token agenta ho identifikuje i tehdy, když se změnilo jeho ID stroje (například po návratu ke starší verzi agenta).
Záznam staršího agenta (registrovaného bez ID stroje) v jiné organizaci neblokuje hostname: agent této verze, který se registruje nasazovacím tokenem své organizace, se stane novým agentem.

6. Pravidelné operace¶

Agent automaticky spouští několik úloh na pozadí:

Operace	Interval	Popis
Synchronizace tajemství	Konfigurovatelný (výchozí 5m)	Synchronizuje tajemství z backendu do lokálního úložiště
Heartbeat	60 sekund	Hlásí stav, metriky (CPU, paměť, disk) a verzi backendu
Objevování certifikátů	1 hodina	Skenuje nakonfigurované cesty pro certifikáty (filesystem, JKS, Windows cert store)
Objevování konfigurací	Se skenem souborového systému	Skenuje cesty definované politikou pro konfigurační soubory (`.env`, YAML, JSON, INI, properties, TOML, XML), detekuje vložená tajemství a hlásí kandidáty — vyžaduje licenční funkci `config_management`; viz Správa konfigurací
Kontrola aktualizací	24 hodin	Kontroluje dostupnost novější verze agenta
Licenční heartbeat	5 minut	Odesílá telemetrii na licenční server (pokud je nakonfigurován)
K8s reconciliace	5 minut	Reconcilace Kubernetes Secret certifikátů (pouze K8s)
WebSocket reconnect	Exponenciální backoff	Udržuje real-time push připojení (1s → 2s → 4s → ...)

Všechny intervaly jsou fixní kromě synchronizace tajemství (SYNC_INTERVAL_SECONDS).

Aktualizace a spodní hranice pro rollback¶

Při startu a při každé kontrole aktualizací se agent zeptá backendu, jakou verzi mu nabízí politika verzí agenta (viz Proměnné prostředí § Binárky agenta). Novější verzi nainstaluje, nižší jen tehdy, když ji backend označí jako downgrade a není pod spodní hranicí pro rollback agenta. Každá binárka se před výměnou ověří (hash, podpis, hlášená verze). Hranice je nejvyšší z:

hranice zabudované v binárce agenta (zvyšují ji releasy MazeVault),
nejvyšší min_rollback_version, kterou agent přijal od backendu, uložené v <state_dir>/min-rollback-version (backend ji může jen zvýšit),
min_rollback_version v agent.yaml.

# /etc/mazevault/agent.yaml
min_rollback_version: v1.2.0   # nikdy neinstalovat verzi nižší než v1.2.0

Odmítnutou verzi agent zaloguje spolu s běžící verzí, nabízenou verzí a hranicí. Snížit hranici lze jen lokálně: snížení v agent.yaml pod uloženou hodnotu nic nezmění; hodnotu uloženou od backendu smaže

mazevault-agent -config /etc/mazevault/agent.yaml reset-min-rollback-version

Požadavky na nasazení certifikátů¶

Kromě pravidelných úloh posílá backend agentovi přes WebSocket požadavky na nasazení certifikátu, když běží rotace. Agent zpracovává tyto typy:

Požadavek	Co agent udělá
`certificate_sync`	Nainstaluje certifikát s klíčem do keystore (`jks`, `pkcs12`, `windows_my`) a řetězec vydavatelů do trust store platformy. Cíle `windows_root` / `windows_ca` dostávají pouze veřejné certifikáty — privátní klíč se do trust store nikdy nedostane.
`certificate_file_sync`	Zapíše soubory certifikátu podle content mode cíle (`public_only`, `public_chain`, `full_chain_with_key`, `key_only`): leaf, řetězec, klíč a volitelný sloučený bundle (PEM nebo PKCS#12). Privátní materiál má práva `0600`; původní soubory zůstávají jako `.BAK`.
`agent_command`	Spustí příkaz pro krok nasazení (restart služby, WLST restart skript, import do Oracle wallet přes `orapki`, import do trust store přes `keytool`). Spustí se pouze příkazy z allowlistu. Argumenty, které backend označí jako citlivé (hesla store a walletu), agent v auditním logu, odpovědi i chybových zprávách rediguje.

Allowlist příkazů¶

Agent má vestavěný allowlist (systemctl restart|reload, nginx -s reload, apachectl graceful, iisreset, recyklace IIS app poolu, orapki wallet import_pkcs12 nad PKCS#12 připraveným MazeVaultem a jeho úklid, keytool -importcert PEM vydavatele připraveného MazeVaultem do JKS/PKCS12 trust store a jeho úklid). Cokoliv dalšího — včetně WLST restart skriptu WebLogic cíle — je nutné výslovně povolit regulárním výrazem v konfiguraci agenta:

allowed_commands:
  - '^/opt/weblogic/scripts/restart-managed-server\.sh\s+[\w\-\./:= ]+$'

Vzory se porovnávají s celým příkazovým řádkem. Držte je úzké (absolutní cesty, žádné shellové metaznaky) — odmítnutý příkaz ukončí krok nasazení srozumitelnou chybou, místo aby se spustil.

Povolené adresáře pro zápis¶

Soubory, které určí backend (keystore u certificate_sync, soubory certificate_file_sync, cíle secret_sync, keytaby keytab_deploy, obnovené certifikáty, souborové a JKS cíle pravidelné synchronizace), agent zapisuje jen do cert_store_path a do adresářů uvedených v allowed_write_paths. Když allowed_write_paths není nastaveno, platí výchozí /etc/ssl, /etc/pki, /etc/letsencrypt, /etc/nginx/ssl, /etc/nginx/certs, /etc/apache2/ssl, /etc/httpd/ssl, /etc/haproxy/certs, /etc/krb5.keytab, /var/lib/mazevault/certs a /etc/mazevault/certs na Linuxu, C:\ProgramData\MazeVault\certs na Windows. Položka může jmenovat i jednotlivý soubor. Cesty musí být absolutní a nesmí obsahovat ..; symbolické odkazy se před kontrolou rozvinou, takže odkaz uvnitř povoleného adresáře nemůže zápis přesměrovat jinam. Vlastní konfigurace agenta, jeho identita a stavový adresář takto zapsat nejdou nikdy. Doplňte všechny další adresáře, které vaše cíle nasazení používají:

allowed_write_paths:
  - /etc/ssl
  - /opt/tomcat/conf
  - /etc/jira-sync/config.json

Nastavený seznam nahrazuje výchozí hodnoty; položky i cert_store_path musí být absolutní, jinak agent nenastartuje. Na Windows se odmítnou i junctiony a přípojné body v cestě. Odmítnutá cesta ukončí požadavek chybou, která allowed_write_paths jmenuje; pravidelná synchronizace certifikátů (souborové a JKS cíle) odmítnutí jen zapíše do logu agenta, proto v něm po upgradu hledejte allowed_write_paths.

Požadavky na verzi agenta

certificate_file_sync, agent_command a sémantika „pouze veřejné“ u windows_root/windows_ca vyžadují tuto nebo novější verzi agenta. Starší agent na takový požadavek odpoví explicitní chybou unsupported message type a krok nasazení selže rychle, místo aby materiál skončil na špatném místě.

7. Objevování certifikátů¶

Agent objevuje certifikáty napříč infrastrukturou a hlásí je backendu:

Zdroje objevování¶

Zdroj	Platforma	Popis
Souborový systém	Linux/Windows	Skenuje nakonfigurované adresáře pro PEM, DER, PFX soubory
Java KeyStore (JKS)	Všechny	Parsuje `.jks` a `.p12` soubory
Windows Certificate Store	Windows	Enumeruje systémové a uživatelské certifikátové úložiště
Kubernetes Secrets	K8s	Sleduje `kubernetes.io/tls` secrets

Konfigurace objevování¶

Cesty pro objevování se konfigurují ve webovém UI MazeVault:

Projekt → Nastavení → Objevování agenta → Cesty

Výsledky se zobrazí v pohledu Objevené certifikáty na dashboardu.

Discovery konfiguračních souborů se řídí šablonami discovery politik na úrovni organizace, nikoli výše uvedenými cestami; výsledky se zobrazují pod Enterprise Functions → Configuration Management → Discovered Configurations. Viz Správa konfigurací. Agenti také mohou doručovat externě vydané API tokeny do konfiguračních souborů jako cíle nasazení typu agent_file; viz Správa tokenů.

8. Monitoring¶

Endpoint stavu¶

Agent hlásí stav prostřednictvím heartbeatu. Monitorujte stav agentů ve webovém UI:

Nasazení → Agenti

Klíčové hlášené metriky¶

cpu_percent — Vytížení CPU agenta
memory_percent — Využití paměti agenta
secrets_synced — Počet synchronizovaných tajemství
certificates_managed — Počet spravovaných certifikátů
last_sync_time — Časové razítko poslední úspěšné synchronizace
uptime_seconds — Doba běhu agenta

Prometheus metriky¶

Backend vystavuje metriky agentů na /metrics:

mazevault_agents_online{environment="production"} 12
mazevault_agent_sync_operations_total{agent_id="agt_xyz"} 1842
mazevault_agent_discovery_findings_total{agent_id="agt_xyz"} 37

9. Řešení problémů¶

Agent se nespustí¶

# Kontrola logů
journalctl -u mazevault-agent -f

# Ověření konektivity
curl -sk https://vault.example.com/api/v1/health

Problém	Příčina	Řešení
`connection refused`	Backend nedostupný	Ověřte `MAZEVAULT_SERVER_URL` a pravidla firewallu
`certificate expired`	Certifikát agenta vypršel	Znovu zaregistrujte s novým bootstrap tokenem
`bootstrap token invalid`	Token vypršel nebo byl použit	Vygenerujte nový bootstrap token ve webovém UI
`TLS handshake error`	Neshoda CA certifikátu	Ověřte řetězec CA certifikátů
`status=203/EXEC` v `systemctl status`	systemd nemůže binárku spustit: `noexec` připojení (typicky `/var`), SELinux label nebo chybějící právo spuštění	Spusťte znovu instalační skript (instaluje do `/opt/mazevault-agent/bin`, viz 3.2.1); zkontrolujte `findmnt -T <adresář binárky>` a `ls -Z`
`GLIBC_2.34' not found`	Agent starší než 1.0.61 na hostiteli s glibc < 2.34 (RHEL/Rocky/Alma 8)	Nainstalujte agenta 1.0.61 nebo novějšího (staticky linkovaný)
Instalátor skončí kódem `2`, `3` nebo `4`	Selhal preflight, stažení/ověření, nebo start služby	Přečtěte vypsaný důvod; `3` s `HTTP 503` znamená, že server nemá nakonfigurované binárky agenta

Životní cyklus agenta (Nasazení → Agenti)¶

Registrovaní agenti se spravují v sekci Nasazení → Agenti přes nabídku akcí u každého řádku. Tyto operace pracují s identitou nainstalovaného agenta v řídicí rovině MazeVault a jsou odlišné od smazání vygenerovaného instalačního záznamu v sekci Nasazení → Nasadit.

Akce	Co dělá	Kdy použít
Unregister (odregistrovat)	Vyřadí agenta, zneplatní jeho mTLS identitu a recovery tokeny, deaktivuje vazby na projekty a zablokuje veškeré budoucí runtime použití. Historie zůstává zachována. Zvolením bezpečnostní kategorie důvodu (kompromitace / ztracený credential / odcizený host) se akce zaznamená jako revokace.	Vyřazené, ztracené, offline nebo ručně odstraněné hosty.
Remote uninstall (vzdálená odinstalace)	Požádá připojeného agenta, aby se sám odinstaloval z hosta, a před dokončením nahlásí skutečný výsledek zpět. Podporováno na Linuxu (balíčková systemd instalace, agent běžící jako root) a na Windows (MSI service instalace; služba `MazeVaultAgent` je odebrána přes `msiexec`). Agent musí být aktuálně připojen. Agent je vyřazen až po potvrzení úspěšného odstranění; pokud odstranění selže, agent zůstane aktivní a konzole zobrazí Uninstall failed pro opakování nebo zásah.	Čisté odstranění agenta z dostupného Linux nebo Windows hosta.
Re-register / Renew identity (přeregistrovat / obnovit identitu)	Vyřadí starou identitu a vydá jednorázový náhradní bootstrap token (platnost 24 h) pro opětovné zaregistrování hosta.	Vypršený nebo kompromitovaný mTLS certifikát; výměna hosta.

Před odregistrací se zobrazí náhled dopadu (spravované certifikáty, vazby na projekty, rotační cíle, čekající keytab práce). Nevyřešená práce, jako čekající keytab nasazení nebo aktivně spravované certifikáty, vyžaduje pro pokračování volbu Force.

Odregistrace neodinstaluje binárku na hostu. Pro offline hosty nebo tam, kde vzdálená odinstalace není podporována (nebalíčkové/ruční instalace, macOS), agenta odregistrujte a odstraňte lokálně.

Linux:

sudo systemctl stop mazevault-agent && sudo systemctl disable mazevault-agent
sudo apt remove mazevault-agent   # nebo: sudo rpm -e mazevault-agent
sudo rm -rf /etc/mazevault /var/lib/mazevault /var/log/mazevault /opt/mazevault-agent

Windows (PowerShell, s oprávněním administrátora):

$p = Get-WmiObject Win32_Product -Filter "Name='MazeVault Agent'"
if ($p) {
    $p.Uninstall()    # instalováno z balíčku MSI
} else {
    # instalováno skriptem: zastaví a smaže službu MazeVaultAgent
    & "C:\Program Files\MazeVault Agent\mazevault-agent.exe" -config C:\ProgramData\MazeVault\agent.yaml uninstall
    Remove-Item -Recurse -Force "C:\Program Files\MazeVault Agent" -ErrorAction SilentlyContinue
}
Remove-Item -Recurse -Force "$env:ProgramData\MazeVault" -ErrorAction SilentlyContinue

Starší instalace na Windows mají binárku v C:\ProgramData\MazeVault\; příkaz uninstall spusťte z ní.

Opětovná registrace¶

Pokud mTLS certifikát agenta vyprší nebo je kompromitován:

V sekci Nasazení → Agenti otevřete nabídku akcí agenta a zvolte Re-register / Renew identity (nebo Unregister s bezpečnostním důvodem u kompromitovaného hosta).
Zkopírujte jednorázový náhradní bootstrap token z dialogu.
Odstraňte lokální stav na hostu: rm -rf /etc/mazevault/agent.state (Windows: soubor agent.state v C:\ProgramData\MazeVault\). Alternativně spusťte mazevault-agent enroll --force s novým tokenem, což smaže konfiguraci, klientský certifikát, klíč i stav — agent získá novou identitu (certifikát, klíč a recovery token) a server ponechá stejný záznam agenta, pokud se shoduje hostname a ID stroje.
Restartujte agenta s novým MAZEVAULT_BOOTSTRAP_TOKEN.

Token musí patřit stejné organizaci jako agent; token jiné organizace je zamítnut. Agent, který ztratil lokální stav, se může znovu zaregistrovat i původním nasazovacím tokenem po jeho vypršení, ale pouze na stejném stroji a ve stejné organizaci (viz Pravidla registrace v kapitole 5).

Ladící logování¶

Povolte podrobné logování pro diagnostiku:

MAZEVAULT_LOG_LEVEL=debug mazevault-agent

10. Bezpečnostní aspekty¶

Bootstrap tokeny jsou jednorázové a časově omezené (výchozí: 24 hodin)
mTLS certifikáty jsou vázány na konkrétního agenta a projekt
Data tajemství jsou šifrována při přenosu (TLS 1.2+) a lokálně uložena šifrovaně
Minimální oprávnění — agenti mají přístup pouze k tajemstvím přiřazeným jejich projektu
Žádné příchozí porty — agent iniciuje veškerá spojení (pouze odchozí)

Související¶

Agents API — REST API reference pro endpointy agentů
FAQ — Často kladené otázky
Škálování — Doporučení pro škálování agentů
Autentizace — Detaily autentizace agentů
Monitoring — Prometheus metriky pro agenty