171 lines
4.0 KiB
Markdown
171 lines
4.0 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
cp config.env config.local.env
|
|
```
|
|
|
|
### 2. Edit config.local.env for your server
|
|
|
|
Update the values to match your environment:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
./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:
|
|
|
|
```bash
|
|
./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:
|
|
|
|
```bash
|
|
./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:
|
|
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
$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:
|
|
|
|
```bash
|
|
./validate-syntax.sh
|
|
```
|
|
|
|
### Drift detected but server looks correct
|
|
|
|
Check that paths in `config.local.env` match your actual server:
|
|
|
|
```bash
|
|
# On the server:
|
|
ls -la /etc/rsyslog.conf
|
|
ls -la /etc/rsyslog.d/
|
|
```
|
|
|
|
Then compare with your config:
|
|
|
|
```bash
|
|
grep RSYSLOG_MAIN_CONFIG config.local.env
|
|
grep RSYSLOG_CONFIG_DIR config.local.env
|
|
```
|