{"id":28565693,"url":"https://github.com/cwt/aiosyslogd","last_synced_at":"2026-02-23T04:36:54.856Z","repository":{"id":298232435,"uuid":"998842467","full_name":"cwt/aiosyslogd","owner":"cwt","description":"Asynchronous Syslog server using asyncio, with an optional uvloop integration and SQLite backend.","archived":false,"fork":false,"pushed_at":"2026-02-07T03:08:10.000Z","size":660,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-07T13:49:38.572Z","etag":null,"topics":["asyncio","sqlite","syslog","syslogd"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/aiosyslogd/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cwt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-09T10:40:11.000Z","updated_at":"2026-02-07T03:08:13.000Z","dependencies_parsed_at":"2025-06-25T06:25:13.193Z","dependency_job_id":"c05b98e1-ba8e-4849-8995-b13324a25058","html_url":"https://github.com/cwt/aiosyslogd","commit_stats":null,"previous_names":["cwt/aiosyslogd"],"tags_count":31,"template":false,"template_full_name":null,"purl":"pkg:github/cwt/aiosyslogd","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cwt%2Faiosyslogd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cwt%2Faiosyslogd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cwt%2Faiosyslogd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cwt%2Faiosyslogd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cwt","download_url":"https://codeload.github.com/cwt/aiosyslogd/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cwt%2Faiosyslogd/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29738080,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-23T02:24:00.660Z","status":"ssl_error","status_checked_at":"2026-02-23T02:22:56.087Z","response_time":90,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asyncio","sqlite","syslog","syslogd"],"created_at":"2025-06-10T14:39:58.010Z","updated_at":"2026-02-23T04:36:54.815Z","avatar_url":"https://github.com/cwt.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# **aiosyslogd**\n\n[![PyPI Version](https://img.shields.io/pypi/v/aiosyslogd.svg)](https://pypi.org/project/aiosyslogd/)\n[![Quay.io Build Status](https://quay.io/repository/cwt/aiosyslogd/status \"Quay.io Build Status\")](https://quay.io/repository/cwt/aiosyslogd)\n\n**aiosyslogd** is a high-performance, asynchronous Syslog server built with Python's asyncio. It is designed for efficiently receiving, parsing, and storing a large volume of syslog messages.\n\nIt features an optional integration with uvloop for a significant performance boost and can write messages to a SQLite database or Meilisearch, automatically creating monthly tables/indexes and maintaining a Full-Text Search (FTS) index for fast queries.\n\n## **Key Features**\n\n- **Asynchronous:** Built on asyncio to handle thousands of concurrent messages with minimal overhead.\n- **Fast:** Supports uvloop for a C-based event loop implementation, making it one of the fastest ways to run asyncio.\n- **Flexible Database Backends:**\n  - **SQLite Backend:** Writes all incoming messages to a SQLite database. For easier maintenance and backup, it creates a separate database file for each month (e.g., syslog_YYYYMM.sqlite3). Each file contains a SystemEvents table and a corresponding SystemEvents_FTS virtual table using FTS5 for powerful full-text search.\n  - **Meilisearch Backend:** Optionally stores messages in Meilisearch, a fast and lightweight search engine, with automatic monthly indexes and advanced search capabilities like filtering, sorting, and proximity precision.\n- **Automatic Table/Index Management:** Creates new database files (SQLite) or indexes (Meilisearch) for each month to keep the database organized and fast.\n- **Full-Text Search:** Automatically maintains an FTS5 virtual table (SystemEvents_FTS) for SQLite or fully indexed Meilisearch backend for powerful and fast message searching.\n- **RFC5424 Conversion:** Includes a utility to convert older *RFC3164* formatted messages to the modern *RFC5424* format.\n- **Flexible Configuration:** Configure the server via a simple aiosyslogd.toml file.\n- **Web UI:** A simple web interface for monitoring and searching logs, accessible via a web browser.\n- **Container Support:** Pre-built Docker/Podman images for easy deployment.\n\n## **Running with Containers (Docker / Podman)**\n\nThe most convenient way to run **aiosyslogd** is by using the pre-built container images available on [Quay.io](https://quay.io/repository/cwt/aiosyslogd).\n\n### **Image Tags**\n\nThe container images are automatically built from the GitHub repository:\n\n- Pushes to the `main` branch will build the `quay.io/cwt/aiosyslogd:latest` image.\n- New version tags (e.g., `v0.2.5`) will automatically build a corresponding image (`quay.io/cwt/aiosyslogd:v0.2.5`).\n\n### **Quick Start with Containers**\n\n**1. Pull the Image**\n\nYou can pull the latest image using Docker or Podman:\n\n```bash\n# Using Docker\ndocker pull quay.io/cwt/aiosyslogd:latest\n```\n\n```bash\n# Using Podman\npodman pull quay.io/cwt/aiosyslogd:latest\n```\n\n**2. Run the Server**\n\nTo run the server, you must mount a volume to the /data directory inside the container. This is critical for persisting your configuration and log data.\n\n```bash\n# Run the server using Docker\ndocker run -d \\\n  --name aiosyslogd-server \\\n  -p 5140:5140/udp \\\n  -v /path/to/your/data:/data \\\n  quay.io/cwt/aiosyslogd:latest\n```\n\n```bash\n# Run the web UI using Docker\ndocker run -d \\\n  --name aiosyslogd-web \\\n  -p 5141:5141/tcp \\\n  -v /path/to/your/data:/data,ro \\\n  quay.io/cwt/aiosyslogd:latest \\\n    aiosyslogd-web\n```\n\n**Note:** Be sure to replace /path/to/your/data with a real path on your host machine (e.g., ~/.aiosyslogd/data).\n\n**Explanation of the command:**\n\n- `-d`: Runs the container in detached mode (in the background).\n- `--name aiosyslogd-server` (or `aiosyslogd-web` for the web UI): Assigns a convenient name to your container.\n- `-p 5140:5140/udp`: Maps the syslog server port.\n- `-p 5141:5141/tcp`: Maps the web server port.\n- `-v /path/to/your/data:/data`: (IMPORTANT) Mounts a host directory into the container's data directory, and you should add `,ro` to mount it as a read-only storage for the web UI.\n\nOn the first run, the server will not find a configuration file in the mounted /data volume and will create a default aiosyslogd.toml for you there. You can then edit this file on your host machine to re-configure the server and simply restart the container for the changes to take effect.\n\n## **Installation**\n\nYou can install the package directly from its source repository or via pip.\n\n**Standard Installation:**\n\n```bash\npip install aiosyslogd\n```\n\n**For Maximum Performance (with uvloop/winloop):**\n\nTo include the performance enhancements, install the speed extra:\n\n```bash\npip install 'aiosyslogd[speed]'\n```\n\n## **Quick Start: Running the Server**\n\nThe package installs a command-line script called `aiosyslogd`. You can run it directly from your terminal.\n\n```bash\naiosyslogd\n```\n\nOn the first run, if an `aiosyslogd.toml` file is not found in the current directory, the server will create one with default settings and then start.\n\nThe server will begin listening on `0.0.0.0:5140` and, if enabled in the configuration, create a `syslog.sqlite3` file (SQLite) in the current directory or connect to Meilisearch.\n\n## **Configuration**\n\nThe server is configured using a TOML file. By default, it looks for aiosyslogd.toml in the current working directory.\n\n### **Default aiosyslogd.toml**\n\nIf a configuration file is not found, this default version will be created:\n\n```toml\n[server]\nbind_ip = \"0.0.0.0\"\nbind_port = 5140\ndebug = false\nlog_dump = false\n\n[database]\ndriver = \"sqlite\"\nbatch_size = 100\nbatch_timeout = 5\nsql_dump = false\n\n[web_server]\nbind_ip = \"0.0.0.0\"\nbind_port = 5141\ndebug = false\nredact = false\n\n[database.sqlite]\ndatabase = \"syslog.sqlite3\"\n\n[database.meilisearch]\nurl = \"http://127.0.0.1:7700\"\napi_key = \"\"\n```\n\n#### **Custom Configuration Path**\n\nYou can specify a custom path for the configuration file by setting the `AIOSYSLOGD_CONFIG` environment variable.\n\n```bash\nexport AIOSYSLOGD_CONFIG=\"/etc/aiosyslogd/config.toml\"\naiosyslogd\n```\n\nWhen a custom path is provided, the server will **not** create a default file if it's missing and will exit with an error instead.\n\n### **Configuration Options**\n\n#### **Server Settings**\n\nThese options control the main syslog server behavior:\n\n| Key       | Description                                                            | Default   |\n| :-------- | :--------------------------------------------------------------------- | :-------- |\n| bind_ip   | The IP address the server should bind to.                              | \"0.0.0.0\" |\n| bind_port | The UDP port to listen on.                                             | 5140      |\n| debug     | Set to true to enable verbose logging for parsing and database errors. | false     |\n| log_dump  | Set to true to print every received message to the console.            | false     |\n\n#### **Database Settings**\n\nThese options control how messages are stored:\n\n| Key           | Description                                                              | Default  |\n| :------------ | :----------------------------------------------------------------------- | :------- |\n| driver        | The database backend to use (\"sqlite\" or \"meilisearch\").                 | \"sqlite\" |\n| batch_size    | The number of messages to batch together before writing to the database. | 100      |\n| batch_timeout | The maximum time in seconds to wait before writing an incomplete batch.  | 5        |\n| sql_dump      | Set to true to print the SQLite command and parameters before execution. | false    |\n\n**Note:** When `sql_dump` is enabled, `log_dump` will be automatically disabled.\n\n#### **SQLite Database Settings**\n\nSpecific settings for SQLite backend:\n\n| Key              | Description                                                  | Default          |\n| :--------------- | :----------------------------------------------------------- | :--------------- |\n| database         | The path to the SQLite database file.                        | \"syslog.sqlite3\" |\n| retention_months | Number of months to retain old database files (SQLite only). | 12               |\n\n**Automatic Cleanup of Old Databases:**\n\nThe SQLite driver automatically deletes monthly database files older than the configured `retention_months` period. This cleanup runs:\n\n- On server startup\n- When switching to a new month's database file (at month boundaries)\n\nThe number of monthly database files is counted, keeping only the most recent `retention_months` files. For example, with `retention_months = 12`, only the 12 most recent monthly database files are kept.\n\n**Note:** This includes the current month's file. If you want to retain the current month plus 11 older months, set `retention_months = 12`.\n\nTo delete all old database files, set `retention_months = 0`.\n\n#### **Meilisearch Database Settings**\n\nSpecific settings for Meilisearch backend:\n\n| Key     | Description                             | Default                 |\n| :------ | :-------------------------------------- | :---------------------- |\n| url     | The URL of the Meilisearch instance.    | \"http://127.0.0.1:7700\" |\n| api_key | The API key for Meilisearch (optional). | \"\"                      |\n\n#### **Web Server Settings**\n\nThese options control the web interface:\n\n| Key        | Description                                                  | Default      |\n| :--------- | :----------------------------------------------------------- | :----------- |\n| bind_ip    | The IP address the web server should bind to.                | \"0.0.0.0\"    |\n| bind_port  | The TCP port the web server should listen on.                | 5141         |\n| debug      | Set to true to enable verbose logging for the web server.    | false        |\n| redact     | Set to true to redact sensitive information (user, IP, MAC). | false        |\n| users_file | The path to the JSON file for storing user credentials.      | \"users.json\" |\n\n### **Web Interface Authentication**\n\nThe web interface now includes user authentication to protect access to logs.\n\n#### **First-time Setup**\n\nOn the first run, `aiosyslogd-web` will create a `users.json` file in the same directory as your `aiosyslogd.toml` file. This file will contain a default admin user with the following credentials:\n\n- **Username**: `admin`\n- **Password**: `admin`\n\nYou will be required to log in with these credentials to access the web interface. It is highly recommended to change the default password after your first login.\n\n### **Gemini Natural Language Search**\n\nThe web interface includes an optional Gemini-powered natural language search feature that allows users to describe their search queries in natural language, which are then automatically converted to FTS5 syntax.\n\n#### **Setup**\n\nTo enable this feature:\n\n1. Install the gemini extra: `poetry install --extras \"gemini\"`\n\n**Note**: If you choose not to install the gemini extra, the Gemini button and related UI elements will be automatically hidden from the web interface. The rest of the web UI functionality remains available.\n\n#### **How to Use**\n\n1. **Access the Web Interface**: Navigate to your aiosyslogd-web instance and log in with your credentials.\n\n1. **Click the Gemini Button**: Look for the Gemini logo button (🔍) next to the main search bar.\n\n1. **Configure Gemini API Access** (first time only):\n\n   - If you haven't configured API access before, you'll see instructions to get your Gemini API key\n   - Visit [Google AI Studio](https://makersuite.google.com/app/apikey) to create an account and get your API key\n   - Enter your API key in the modal and save it\n   - Your API key is stored locally in your browser's localStorage and on the server session\n\n1. **Manage Your API Key**:\n\n   - Go to your Profile page to save or clear your API key\n   - Click \"Save API Key\" to store your key in browser's local storage\n   - Click \"Clear API Key\" to remove your stored key\n\n1. **Describe Your Search**:\n\n   - In the modal dialog, describe what you want to search for in natural language\n   - Example: \"Show me all error messages from server1\"\n\n1. **Get the Generated Query**:\n\n   - Gemini will convert your natural language to an appropriate FTS5 query\n   - Review the generated query and click \"Use This Query\" to apply it to your search\n\n#### **Technical Details**\n\n- The feature integrates with Google's Gemini API to convert natural language to FTS5 syntax\n- Generated queries use proper FTS5 operators like AND, OR, NOT, phrase matching, and wildcards\n- API keys are stored in browser's localStorage and used for authentication\n- All API communication is secured with CSRF protection\n- Uses the new `google-genai` library (the `google-generativeai` library has been deprecated)\n\n#### **Privacy Notice**\n\n- Your Gemini API key is stored only in your browser's local storage\n- Search queries are sent to Google's Gemini API for processing using your API key\n- This ensures usage counts against your own quota\n- No logs or search history are stored on the aiosyslogd server as part of this feature\n\n#### **User Roles**\n\nThere are two user roles:\n\n- **Admin**: Can view logs, manage users (add, edit, delete), and change their own password.\n- **User**: Can view logs and change their own password.\n\n#### **Managing Users (Admins only)**\n\nAdmins can access the \"Users\" page from the navigation bar to:\n\n- **Add new users**: Provide a username, password, and specify if the user should be an admin.\n- **Edit existing users**: Change a user's password, admin status, and enable/disable their account.\n- **Delete users**: Remove a user from the system.\n\n#### **Changing Your Password**\n\nAll users can change their own password by clicking on their username in the navigation bar and selecting \"Profile\".\n\n### **Performance Tuning: Finding the Optimal batch_size**\n\nThe `database.batch_size` setting is critical for performance. It controls how many log messages are grouped together before being written to the database.\n\n- A **larger batch_size** can be more efficient for the database but increases the risk of dropping logs under heavy load. If the database write takes too long, the server's incoming network buffer can overflow, causing the operating system to discard new messages.\n- A **smaller batch_size** results in quicker but more frequent database writes, reducing the risk of buffer overflow but potentially increasing I/O overhead.\n\nThe optimal `batch_size` depends heavily on your hardware (CPU, disk speed like NVMe vs. HDD) and network conditions. A `batch_size` of 100 is set as a safe default, but you can likely increase this for better performance.\n\n#### **Using the Log Generation Tool**\n\nA benchmarking script is included at `scripts/loggen.py` to help you find the optimal `batch_size` setting for your system.\n\n1. **Prepare for Testing**:\n\n   - Set `server.debug = true` in your `aiosyslogd.toml` configuration file\n   - Start aiosyslogd: `$ aiosyslogd`\n\n1. **Run the Benchmark**:\n   Open another terminal and run the log generation script to send a large number of messages. For example, to send 100,000 logs:\n\n   ```bash\n   python scripts/loggen.py -n 100000\n   ```\n\n   The script will output the total number of messages sent.\n\n1. **Monitor Server Logs**:\n   When the **aiosyslogd** server writes a batch, it logs the number of messages successfully written:\n\n   ```syslog\n   [2025-06-18 19:30:00] [12345] [DEBUG] Successfully wrote 100 logs to 'syslog_202506.sqlite3'.\n   ```\n\n   Sum up the total number of logs written by the server and compare it to the number sent by `loggen.py`.\n\n1. **Evaluate Results**:\n\n   - If the numbers match, your `batch_size` setting is appropriate for your system\n   - If the server received fewer logs than sent, some messages were dropped\n\n1. **Tune and Repeat**:\n\n   - If you see dropped logs (server received \u003c 100,000), your `batch_size` is too high; decrease it\n   - If all logs are received successfully, you can try increasing the `batch_size` in your `aiosyslogd.toml` file\n   - Repeat the test to find the highest value your specific hardware can handle without dropping packets\n\n## **Running as a Daemon with Auto-Startup**\n\nYou can run **aiosyslogd** as a system service that automatically starts after server reboot. This section describes multiple approaches including Podman Quadlet (easiest), root-less systemd services, and traditional system services.\n\n### **Podman Quadlet Setup (Easiest Method)**\n\nThe easiest way to run **aiosyslogd** as a daemon is using Podman Quadlet, which allows you to define container services using simple configuration files.\n\n#### **1. Install Podman**\n\nMake sure Podman is installed on your system:\n\n```bash\n# On Ubuntu/Debian\nsudo apt install podman\n```\n\n```bash\n# On RHEL/CentOS/Fedora\nsudo dnf install podman\n```\n\n#### **2. Enable Podman Socket**\n\nEnable the Podman socket for root and/or user services:\n\n```bash\n# For root services\nsudo systemctl enable --now podman.socket\n```\n\n```bash\n# For user services (if running as non-root)\nsystemctl --user enable --now podman.socket\n```\n\n#### **3. Create Quadlet Files**\n\nCreate the Quadlet unit files in the appropriate directory:\n\nFor user services: `~/.config/containers/systemd/`\nFor system services: `/etc/containers/systemd/`\n\n**File: ~/.config/containers/systemd/aiosyslogd.container (for user services) or /etc/containers/systemd/aiosyslogd.container (for system services)**\n\n```toml\n[Unit]\nDescription=aiosyslogd - Asynchronous Syslog Server\nAfter=network.target\nWants=network.target\n\n[Container]\nImage=quay.io/cwt/aiosyslogd:latest\nVolume=%h/.aiosyslogd:/data\nNetwork=slirp4netns\nPublishPort=5140:5140/udp\nEnvironment=AIOSYSLOGD_CONFIG=/data/aiosyslogd.toml\nUserNS=keep-id\n\n[Install]\nWantedBy=default.target\n```\n\n**File: ~/.config/containers/systemd/aiosyslogd-web.container (for user services) or /etc/containers/systemd/aiosyslogd-web.container (for system services)**\n\n```toml\n[Unit]\nDescription=aiosyslogd-web - Web Interface for aiosyslogd\nAfter=network.target\nWants=network.target\nBindsTo=aiosyslogd.container\n\n[Container]\nImage=quay.io/cwt/aiosyslogd:latest\nVolume=%h/.aiosyslogd:/data\nNetwork=slirp4netns\nPublishPort=5141:5141/tcp\nEnvironment=AIOSYSLOGD_CONFIG=/data/aiosyslogd.toml\nUserNS=keep-id\nExec=aiosyslogd-web\n\n[Install]\nWantedBy=default.target\n```\n\n#### **4. Create Configuration Directory**\n\nCreate a directory for your configuration files:\n\n```bash\nmkdir -p ~/.aiosyslogd\ncd ~/.aiosyslogd\n```\n\nCopy the default configuration to this directory:\n\n```bash\n# If you have the source code, copy the default config from the config directory\n# Or create it manually with your preferred editor\ncp /path/to/aiosyslogd/config/default-aiosyslogd.toml ~/.aiosyslogd/aiosyslogd.toml\n```\n\n#### **5. Start and Enable Services**\n\nEnable lingering for your user to allow services to start at boot even when not logged in (for user services):\n\n```bash\nsudo loginctl enable-linger $USER\n```\n\nStart and enable the services:\n\n```bash\n# For user services\nsystemctl --user daemon-reload\nsystemctl --user enable aiosyslogd\nsystemctl --user enable aiosyslogd-web\nsystemctl --user start aiosyslogd\nsystemctl --user start aiosyslogd-web\n```\n\n```bash\n# For system services\nsudo systemctl daemon-reload\nsudo systemctl enable aiosyslogd\nsudo systemctl enable aiosyslogd-web\nsudo systemctl start aiosyslogd\nsudo systemctl start aiosyslogd-web\n```\n\nCheck the status of the services:\n\n```bash\n# For user services\nsystemctl --user status aiosyslogd\nsystemctl --user status aiosyslogd-web\n```\n\n```bash\n# For system services\nsudo systemctl status aiosyslogd\nsudo systemctl status aiosyslogd-web\n```\n\nView logs for debugging:\n\n```bash\n# For user services\njournalctl --user-unit aiosyslogd -f\njournalctl --user-unit aiosyslogd-web -f\n```\n\n```bash\n# For system services\nsudo journalctl -u aiosyslogd -f\nsudo journalctl -u aiosyslogd-web -f\n```\n\n### **Root-less Service Setup (Python Installation)**\n\nIf you prefer to run **aiosyslogd** directly from a Python installation rather than containers, you can use systemd user services:\n\n#### **1. Install aiosyslogd**\n\nFirst, install aiosyslogd using pip:\n\n```bash\n# Install globally for all users\nsudo pip install aiosyslogd\n```\n\n```bash\n# Or install for a specific user\npip install --user aiosyslogd\n```\n\n#### **2. Create Configuration Directory**\n\nCreate a directory for your configuration files:\n\n```bash\nmkdir -p ~/.aiosyslogd\ncd ~/.aiosyslogd\n```\n\nCopy the default configuration to this directory:\n\n```bash\n# If you have the source code, copy the default config from the config directory\n# Or create it manually with your preferred editor\ncp /path/to/aiosyslogd/config/default-aiosyslogd.toml ~/.aiosyslogd/aiosyslogd.toml\n```\n\n#### **3. Enable User Services**\n\nEnable lingering for your user to allow services to start at boot even when not logged in:\n\n```bash\nsudo loginctl enable-linger $USER\n```\n\n#### **4. Create Service Files**\n\nCreate the systemd service files in `~/.config/systemd/user/`:\n\n```bash\nmkdir -p ~/.config/systemd/user/\n```\n\nCreate `~/.config/systemd/user/aiosyslogd.service`:\n\n```toml\n[Unit]\nDescription=aiosyslogd - Asynchronous Syslog Server\nAfter=network.target\nWants=network.target\n\n[Service]\nType=simple\nRestart=always\nRestartSec=5\nExecStart=/usr/local/bin/aiosyslogd\nWorkingDirectory=%h/.aiosyslogd\nEnvironment=AIOSYSLOGD_CONFIG=%h/.aiosyslogd/aiosyslogd.toml\nStandardOutput=journal\nStandardError=journal\n\n[Install]\nWantedBy=default.target\n```\n\nCreate `~/.config/systemd/user/aiosyslogd-web.service`:\n\n```toml\n[Unit]\nDescription=aiosyslogd-web - Web Interface for aiosyslogd\nAfter=network.target\nWants=network.target\nRequires=aiosyslogd.service\n\n[Service]\nType=simple\nRestart=always\nRestartSec=5\nExecStart=/usr/local/bin/aiosyslogd-web\nWorkingDirectory=%h/.aiosyslogd\nEnvironment=AIOSYSLOGD_CONFIG=%h/.aiosyslogd/aiosyslogd.toml\nStandardOutput=journal\nStandardError=journal\n\n[Install]\nWantedBy=default.target\n```\n\n#### **5. Start and Enable Services**\n\nReload the systemd daemon and start the services:\n\n```bash\nsystemctl --user daemon-reload\nsystemctl --user enable aiosyslogd.service\nsystemctl --user enable aiosyslogd-web.service\nsystemctl --user start aiosyslogd.service\nsystemctl --user start aiosyslogd-web.service\n```\n\nCheck the status of the services:\n\n```bash\nsystemctl --user status aiosyslogd.service\nsystemctl --user status aiosyslogd-web.service\n```\n\nView logs for debugging:\n\n```bash\njournalctl --user-unit aiosyslogd.service -f\njournalctl --user-unit aiosyslogd-web.service -f\n```\n\n### **Traditional System Service Setup (Python Installation)**\n\nIf you need to run aiosyslogd as a system-wide service from a Python installation, create the following files in `/etc/systemd/system/`:\n\n**File: /etc/systemd/system/aiosyslogd.service**\n\n```toml\n[Unit]\nDescription=aiosyslogd - Asynchronous Syslog Server\nAfter=network.target\nWants=network.target\n\n[Service]\nType=simple\nRestart=always\nRestartSec=5\nUser=aiosyslogd\nGroup=aiosyslogd\nExecStart=/usr/local/bin/aiosyslogd\nWorkingDirectory=/var/lib/aiosyslogd\nEnvironment=AIOSYSLOGD_CONFIG=/etc/aiosyslogd/aiosyslogd.toml\nStandardOutput=journal\nStandardError=journal\n\n[Install]\nWantedBy=multi-user.target\n```\n\n**File: /etc/systemd/system/aiosyslogd-web.service**\n\n```toml\n[Unit]\nDescription=aiosyslogd-web - Web Interface for aiosyslogd\nAfter=network.target\nWants=network.target\nRequires=aiosyslogd.service\n\n[Service]\nType=simple\nRestart=always\nRestartSec=5\nUser=aiosyslogd\nGroup=aiosyslogd\nExecStart=/usr/local/bin/aiosyslogd-web\nWorkingDirectory=/var/lib/aiosyslogd\nEnvironment=AIOSYSLOGD_CONFIG=/etc/aiosyslogd/aiosyslogd.toml\nStandardOutput=journal\nStandardError=journal\n\n[Install]\nWantedBy=multi-user.target\n```\n\nThen create the user and setup directories:\n\n```bash\n# Create system user\nsudo useradd -r -s /bin/false aiosyslogd\n\n# Create directories\nsudo mkdir -p /var/lib/aiosyslogd\nsudo chown aiosyslogd:aiosyslogd /var/lib/aiosyslogd\n\n# Copy configuration from the config directory\nsudo cp /path/to/aiosyslogd/config/default-aiosyslogd.toml /etc/aiosyslogd/aiosyslogd.toml\nsudo chown aiosyslogd:aiosyslogd /etc/aiosyslogd/aiosyslogd.toml\n```\n\nFinally, enable and start the services:\n\n```bash\nsudo systemctl daemon-reload\nsudo systemctl enable aiosyslogd.service\nsudo systemctl enable aiosyslogd-web.service\nsudo systemctl start aiosyslogd.service\nsudo systemctl start aiosyslogd-web.service\n```\n\n## **Integrating with rsyslog**\n\nYou can use **rsyslog** as a robust, battle-tested frontend for **aiosyslogd**. This is useful for receiving logs on the standard privileged port (514) and then forwarding them to **aiosyslogd** running as a non-privileged user on a different port.\n\nHere are two common configurations:\n\n### **1. Forwarding from an Existing rsyslog Instance**\n\nIf you already have an **rsyslog** server running and simply want to forward all logs to **aiosyslogd**, add the following lines to a new file in /etc/rsyslog.d/, such as 99-forward-to-aiosyslogd.conf. This configuration includes queueing to prevent log loss if **aiosyslogd** is temporarily unavailable.\n\n**File: /etc/rsyslog.d/99-forward-to-aiosyslogd.conf (or use the template from config/rsyslog-forward.conf)**\n\n```\n$ActionQueueFileName fwdRule1 # unique name prefix for spool files\n$ActionQueueMaxDiskSpace 1g   # 1gb space limit (use as much as possible)\n$ActionQueueSaveOnShutdown on # save messages to disk on shutdown\n$ActionQueueType LinkedList   # run asynchronously\n$ActionResumeRetryCount -1    # infinite retries if host is down\n*.* @127.0.0.1:5140\n```\n\nYou can copy this configuration from the project's config directory:\n\n```bash\nsudo cp /path/to/aiosyslogd/config/rsyslog-forward.conf /etc/rsyslog.d/99-forward-to-aiosyslogd.conf\nsudo systemctl restart rsyslog\n```\n\n### **2. Using rsyslog as a Dedicated Forwarder**\n\nIf you want rsyslog to listen on the standard syslog port 514/udp and do nothing but forward to aiosyslogd, you can use a minimal configuration like this. This is a common pattern for privilege separation, allowing aiosyslogd to run as a non-root user.\n\n**File: /etc/rsyslog.conf (Minimal Example from config/rsyslog-minimal.conf)**\n\n```\n$WorkDirectory /var/lib/rsyslog\n\n$FileOwner root\n$FileGroup adm\n$FileCreateMode 0640\n$DirCreateMode 0755\n$Umask 0022\n\nmodule(load=\"immark\")\nmodule(load=\"imuxsock\")\nmodule(load=\"imudp\")\ninput(\n\ttype=\"imudp\"\n\tport=\"514\"\n)\n\n$ActionQueueFileName fwdRule1\n$ActionQueueMaxDiskSpace 1g\n$ActionQueueSaveOnShutdown on\n$ActionQueueType LinkedList\n$ActionResumeRetryCount -1\n*.* @127.0.0.1:5140\n```\n\nYou can copy this configuration from the project's config directory:\n\n```bash\nsudo cp /path/to/aiosyslogd/config/rsyslog-minimal.conf /etc/rsyslog.conf\nsudo systemctl restart rsyslog\n```\n\n## **Nginx Reverse Proxy Setup**\n\nFor production deployments, it's recommended to put aiosyslogd-web behind a reverse proxy like nginx. This provides benefits like SSL termination, static file serving, and improved security.\n\n### **Basic Nginx Configuration**\n\nCreate a configuration file in `/etc/nginx/sites-available/aiosyslogd`:\n\n```nginx\nserver {\n    listen 80;\n    server_name your-domain.com;  # Change this to your domain\n\n    # SSL configuration (recommended for production)\n    # listen 443 ssl;\n    # ssl_certificate /path/to/your/certificate.crt;\n    # ssl_certificate_key /path/to/your/private.key;\n\n    location / {\n        proxy_pass http://127.0.0.1:5141;  # aiosyslogd-web default port\n        proxy_set_header Host $host;\n        proxy_set_header X-Real-IP $remote_addr;\n        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n        proxy_set_header X-Forwarded-Proto $scheme;\n\n        # WebSocket support if needed\n        proxy_http_version 1.1;\n        proxy_set_header Upgrade $http_upgrade;\n        proxy_set_header Connection \"upgrade\";\n\n        # Timeouts\n        proxy_connect_timeout 60s;\n        proxy_send_timeout 60s;\n        proxy_read_timeout 60s;\n    }\n\n    # Optional: Basic security headers\n    add_header X-Frame-Options \"SAMEORIGIN\" always;\n    add_header X-XSS-Protection \"1; mode=block\" always;\n    add_header X-Content-Type-Options \"nosniff\" always;\n}\n```\n\nEnable the site:\n\n```bash\nsudo ln -s /etc/nginx/sites-available/aiosyslogd /etc/nginx/sites-enabled/\nsudo nginx -t  # Test configuration\nsudo systemctl reload nginx\n```\n\n### **SSL/HTTPS Configuration**\n\nFor secure access, configure SSL certificates. If you're using Let's Encrypt:\n\n```bash\nsudo apt install certbot python3-certbot-nginx\nsudo certbot --nginx -d your-domain.com\n```\n\nThis will automatically update your nginx configuration with SSL settings.\n\n## **Using as a Library**\n\nYou can also import and use the SyslogUDPServer in your own asyncio application.\n\n```python\nimport asyncio\nfrom aiosyslogd.server import SyslogUDPServer\n\nasync def main():\n    # The server is configured via aiosyslogd.toml by default.\n    # To configure programmatically, you would need to modify the\n    # server class or bypass the config-loading mechanism.\n    server = await SyslogUDPServer.create(host=\"0.0.0.0\", port=5141)\n\n    loop = asyncio.get_running_loop()\n\n    # Define the protocol factory as a simple function\n    def server_protocol_factory():\n        return server\n\n    # Start the UDP server endpoint\n    transport, protocol = await loop.create_datagram_endpoint(\n        server_protocol_factory,\n        local_addr=(server.host, server.port)\n    )\n\n    print(\"Custom server running. Press Ctrl+C to stop.\")\n    try:\n        await asyncio.Event().wait()\n    except (KeyboardInterrupt, asyncio.CancelledError):\n        pass\n    finally:\n        print(\"Shutting down custom server.\")\n        transport.close()\n        await server.shutdown()\n\nif __name__ == \"__main__\":\n    asyncio.run(main)\n```\n\n## **Contributing**\n\nContributions are welcome! If you find a bug or have a feature request, please open an issue on the project's repository.\n\n## **License**\n\nThis project is licensed under the [**MIT License**](https://github.com/cwt/aiosyslogd/blob/main/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcwt%2Faiosyslogd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcwt%2Faiosyslogd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcwt%2Faiosyslogd/lists"}