Dashboard GitHub

Configuration

Configure the LogFlux Agent and its plugins

This guide covers configuring the LogFlux Agent system, including the main agent daemon and its various plugins.

Quick Setup

After installing the LogFlux Agent, configure the main agent:

1
2
3
4
5

# Edit the main configuration file
sudo nano /etc/logflux-agent/agent.yaml

# Test configuration
logflux -health

Main Agent Configuration

The main configuration file is located at /etc/logflux-agent/agent.yaml and uses YAML format:

1
2
3

# Main LogFlux Agent Configuration
api_key: your-actual-api-key-here    # REQUIRED - LogFlux API key
node: production-server-01           # Node identifier for this agent

Configuration Fields

Field Required Description Example
api_key Yes Your LogFlux API key lf_abcd1234efgh5678ijkl9012mnop3456
node No Unique identifier for this agent (defaults to hostname) production-server-01

API Key Format

LogFlux API keys follow a specific format:

  • Prefix: All keys start with lf_
  • Format: lf_ followed by 32 alphanumeric characters
  • Example: lf_abcd1234efgh5678ijkl9012mnop3456

You can get your API key from the LogFlux dashboard.

Configuration Priority

The LogFlux Agent and CLI use the following configuration priority (highest to lowest):

  1. Command line flags: Override all other settings
  2. Custom config file: Specified with -config flag
  3. Main agent config: /etc/logflux-agent/agent.yaml
  4. Plugin-specific config: /etc/logflux-agent/plugins/<plugin>.yaml
  5. Built-in defaults: Fallback values

Plugin Configuration

Each plugin can have its own configuration file in /etc/logflux-agent/plugins/:

1
2
3
4
5

# Create plugin configuration directory
sudo mkdir -p /etc/logflux-agent/plugins

# Configure CLI plugin
sudo nano /etc/logflux-agent/plugins/cli.yaml

CLI Plugin Configuration

Example configuration for the CLI plugin:

1
2
3
4
5

# CLI Plugin Configuration (/etc/logflux-agent/plugins/cli.yaml)
server_url: /tmp/logflux-agent.sock
api_key: your-api-key-here
node: my-workstation
prefix: CLI

Other Plugin Examples

Syslog Plugin Configuration:

1
2
3

# /etc/logflux-agent/plugins/syslogd.yaml
bind_address: "0.0.0.0:514"
protocol: "both"  # tcp, udp, or both

File Monitoring Plugin Configuration:

1
2
3
4
5
6

# /etc/logflux-agent/plugins/filestream.yaml
files:
  - path: "/var/log/nginx/access.log"
    prefix: "NGINX"
  - path: "/var/log/app/*.log"
    prefix: "APP"

CLI Configuration

For CLI-specific configuration, you can also create a user configuration file:

1
2

# Initialize CLI configuration
logflux -init

This creates a configuration file (location varies by permissions):

  • System-wide: /etc/logflux-agent/cli.yaml (if run with sudo)
  • User-specific: ~/.logflux-cli.yaml (if run as user)

Environment Variables

You can override configuration values using environment variables for the CLI:

1
2
3

export LOGFLUX_API_KEY="lf_abcd1234efgh5678ijkl9012mnop3456"
export LOGFLUX_NODE="my-server"
export LOGFLUX_PREFIX="myapp"

Command line flags take precedence over environment variables.

Security Considerations

API Key Security

  • Never commit API keys to version control
  • Use environment variables in production
  • Rotate API keys periodically
  • Store keys securely using your preferred secrets management solution

File Permissions

Secure your configuration files:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# Set restrictive permissions on main config
sudo chmod 600 /etc/logflux-agent/agent.yaml
sudo chown root:root /etc/logflux-agent/agent.yaml

# Secure plugin configuration directory
sudo chmod 700 /etc/logflux-agent/plugins/
sudo chown -R root:root /etc/logflux-agent/plugins/

# User CLI configuration
chmod 600 ~/.logflux-cli.yaml

Service User

Run the agent service as a dedicated user:

1
2
3
4
5

# Create logflux user
sudo useradd -r -s /bin/false logflux

# Update systemd service to use the user
sudo systemctl edit logflux-agent

Add:

1
2
3

[Service]
User=logflux
Group=logflux

Validation

Test your configuration:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# Check agent service status
sudo systemctl status logflux-agent

# Test CLI connectivity
logflux -health

# Check CLI version
logflux -version

# Send a test message
logflux -message "Configuration test successful"

# Test with verbose output
logflux -message "Debug test" -verbose

Service Management

Manage the LogFlux Agent service:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# Start the agent
sudo systemctl start logflux-agent

# Enable auto-start on boot
sudo systemctl enable logflux-agent

# Check status
sudo systemctl status logflux-agent

# View logs
sudo journalctl -u logflux-agent -f

# Restart after configuration changes
sudo systemctl restart logflux-agent

Common Issues

Agent Service Not Running

1
2
3
4
5
6
7
8

# Check service status
sudo systemctl status logflux-agent

# Check logs for errors
sudo journalctl -u logflux-agent --no-pager

# Restart service
sudo systemctl restart logflux-agent

Invalid API Key

Error: authentication failed: invalid API key
  • Verify your API key starts with lf_
  • Check that the key is exactly 32 characters after the prefix
  • Ensure no extra spaces or characters in the YAML file

Permission Errors

Error: permission denied accessing /tmp/logflux-agent.sock
  • Check file permissions on the socket
  • Ensure your user has access to the LogFlux agent
  • Try running with appropriate permissions

Socket Connection Errors

Error: connection failed: dial unix /tmp/logflux-agent.sock: connect: no such file or directory
  • Ensure the LogFlux Agent service is running
  • Check that the socket path in configuration is correct
  • Verify the agent is listening on the expected socket

Production Setup

For production deployments:

1. Secure Configuration Management

1
2

# Use environment variables for sensitive data
sudo systemctl edit logflux-agent

Add environment variables:

1
2

[Service]
Environment=LOGFLUX_API_KEY=lf_abcd1234efgh5678ijkl9012mnop3456

2. Multiple Environment Setup

Create environment-specific configurations:

1
2
3
4
5

# Production config
sudo cp /etc/logflux-agent/agent.yaml /etc/logflux-agent/agent-prod.yaml

# Development config  
sudo cp /etc/logflux-agent/agent.yaml /etc/logflux-agent/agent-dev.yaml

3. Plugin Management

Enable only required plugins:

1
2
3
4
5

# Enable essential plugins
sudo systemctl enable logflux-syslogd logflux-journald

# Disable unused plugins
sudo systemctl disable logflux-docker logflux-kubernetes

4. Monitoring and Alerting

Set up monitoring for the agent:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# Create monitoring script
cat > /usr/local/bin/logflux-monitor.sh << 'EOF'
#!/bin/bash
if ! logflux -health > /dev/null 2>&1; then
    echo "LogFlux Agent health check failed"
    # Add your alerting logic here
fi
EOF

chmod +x /usr/local/bin/logflux-monitor.sh

# Add to crontab
echo "*/5 * * * * /usr/local/bin/logflux-monitor.sh" | sudo crontab -

Next Steps