rsyslox

README

rsyslox

High-performance REST API for rsyslog/MySQL written in Go.

📖 About

A modern REST API server that queries rsyslog data from a MySQL/MariaDB database and makes it accessible via HTTP/JSON. Perfect for monitoring dashboards, log analysis, and system integration.

🌟 Features

• 🚀 High Performance - Compiled in Go for maximum speed
• 🔍 Advanced Filtering - Multi-value filters for complex queries
• 📊 All Fields - Access to all 25+ SystemEvents columns
• 🔐 Secure - API key authentication, SSL/TLS support
• 🐳 Docker Ready - Complete test environment with live data
• 📝 REST API - Clean JSON responses
• 🎯 RFC-5424 Compliant - Proper syslog severity and facility labels

🚀 Quick Start

Binary Installation (Recommended)

# Download latest release
wget https://github.com/phil-bot/rsyslox/releases/latest/download/rsyslox-linux-amd64

# Install
chmod +x rsyslox-linux-amd64
sudo mv rsyslox-linux-amd64 /usr/local/bin/rsyslox

# Create configuration
cat > .env << EOF
API_KEY=$(openssl rand -hex 32)
DB_HOST=localhost
DB_NAME=Syslog
DB_USER=rsyslog
DB_PASS=your-password
EOF

# Run
rsyslox

Test the API:

curl http://localhost:8000/health
curl -H "X-API-Key: YOUR_KEY" "http://localhost:8000/logs?limit=5"

Docker Test Environment

Perfect for testing with live generated logs:

# Build binary
make build-static

# Start container
cd docker && docker-compose up -d

# Test
curl "http://localhost:8000/logs?limit=5"

→ Full Installation Guide

📚 Documentation

Getting Started

• Installation Guide - All installation methods
• Configuration - Complete configuration
• Quick Examples - Practical examples

API & Usage

• API Reference - All endpoints and parameters
• Troubleshooting - Troubleshooting and FAQ

Administration

• Deployment - Production setup
• Security - Security best practices

Development

• Docker Testing - Test environment
• Contributing - Development guidelines

→ Full Documentation

💡 Examples

Retrieve logs with filters

# All errors from the last hour
curl -H "X-API-Key: YOUR_KEY" \
  "http://localhost:8000/logs?Priority=3&start_date=2025-02-09T09:00:00Z"

# Logs from multiple hosts (Multi-value!)
curl -H "X-API-Key: YOUR_KEY" \
  "http://localhost:8000/logs?FromHost=web01&FromHost=web02&FromHost=db01"

# Combined filters
curl -H "X-API-Key: YOUR_KEY" \
  "http://localhost:8000/logs?FromHost=web01&Priority=3&Priority=4&limit=20"

Query metadata

# All available hosts
curl -H "X-API-Key: YOUR_KEY" "http://localhost:8000/meta/FromHost"

# All priorities with labels
curl -H "X-API-Key: YOUR_KEY" "http://localhost:8000/meta/Priority"

# Hosts that had errors
curl -H "X-API-Key: YOUR_KEY" \
  "http://localhost:8000/meta/FromHost?Priority=3&Priority=4"

→ More Examples

🆕 What's New in v0.2.3?

• ✅ Complete Modularization - Clean code architecture
• ✅ Structured Error Responses - Better API error handling
• ✅ DB Connection String Support - Flexible database configuration
• ✅ Multi-Value Filters - Multiple values per parameter
• ✅ Extended Columns - All 25+ SystemEvents fields

→ Changelog

🗺️ Roadmap

v0.3.0 (Planned)

• Negation filters (exclude, not)
• Advanced filter combinations
• Complex query support

v0.4.0 (Planned)

• Statistics endpoint (/stats)
• Aggregations
• Timeline/Histogram
• WebUI integration

→ GitHub Issues

🤝 Support & Community

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: docs/

🙏 Contributing

Contributions are welcome! Please read the Contributing Guidelines.

1. Fork the repository
2. Create feature branch
3. Make changes & add tests
4. Submit pull request

📄 License

MIT License - see LICENSE for details.

✨ Credits

Created with ❤️ for the syslog community.

Built with:

• Go
• go-sql-driver/mysql
• rsyslog
• MariaDB

---

⭐ Star this project if it helps you!