Skip to main content
Vector can be run as a systemd service on Linux systems, providing automatic startup, restart on failure, and integration with system logging.

​
Installation

​
From Package Manager

The easiest way to install Vector with systemd support: Ubuntu/Debian: 
curl -1sLf 'https://repositories.timber.io/public/vector/cfg/setup/bash.deb.sh' | sudo bash
sudo apt-get install vector
RHEL/CentOS: 
curl -1sLf 'https://repositories.timber.io/public/vector/cfg/setup/bash.rpm.sh' | sudo bash
sudo yum install vector
Arch Linux: 
sudo pacman -S vector

​
From Installation Script

curl --proto '=https' --tlsv1.2 -sSf https://sh.vector.dev | bash

​
Systemd Service File

The default systemd service file is installed at /etc/systemd/system/vector.service: 
[Unit]
Description=Vector
Documentation=https://vector.dev
After=network-online.target
Requires=network-online.target

[Service]
User=vector
Group=vector
ExecStartPre=/usr/bin/vector validate
ExecStart=/usr/bin/vector
ExecReload=/usr/bin/vector validate --no-environment
ExecReload=/bin/kill -HUP $MAINPID
Restart=always
AmbientCapabilities=CAP_NET_BIND_SERVICE
EnvironmentFile=-/etc/default/vector
StartLimitInterval=10
StartLimitBurst=5

[Install]
WantedBy=multi-user.target

​
Service File Breakdown

  • User/Group: Runs as dedicated vector user for security
  • ExecStartPre: Validates configuration before starting
  • ExecStart: Starts Vector (config loaded from /etc/vector/vector.yaml)
  • ExecReload: Reloads configuration on systemctl reload vector
  • Restart=always: Automatically restarts on failure
  • AmbientCapabilities: Allows binding to privileged ports (< 1024)
  • EnvironmentFile: Loads environment variables from /etc/default/vector

​
Configuration

​
Default Configuration Location

Vector reads configuration from /etc/vector/vector.yaml: 
data_dir: /var/lib/vector

sources:
  syslog:
    type: file
    include:
      - /var/log/syslog
      - /var/log/auth.log
  
  host_metrics:
    type: host_metrics
    collectors:
      - cpu
      - disk
      - memory
      - network

transforms:
  parse_syslog:
    type: remap
    inputs: ["syslog"]
    source: |
      . = parse_syslog!(.message)

sinks:
  to_aggregator:
    type: vector
    inputs: ["parse_syslog", "host_metrics"]
    address: "aggregator.example.com:6000"
    version: "2"

​
Environment Variables

Create /etc/default/vector to set environment variables: 
# /etc/default/vector
# Environment variables for Vector

# Log level (trace, debug, info, warn, error)
VECTOR_LOG=info

# Number of threads
VECTOR_THREADS=4

# Custom config location (optional)
# VECTOR_CONFIG=/etc/vector/custom.yaml

# API settings
# VECTOR_API_ENABLED=true
# VECTOR_API_ADDRESS=127.0.0.1:8686

# Credentials (use systemd credentials instead for better security)
# AWS_ACCESS_KEY_ID=your_key
# AWS_SECRET_ACCESS_KEY=your_secret

​
Service Management

​
Start Vector

sudo systemctl start vector

​
Enable at boot

sudo systemctl enable vector

​
Stop Vector

sudo systemctl stop vector

​
Restart Vector

sudo systemctl restart vector

​
Reload configuration

# Graceful reload without dropping data
sudo systemctl reload vector

​
Check status

sudo systemctl status vector

​
View logs

# View recent logs
sudo journalctl -u vector

# Follow logs
sudo journalctl -u vector -f

# Last 100 lines
sudo journalctl -u vector -n 100

# Logs since boot
sudo journalctl -u vector -b

# Logs for specific time range
sudo journalctl -u vector --since "2024-01-01 00:00:00" --until "2024-01-01 23:59:59"

