Agent Configuration
Agent configuration reference
File (Enterprise virt unit). /etc/zcs/agent.yml
Source authority. configs/agent.example.yml
Restart the Agent after YAML changes. Hosting profile uses a different file — Hosting Agent Configuration.
Do not treat agent.operating_mode: edge as a certified public product. Default example protection_model: hybrid does not match the Hosting profile identity. UID/GID filtering is not a stable customer contract.
server
Scroll sideways to see the full table. Use the arrow keys when focused.
| Key | Component | Description | Type | Required | Default | Allowed values | Example | Secret/sensitive | Restart/reload | Edition | Interactions | Source authority |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
server.manager_url | Agent | Primary Manager URL | URL | yes | https URL | https://manager.example.com:8443 | no | restart | Shared | ignored if manager_urls non-empty | agent.example.yml | |
server.manager_urls | Agent | Failover URL list | URL[] | no | empty | https URLs | no | restart | Shared | takes priority when set | agent.example.yml | |
server.token | Agent | One-time bootstrap JWT | string | no | "" | yes | restart | Shared | prefer AGENT_TOKEN; do not keep steady-state JWT in YAML | agent.example.yml | ||
server.verify_tls | Agent | Verify Manager TLS | bool | no | true | true/false | true | no | restart | Shared | keep true | agent.example.yml |
server.allow_insecure_remote_tls | Agent | Break-glass skip verify for non-loopback | bool | no | false | true/false | false | no | restart | Shared | only with verify_tls=false | agent.example.yml |
server.heartbeat_interval | Agent | Heartbeat period | duration | no | 30s | Go duration | 30s | no | restart | Shared | vs Manager agents.timeout | agent.example.yml |
server.custom_ca_path | Agent | Extra CA bundle | path | no | no | restart | Shared | ServerConfig | ||||
server.pre_token | Agent | Pre-registration token | string | enroll | yes | first enroll | Shared | ServerConfig |
agent
Scroll sideways to see the full table. Use the arrow keys when focused.
| Key | Component | Description | Type | Required | Default | Allowed values | Example | Secret/sensitive | Restart/reload | Edition | Interactions | Source authority |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
agent.hostname | Agent | Reported hostname | string | no | host-01 | hostname not IP | host-01 | no | restart | Shared | pre-register hostname | agent.example.yml |
agent.interfaces | Agent | Explicit NICs | list | no | [] | interface names | [] | no | restart | Shared | empty = validated default-route set, never all NICs | agent.example.yml |
agent.vm_bridge_name | Agent | VM bridge for TAP discovery | string | no | viifbr0 | iface | viifbr0 | no | restart | Shared | example name not global | agent.example.yml |
agent.log_level | Agent | Agent log level | string | no | info | debug/info/warn/error | info | no | restart | Shared | agent.example.yml | |
agent.log_file | Agent | Log path | path | no | /var/log/zcs/firewall-agent.log | path or empty stdout | no | restart | Shared | agent.example.yml | ||
agent.protection_model | Agent | Profile family | enum | no | example hybrid | virtualization | hosting | hybrid | virtualization | no | restart | Shared | the hybrid example misleads vs Hosting identity; Hosting v2 uses hosting YAML | agent.example.yml |
agent.operating_mode | Agent | host vs edge | enum | no | host | host | edge | host | no | restart | Shared | edge is not a certified public product | agent.example.yml |
agent.edge.transit_interfaces | Agent | Edge transit NICs | list | if edge | [] | no | restart | Shared | not public product | AgentEdgeConfig | ||
agent.edge.recovery_mode | Agent | Edge recovery | string | if edge | fail_open | fail_open | no | restart | Shared | AgentEdgeConfig |
ebpf
Scroll sideways to see the full table. Use the arrow keys when focused.
| Key | Component | Description | Type | Required | Default | Allowed values | Example | Secret/sensitive | Restart/reload | Edition | Interactions | Source authority |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
ebpf.program_path | Agent | XDP object | path | virt | /opt/zcs/ebpf/firewall.o | path | no | restart | Shared | checksums | agent.example.yml | |
ebpf.tc_program_path | Agent | TC egress object | path | virt | /opt/zcs/ebpf/firewall_egress.o | path | no | restart | Shared | agent.example.yml | ||
ebpf.cgroup_program_path | Agent | UID/GID V3 object | path | no | /opt/zcs/ebpf/uid_gid_filter_v3.o | path | no | restart | Shared | UID/GID not a stable customer contract | agent.example.yml | |
ebpf.enable_uid_gid_filtering | Agent | UID/GID hooks | bool | no | example true | true/false | false until a stable customer contract is published | no | restart | Shared | not packet filter | agent.example.yml |
ebpf.xdp_attach_mode | Agent | XDP attach | enum | no | auto | auto | native | generic | offload | auto | no | restart | Shared | agent.example.yml | |
ebpf.min_kernel_version | Agent | Preflight kernel | string | no | 5.8.0 | dotted version | 5.8.0 | no | restart | Shared | no certified OS/kernel matrix | agent.example.yml |
ebpf.strict_kernel_version_check | Agent | Fail if unreadable | bool | no | true | true/false | true | no | restart | Shared | agent.example.yml | |
ebpf.verify_artifact_integrity | Agent | Checksum objects | bool | no | true | true/false | true | no | restart | Shared | keep on | agent.example.yml |
ebpf.allow_unsigned_artifacts | Agent | Break-glass unsigned | bool | no | false | true/false | false | no | restart | Shared | incident only | agent.example.yml |
ebpf.enable_pinned_maps | Agent | Persist maps | bool | no | true | true/false | true | no | restart | Shared | zwallctl map | agent.example.yml |
ebpf.checksums_manifest_path | Agent | Checksum manifest | path | no | /opt/zcs/ebpf/ebpf_checksums.txt | path | no | restart | Shared | agent.example.yml |
virtualization / metrics / geoip
Scroll sideways to see the full table. Use the arrow keys when focused.
| Key | Component | Description | Type | Required | Default | Allowed values | Example | Secret/sensitive | Restart/reload | Edition | Interactions | Source authority |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
virtualization.enabled | Agent | libvirt inventory | bool | no | true/false | true on KVM hosts | no | restart | Shared | VirtualizationConfig | ||
virtualization.platform | Agent | Virt platform | string | no | kvm | kvm (proxmox/xen strings exist; KVM is the documented path) | kvm | no | restart | Shared | VirtualizationConfig | |
virtualization.libvirt.uri | Agent | libvirt URI | string | no | qemu:///system | URI | qemu:///system | no | restart | Shared | LibvirtConfig | |
virtualization.libvirt.read_only | Agent | Read-only libvirt | bool | no | false | true/false | false | no | restart | Shared | LibvirtConfig | |
metrics.enabled | Agent | Local metrics server | bool | no | false | true/false | false | no | restart | Shared | bind localhost | AgentMetricsConfig |
metrics.bind_address | Agent | Metrics bind | string | no | 127.0.0.1 | IP | 127.0.0.1 | no | restart | Shared | AgentMetricsConfig | |
metrics.port | Agent | Metrics port | int | no | 9090 | 9090 | no | restart | Shared | AgentMetricsConfig | ||
geoip.enabled | Agent | Local GeoIP | bool | no | false | true/false | false | no | restart | Shared | Manager sync preferred | AgentGeoIPConfig |
geoip.database_path | Agent | Local MMDB | path | if enabled | no | restart | Shared | AgentGeoIPConfig |
Updater YAML on the Agent is not a production upgrade path.
Warning: the shipped example serializes detection.profiles as a YAML list (- name: …). The Agent loader expects a map. Do not copy the example list as a guaranteed load; that format is under engineering review. If a copied example fails to parse, this gap is the likely cause.
See also Virtualization Behavior.