rsyslog/CONFIGURATION.md

Configuration Guide

This repository can be adapted for different servers through the configuration system.

Quick Start

1. Create your environment-specific configuration

Copy the default configuration template to a local version:

cp config.env config.local.env

2. Edit config.local.env for your server

Update the values to match your environment:

nano config.local.env

Key variables to adjust:

• SERVER_HOSTNAME: Your target server hostname/IP
• RSYSLOG_MAIN_CONFIG: Path to main rsyslog config on server (usually /etc/rsyslog.conf)
• RSYSLOG_CONFIG_DIR: Directory for modular configs on server (usually /etc/rsyslog.d)
• GIT_RSYSLOG_MAIN_CONFIG: Path in Git (usually rsyslog.conf)
• GIT_RSYSLOG_CONFIG_DIR: Path in Git (usually rsyslog.d)

3. Validate your configuration

Check that everything is syntactically correct:

./validate-syntax.sh

This will verify:

• ✓ Shell script syntax
• ✓ Configuration file format
• ✓ Ansible playbook syntax
• ✓ rsyslog config syntax

Configuration File

config.env (Template)

This is the default configuration template checked into Git. Contains all possible options with comments.

Use this as a reference for what variables are available.

config.local.env (Local Override)

Create this file locally for your specific server. It's gitignored to prevent accidental commits of sensitive data.

The scripts load configuration in this order:

1. Look for config.local.env (local overrides)
2. Fall back to config.env (defaults)

This allows you to:

• Keep config.env in Git with generic/default values
• Override locally with config.local.env for your specific server
• Keep secrets and server-specific settings out of Git

How It Works

Running apply.sh

Applies the Git configuration to your server:

./apply.sh

The script will:

1. Load config.local.env (or config.env as fallback)
2. Copy files from Git to the server using paths from config
3. Validate rsyslog syntax
4. Restart rsyslog service

Running drift-check.sh

Checks if the server's configuration matches Git:

./drift-check.sh

The script will:

1. Load configuration
2. Compare each file on the server with the Git version
3. Report any differences (drift)
4. Exit code: 0 if synced, 1 if drift detected

Environment Variables

You can also override config file values using environment variables:

# Use this specific config file
CONFIG_FILE=/path/to/custom.env ./apply.sh

# Or override individual vars
RSYSLOG_CONFIG_DIR=/custom/rsyslog.d ./apply.sh

Adapting for Different Services

To adapt this for a different service (not just rsyslog):

1. Create a new config.env with your service paths:

   # Example: nginx
   MAIN_CONFIG="/etc/nginx/nginx.conf"
   CONFIG_DIR="/etc/nginx/conf.d"
   GIT_MAIN_CONFIG="nginx.conf"
   GIT_CONFIG_DIR="nginx.d"
   VALIDATION_CMD="nginx -t"
   

2. Update apply.sh to use your validation command:

   $VALIDATION_CMD
   

3. Update drift-check.sh if needed (usually no changes needed)

Validation Checklist

Before deploying to a new server:

• config.local.env created and customized
• ./validate-syntax.sh passes all checks
• SSH connectivity to server verified
• Ansible inventory updated with server hostname
• SSH keys configured in CI/CD secrets
• Test on a non-production server first

Troubleshooting

"Configuration file not found"

Make sure you have at least one of these:

• config.local.env (recommended for local use)
• config.env (used as fallback)

Syntax check fails

Run the validation script to identify issues:

./validate-syntax.sh

Drift detected but server looks correct

Check that paths in config.local.env match your actual server:

# On the server:
ls -la /etc/rsyslog.conf
ls -la /etc/rsyslog.d/

Then compare with your config:

grep RSYSLOG_MAIN_CONFIG config.local.env
grep RSYSLOG_CONFIG_DIR config.local.env