​
Hardened Service Configuration

For production environments, use the hardened service file with additional security restrictions: 
# /etc/systemd/system/vector.service
# Experimental service configuration for a hardened Vector

[Unit]
Description=Vector
Documentation=https://vector.dev
After=network-online.target
Requires=network-online.target

[Service]
EnvironmentFile=-/etc/default/vector
User=vector
Group=vector
ExecStartPre=/usr/bin/vector validate
ExecStart=/usr/bin/vector
ExecReload=/usr/bin/vector validate
ExecReload=/bin/kill -HUP $MAINPID
Restart=no

# Capabilities
AmbientCapabilities=CAP_NET_BIND_SERVICE
CapabilityBoundingSet=CAP_NET_BIND_SERVICE

# Sandboxing
ProtectHostname=yes
ProtectClock=yes
ProtectKernelTunables=yes
ProtectKernelModules=yes
ProtectKernelLogs=yes
ProtectSystem=strict
ProtectHome=yes
StateDirectory=vector
ProtectControlGroups=yes
PrivateTmp=yes
PrivateDevices=yes
RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6
LockPersonality=yes
MemoryDenyWriteExecute=yes
RestrictRealtime=yes
RestrictSUIDSGID=yes
NoNewPrivileges=yes
RemoveIPC=yes
RestrictNamespaces=yes

# Syscall filtering
SystemCallFilter=@system-service @debug
SystemCallArchitectures=native

# Process properties
UMask=077

[Install]
WantedBy=multi-user.target
Apply the hardened configuration: 
sudo cp /usr/lib/systemd/system/vector.service /etc/systemd/system/vector.service
# Edit with your hardened configuration
sudo systemctl daemon-reload
sudo systemctl restart vector

​
Security Features Explained

  • ProtectSystem=strict: Makes /usr, /boot, /efi read-only
  • ProtectHome=yes: Makes /home inaccessible
  • PrivateTmp=yes: Provides isolated /tmp directory
  • PrivateDevices=yes: Limits device access
  • RestrictAddressFamilies: Limits to Unix, IPv4, and IPv6 sockets only
  • NoNewPrivileges=yes: Prevents privilege escalation
  • SystemCallFilter: Restricts allowed system calls
  • MemoryDenyWriteExecute=yes: Prevents memory exploitation techniques

​
Multi-Instance Deployment

Run multiple Vector instances on the same host:

​
Create Instance Configuration

# Create instance directories
sudo mkdir -p /etc/vector/instances/{agent,aggregator}
sudo mkdir -p /var/lib/vector/{agent,aggregator}

​
Agent Instance Service

# /etc/systemd/system/vector-agent.service
[Unit]
Description=Vector Agent
Documentation=https://vector.dev
After=network-online.target
Requires=network-online.target

[Service]
User=vector
Group=vector
ExecStartPre=/usr/bin/vector validate --config-yaml /etc/vector/instances/agent/vector.yaml
ExecStart=/usr/bin/vector --config-yaml /etc/vector/instances/agent/vector.yaml
Restart=always
EnvironmentFile=-/etc/default/vector-agent

[Install]
WantedBy=multi-user.target

​
Aggregator Instance Service

# /etc/systemd/system/vector-aggregator.service
[Unit]
Description=Vector Aggregator
Documentation=https://vector.dev
After=network-online.target
Requires=network-online.target

[Service]
User=vector
Group=vector
ExecStartPre=/usr/bin/vector validate --config-yaml /etc/vector/instances/aggregator/vector.yaml
ExecStart=/usr/bin/vector --config-yaml /etc/vector/instances/aggregator/vector.yaml
Restart=always
EnvironmentFile=-/etc/default/vector-aggregator

[Install]
WantedBy=multi-user.target

​
Enable and Start Instances

sudo systemctl daemon-reload
sudo systemctl enable vector-agent vector-aggregator
sudo systemctl start vector-agent vector-aggregator

