Agent setup
IMPORTANT: before proceeding, ensure the reporting server is running and reachable from the host you are installing the agent to.
Create system user
Gullveig agents should be set up to use unprivileged user. Skip this step when deploying agent to host with Gullveig reporting server.
useradd -r gullveig
Create configuration directory
By default, all Gullveig agent configuration files should be located in directory /etc/gullveig/
. This is a common
configuration directory shared between agent, server and web user interface. Skip this step when deploying agent
to host with Gullveig reporting server.
mkdir -p /etc/gullveig/
Create the agent data directory
Reporting agents require a directory to store agent metadata - connection settings, etc. By default, the data directory
is located at /var/lib/gullveig/
. Skip this step when deploying agent to a host with Gullveig reporting server.
makdir -p /var/lib/gullveig/
Create agent configuration file
Create a file /etc/gullveig/agent.conf
and edit it with contents shown bellow.
Modify the configuration options where required.
[agent]
# Ident - identifier of this reporting node.
# By default - reverse FQDN of the host.
;ident = com.example.server1
# Data directory for Gullveig agent
;data_dir = /var/lib/gullveig/
# Number of workers to use to gather information.
# By default - the number of CPU cores on the system / 2
;mod_workers = 5
# Seconds to wait between sending reports
;report_delay = 5
# Seconds to wait between reattempting to reconnect to reporting server
;reconnect_delay = 10
# Assume server is down and alert after waiting ~120 seconds for reconnect
;server_ko_grace = 120
# Timeout to wait for server to respond for health checks.
# Increase for slow/unstable networks.
;ping_timeout = 1
[mail]
# Alerting configuration - disabled by default.
# Used to send alerts when agent is not able to reach reporting server.
;enabled = false
;smtp_from = alerts@example.com
;smtp_to = recipient1@example.com recipient2@example.com
;smtp_host = smtp.example.com
;smtp_port = 587
;smtp_user = smtp_user@example.com
;smtp_password = example
# SMTP mode - plain, tls, starttls. By default - tls.
; smtp_mode = tls
[modules]
# Module configuration: [name] = [value]
# For internal mods: [name] = [true|false] to enable or disable module.
# For shell mods: [name] = [file_to_execute]
;mod_facter = true
;mod_fs = true
;mod_lwall = false
;mod_res = true
;mod_systemd = true
;mod_apt = false
;mod_osquery = false
;external_mod = /home/user/example-script.sh arg1 arg2 arg3
[mod_fs]
# Should we ignore read-only file systems? Default: true
;ignore_ro = true
[mod_osquery]
# osquery configuration file
; config = osquery.yml
[mod_systemd]
# Service name = expected status
; dnsmasq = inactive
; nftables = active
Optional - create systemd service
- Create a file
/etc/systemd/system/gullveig-agent.service
- Ensure the file is owned by root:
chown root:root /etc/systemd/system/gullveig-agent.service
- Ensure the file permissions are correct:
chmod 0644 /etc/systemd/system/gullveig-agent.service
- Edit the file with the contents bellow:
# systemd unit file for gullveig-agent
[Unit]
Description=Gullveig Agent
[Service]
ExecStart=gullveig-agent --conf /etc/gullveig/agent.conf
Environment=PYTHONUNBUFFERED=1
Restart=on-failure
User=gullveig
Group=gullveig
[Install]
WantedBy=default.target
Once you have completed the setup, execute systemctl enable gullveig-agent
to enable the agent to start during system
boot and execute systemctl start gullveig-agent
to start the agent service.
Ensure file-system permissions
Path | Owner | Group | Permissions |
---|---|---|---|
/etc/gullveig/agent.conf | gullveig | gullveig | 0440 |
/var/lib/gullveig/ | gullveig | gullveig | 0740 |
/etc/systemd/system/gullveig-agent.service | root | root | 0644 |