git - Merge pull request #8 from DinoTools/docs

Docs and dependencies

README.md

@@ -31,11 +31,10 @@ MikroTik RouterOS log exporter
   </a>
 </p>
 
-<Warning>
-# Proof of Concept
-
-This project is in an very early stage of development. Don't use it in production.
-</Warning>
+> [!WARNING]
+> **Proof of Concept**
+>
+> This project is in an very early stage of development. Don't use it in production.
 
 The Exporter connects to [MikroTik](https://mikrotik.com/) RouterOS devices via API and connects to the log stream to export the logs in realtime.
 
@@ -46,6 +45,7 @@ Requirements
 - Python Packages
     - [Click](https://pypi.org/project/click/)
     - [librouteros](https://pypi.org/project/librouteros/)
+    - [pyyaml](https://pypi.org/project/PyYAML/)
 
 Installation
 ------------

docs/config/fetcher.md

@@ -0,0 +1,5 @@
+# Fetcher
+
+::: routeros_log_exporter.fetcher
+    options:
+      show_root_toc_entry: false

docs/config/fetcher.md.license

@@ -0,0 +1,2 @@
+# SPDX-FileCopyrightText: none
+# SPDX-License-Identifier: CC0-1.0

docs/config/output/format.md

@@ -0,0 +1,7 @@
+# Output Format
+
+## JSON
+
+::: routeros_log_exporter.output.format.format_json
+    options:
+      show_root_toc_entry: false

docs/config/output/format.md.license

@@ -0,0 +1,2 @@
+# SPDX-FileCopyrightText: none
+# SPDX-License-Identifier: CC0-1.0

docs/config/output/index.md

@@ -0,0 +1,7 @@
+# Output
+
+## File
+
+::: routeros_log_exporter.output.file
+    options:
+      show_root_toc_entry: false

docs/config/output/index.md.license

@@ -0,0 +1,2 @@
+# SPDX-FileCopyrightText: none
+# SPDX-License-Identifier: CC0-1.0

docs/requirements.txt

@@ -4,3 +4,4 @@
 mkdocs
 mkdocs-click
 mkdocs-material
+mkdocstrings[python] >= 0.18

mkdocs.yml

@@ -6,12 +6,16 @@ site_description: Export logs from MikroTik RouterOS devices
 site_url: https://dinotools.github.io/routeros-log-exporter/
 
 repo_name: DinoTools/routeros-log-exporter
-repo_url: https://github.com/DinoTools/routeros-log-exporter
+repo_url: https://github.com/DinoTools/routeros-log-exporter/
 edit_uri: blob/main/docs/
 
 nav:
     - Home: index.md
     - cli.md
+    - Config:
+        - Fetcher: config/fetcher.md
+        - Output: config/output/index.md
+        - Output Format: config/output/format.md
     - License: LICENSE.md
     - Issue Tracker: https://github.com/DinoTools/routeros-log-exporter/issues
     - Git Repo: https://github.com/DinoTools/routeros-log-exporter
@@ -27,4 +31,13 @@ theme:
 
 markdown_extensions:
     - attr_list
+    - def_list
     - mkdocs-click
+    - pymdownx.highlight
+    - pymdownx.superfences
+
+plugins:
+  - mkdocstrings:
+      handlers:
+        python:
+          paths: [.]

pyproject.toml

@@ -21,9 +21,9 @@ classifiers = [
 ]
 keywords = ["RouterOS", "MikroTik", "logging", "exporter"]
 dependencies = [
-    "Click",
-    "librouteros",
-    "pyyaml"
+    "Click >= 8.0.0",
+    "librouteros >= 3.0.0",
+    "pyyaml >= 6.0"
 ]
 requires-python = ">=3.8"
 

requirements.txt

@@ -1,6 +1,6 @@
 # SPDX-FileCopyrightText: none
 # SPDX-License-Identifier: CC0-1.0
 
-click
-librouteros
-pyyaml
+Click >= 8.0.0
+librouteros >= 3.0.0
+pyyaml >= 6.0

routeros_log_exporter/cli.py

@@ -22,8 +22,19 @@ def handle_signal(signal_number, frame):
 
 
 @click.command()
-@click.option("config_filename", "--config", required=True, type=click.Path())
-@click.option("-v", "verbosity", count=True)
+@click.option(
+    "config_filename",
+    "--config",
+    required=True,
+    type=click.Path(),
+    help="The config filename."
+)
+@click.option(
+    "verbosity",
+    "-v",
+    count=True,
+    help="Specify the verbosity. Use multiple times to increase the log level."
+)
 def cli(config_filename, verbosity):
     global g_exporter
     log_handler = None

routeros_log_exporter/fetcher.py

@@ -1,5 +1,65 @@
 # SPDX-FileCopyrightText: PhiBo DinoTools (2024)
 # SPDX-License-Identifier: GPL-3.0-or-later
+"""
+The fetcher connects to a RouterOS device and uses the ```/log/print``` command to
+collect the log messages from the stream. The messages are not processes by the
+fetcher. One should use one or more output plugins to dump the logs.
+
+```yaml
+devices:
+  - hostname: 192.168.0.1
+    username: logger
+    password: secure_password
+    outputs:
+      # The output has to be defined
+      - log_file
+
+  - hostname: 1.2.3.4
+    username: admin
+    password: secure_password
+    ssl: yes
+    outputs:
+      # The output has to be defined
+      - log_file
+```
+
+# Config
+
+hostname (Default: localhost)
+: The hostname or the IP address of the device to connect to
+
+username (Default: admin)
+: The username of a user that can access the log stream. We recommend not use the admin
+  user and create a dedicated user to fetch the logs. We also recommend to limit the
+  access to specified source IPs.
+
+password
+: A secure password
+
+port (Default: not set)
+: If not set the port is 8728 if ```ssl: false``` and 8729 if ```ssl: true```
+
+ssl (Default: true)
+: Use SSL/TLS to connect to the device. It is highly recommended to not disable this feature.
+
+ssl_force_no_certificate (Default: false)
+: Use SSL/TLS encryption but without certificate.
+
+ssl_verify (Default: true)
+: Verify the provided certificate
+: Warning: This will not work if ```ssl_force_no_certificate: true```
+
+ssl_verify_hostname (Default: true)
+: Verify the hostname provided.
+: Warning: This will not work if ```ssl_force_no_certificate: true```
+
+ssl_cafile (Default: not set use CA from system)
+: Set a ca file to use
+
+ssl_capath  (Default: not set use CA from system)
+: Set a path to ca files to use
+
+"""
 
 import logging
 from datetime import datetime, timezone

routeros_log_exporter/output/file.py

@@ -1,5 +1,43 @@
 # SPDX-FileCopyrightText: PhiBo DinoTools (2024)
 # SPDX-License-Identifier: GPL-3.0-or-later
+"""
+This plugin can writes the log messages to a file.
+
+```yaml
+outputs:
+  log_file:
+    type: file
+    # Format of the log messages
+    format: json
+    # The config of this output plugin
+    file_config:
+      # The logging directory
+      dir: "./logs"
+      # The logging filename
+      filename: "{{hostname}}-{{timestamp:%Y-%m-%d}}.json"
+```
+
+## Filename patterns
+
+hostname
+
+: The hostname value from the config file
+
+timestamp
+
+: The timestamp when the log message has been received.
+  It has an additional parameter to specify the format.
+  It uses the strftime syntax.
+
+## Signals
+
+SIGHUP
+
+: This plugin handles the SIGHUP signal. If the signal is received it closes all file
+  handles and reopens them if needed. This is useful if you want to use it with a
+  tool like logrotate.
+"""
+
 
 from datetime import datetime
 import logging

routeros_log_exporter/output/format/format_json.py

@@ -1,5 +1,16 @@
 # SPDX-FileCopyrightText: PhiBo DinoTools (2024)
 # SPDX-License-Identifier: GPL-3.0-or-later
+"""
+This format plugin renders the log message as json string. Every message is one line.
+
+```yaml
+outputs:
+  log_file:
+    type: file
+    # Format of the log messages
+    format: json
+```
+"""
 
 import json
 from typing import Any, Dict