​
User and Permissions

The Vector service runs as the vector user, created during installation: 
# Check user exists
id vector

# Add vector user to additional groups if needed
sudo usermod -aG adm vector  # For reading /var/log
sudo usermod -aG systemd-journal vector  # For reading systemd journal

​
File Permissions

# Configuration files
sudo chown -R vector:vector /etc/vector
sudo chmod 640 /etc/vector/vector.yaml

# Data directory
sudo chown -R vector:vector /var/lib/vector
sudo chmod 755 /var/lib/vector

# Log file access (if reading logs)
sudo usermod -aG adm vector

​
Monitoring and Debugging

​
Check Vector is running

sudo systemctl is-active vector
sudo systemctl is-enabled vector

​
View resource usage

systemctl status vector

​
Detailed status

sudo systemctl show vector

​
Validate configuration

sudo -u vector vector validate --config-yaml /etc/vector/vector.yaml

​
Check Vector version

vector --version

​
Test configuration changes

# Validate before applying
sudo vector validate --config-yaml /etc/vector/vector.yaml

# If valid, reload
sudo systemctl reload vector

​
Troubleshooting

​
Service fails to start

# Check detailed error
sudo journalctl -u vector -n 50 --no-pager

# Validate configuration
sudo vector validate

# Check file permissions
ls -la /etc/vector/vector.yaml
ls -la /var/lib/vector

# Test running as vector user
sudo -u vector vector validate

​
Configuration reload fails

# Validate config syntax
sudo vector validate

# Check for lock files
sudo ls -la /var/lib/vector/

# View reload logs
sudo journalctl -u vector --since "5 minutes ago"

​
High memory usage

# Check memory usage
systemctl status vector

# View detailed metrics
sudo systemctl show vector | grep Memory

# Enable memory limits
sudo systemctl edit vector
# Add:
# [Service]
# MemoryMax=1G
# MemoryHigh=800M

​
Permission denied errors

# Check Vector can read logs
sudo -u vector cat /var/log/syslog

# Add to required groups
sudo usermod -aG adm,systemd-journal vector

# Restart service
sudo systemctl restart vector

​
Upgrading

​
Using Package Manager

# Ubuntu/Debian
sudo apt-get update
sudo apt-get upgrade vector

# RHEL/CentOS
sudo yum update vector

# Restart service
sudo systemctl restart vector

​
Manual Upgrade

# Stop service
sudo systemctl stop vector

# Backup configuration
sudo cp -r /etc/vector /etc/vector.backup

# Install new version
curl --proto '=https' --tlsv1.2 -sSf https://sh.vector.dev | bash

# Validate configuration with new version
vector validate

# Start service
sudo systemctl start vector

# Check status
sudo systemctl status vector

​
Best Practices

​
Configuration Management

  • Store configurations in version control
  • Validate configuration before deploying
  • Use /etc/default/vector for environment-specific settings
  • Test changes in non-production first

​
Security

  • Use the hardened service configuration in production
  • Run as dedicated vector user (never root)
  • Apply principle of least privilege for file access
  • Use systemd credentials for secrets instead of environment variables
  • Regularly update Vector to get security patches

​
Reliability

  • Enable automatic restart: Restart=always
  • Configure appropriate restart limits
  • Use disk buffers for critical data pipelines
  • Monitor systemd journal for errors
  • Set up alerting for service failures

​
Performance

  • Tune thread count via VECTOR_THREADS
  • Monitor resource usage with systemctl status
  • Use appropriate log levels (avoid trace in production)
  • Implement log rotation for Vector’s own logs
  • Configure memory limits to prevent OOM

​
Maintenance

  • Regularly check logs: journalctl -u vector
  • Monitor disk usage of /var/lib/vector
  • Test configuration reloads before applying
  • Keep Vector updated to latest stable version
  • Document any custom service file modifications

Build docs developers (and LLMs) love

Get started for freeTalk to us