Infrastructure guide
Logs Hook Guide
Centralized, rotation-aware logging that Kodachi's services write through. This guide covers log locations, rotation, secure wiping, and cross-service error triage.
Logging
Audit trail
Rotation
Secure wipe
Documentation Navigation
This page is scenario-first (operational workflows, real run order, and troubleshooting). For the full autogenerated command/flag catalog, use the CLI Reference.
File Information
| Property | Value |
|---|---|
| Binary Name | logs-hook |
| Version | 10.0.3 |
| Build Date | Not disclosed |
| Rust Version | 1.88.0 |
| File Size | 1.7MB |
| Author | Warith Al Maawali |
| License | Proprietary |
| Category | Infrastructure & Management |
| Description | A robust, secure, and configurable logging system for Kodachi OS |
| JSON Data | View Raw JSON |
SHA256 Checksum
9abf525cfe31433449b5a73f7e4e09c049520d7781b5e8a3d3d59ccb19b396dc
Key Features
Centralized Logging
| Feature | Description |
|---|---|
| Unified System | Kodachi's services log to one directory, one file per service |
| Consistent Format | Standardized timestamps and severity levels |
| Automatic Rotation | A log rotates after 2,000 lines and only a bounded number of numbered copies is kept |
| Secure Wiping | Overwrites log files (three random passes and a zero pass) before deleting them |
Why Logs Hook is Essential
| Benefit | Description |
|---|---|
| System Health | Track service operations and errors |
| Security Auditing | Maintain audit trail of system events |
| Disk Management | Automatic rotation prevents space issues |
| Privacy Protection | Secure deletion of sensitive log data |
TL;DR - Essential Commands
# Log a message
logs-hook log --script 'service' --level info 'System check completed'
# Rotate one log file (--file is required, there is no rotate-all)
sudo logs-hook maintenance rotate --file /opt/kodachi/dashboard/hooks/logs/health-control-log.log
# Wipe logs by the built-in policy (untouched for 30+ days or over 10 MB)
sudo logs-hook maintenance wipe --confirm
# View recent logs
tail -50 dashboard/hooks/logs/*-log.log
Understanding Centralized Logging
How Logs Hook Works
Kodachi's Rust services write their logs through the Logs Hook library, and scripts can use the same CLI:
# Basic logging
logs-hook log --script 'service' --level info 'Starting VPN connection'
logs-hook log --script 'service' --level error 'Authentication failed'
logs-hook log --script 'service' --level debug 'Debug: Connection details' # dropped unless debug logging is on (off by default)
Log Levels:
| Level | Description |
|---|---|
| ERROR | Critical issues requiring attention |
| WARN | Warnings about potential problems |
| INFO | General informational messages |
| DEBUG | Detailed debugging information (not written unless debug logging is enabled, which is off by default) |
| FATAL | Fatal errors requiring immediate attention |
Log Location and Structure
Logs are stored in dashboard/hooks/logs/ (on an installed system /opt/kodachi/dashboard/hooks/logs/; the relative paths below assume you are in /opt/kodachi), one <service>-log.log file per service plus its numbered rotations:
# View log directory structure
ls -la dashboard/hooks/logs/
# Exact log file paths and samples:
dashboard/hooks/logs/ip-fetch-log.log # IP fetch operations
dashboard/hooks/logs/dns-switch-log.log # DNS switching events
dashboard/hooks/logs/health-control-log.log # System health checks
dashboard/hooks/logs/routing-switch-log.log # VPN/proxy connections
dashboard/hooks/logs/tor-switch-log.log # Tor operations
dashboard/hooks/logs/online-auth-log.log # Authentication events
dashboard/hooks/logs/permission-guard-log.log # Permission corrections
dashboard/hooks/logs/integrity-check-log.log # Integrity verification
Sample Log Entries:
2026-10-16 14:23:17 UTC [INFO] | ip-fetch: Successfully fetched IP from Kodachi Cloud
2026-10-16 14:23:18 UTC [ERROR] | dns-switch: Failed to connect to DNS server 8.8.8.8
2026-10-16 14:23:19 UTC [WARN] | health-control: Network connectivity degraded
2026-10-16 14:23:20 UTC [INFO] | routing-switch: Connecting to WireGuard server
Log Rotation
Every write rotates its log automatically once it passes 2,000 lines. logs-hook itself needs no root: writing an entry works as any user. Wipe only touches log files owned by the user running it, or, under sudo, files owned by root or by the user who ran sudo; rotate needs write access to the file. Services that run as root write root-owned logs, which is why the maintenance examples below use sudo. To rotate one log now:
# Rotate one log now (--file is required)
sudo logs-hook maintenance rotate --file /opt/kodachi/dashboard/hooks/logs/health-control-log.log
# Same, with JSON output for automation
sudo logs-hook maintenance rotate --file /opt/kodachi/dashboard/hooks/logs/health-control-log.log --json
# What happens:
# 1. The log is copied to <service>-log.log.1 (older .1, .2, ... move up by one; no compression)
# 2. The active log is emptied and keeps receiving new lines
# 3. Up to 33 numbered copies are kept; the oldest is overwritten (no age-based deletion)
Secure Log Wiping
Remove sensitive information from logs. Every wipe is irreversible:
# Wipe EVERY log file: active logs and their numbered rotations
sudo logs-hook maintenance wipe --all
# Each file gets three random passes and a zero pass, then is truncated and deleted
# Files over 64 MB are refused. --file <path> wipes one log;
# --confirm wipes only active logs untouched for 30+ days or over 10 MB
Logging from Applications
Services use Logs Hook for consistent logging:
# Application logging (script name required)
logs-hook log --script 'my-service' --level info 'Service started'
# Short form with -s and -l
logs-hook log -s 'routing-switch' -l info 'Connection established'
# With JSON output
logs-hook --json log -s 'app' -l error 'Connection failed'
Working with Logs
# Logs are stored in dashboard/hooks/logs/
ls -la dashboard/hooks/logs/
# View logs directly (each service has its own file)
tail -f dashboard/hooks/logs/ip-fetch-log.log
tail -f dashboard/hooks/logs/dns-switch-log.log
# logs-hook has no view command: read the files directly
Log Management Best Practices
# Regular maintenance workflow
sudo logs-hook maintenance rotate --file /opt/kodachi/dashboard/hooks/logs/health-control-log.log # Rotate one log
sudo logs-hook maintenance wipe --confirm # Policy wipe: 30+ days old or over 10 MB
# Check logs-hook is working
sudo logs-hook -v --json # Version info
sudo logs-hook -n --json # Detailed info
JSON Output Options
# All logs-hook commands support JSON output
logs-hook --json log -s 'test' -l info 'Test message'
# Pretty-printed JSON for readability
logs-hook --json-pretty log -s 'app' -l warn 'Warning'
# Parse JSON output with jq filters
sudo logs-hook -v --json | jq '.version'
sudo logs-hook maintenance rotate --file /opt/kodachi/dashboard/hooks/logs/health-control-log.log --json | jq '.data.file'
sudo logs-hook -n --json | jq '.data.name'
# Filter log files (they are plain text, not JSON)
tail -f dashboard/hooks/logs/ip-fetch-log.log | grep --line-buffered '\[ERROR\]' # Error lines only
grep "ERROR" dashboard/hooks/logs/*.log | jq -R 'split(":") | {file: .[0], message: .[1:]}'
Advanced Commands
For advanced users who need access to all available commands and options, please refer to the auto-generated command reference which includes:
| Feature | Description |
|---|---|
| Rotation | maintenance rotate --file for one log; automatic rotation past 2,000 lines |
| Wiping | maintenance wipe with --all, --file or --confirm |
| Remote Logging (Planned) | Remote logging configuration |
| Filtering (Planned) | Advanced filtering and queries |
| Metrics (Planned) | Performance metrics logging |
| JSON Formatting | JSON output formatting |
| CLI Reference | All command-line flags and parameters |
Security Notes
Important Security Practices:
| Practice | Description |
|---|---|
| Data Wiping | Regularly wipe old logs containing sensitive data |
| Size Monitoring | Monitor log sizes to prevent disk exhaustion |
| Error Review | Review error logs for security issues |
| Log Levels | Use appropriate log levels (avoid DEBUG in production) |
| Permissions | Ensure log directory permissions are restrictive |
Performance
| Metric | Value |
|---|---|
| Write Speed | ~10,000 messages/second |
| Memory Usage | ~10MB active, < 2MB idle |
| CPU Usage | < 1% during normal logging |
| Rotation Time | < 2 seconds for 1GB logs |
| Default Retention | No age-based deletion: a log rotates past 2,000 lines and up to 33 numbered copies are kept |
Retention Configuration
| Log Type | Retention | Size Limit | Action |
|---|---|---|---|
| Active Logs | Until rotated | 2,000 lines per file | Rotated on the next write past the limit; maintenance wipe --confirm wipes ones untouched for 30+ days or over 10 MB |
| Archived Logs | Until overwritten (no age limit) | 33 numbered files per service (.log.1 newest) |
Oldest overwritten on the next rotation; not compressed |
| Error Logs | Same as the service log | No separate limit | ERROR and FATAL lines share the service's file; no separate retention |
| Debug Logs | Not written by default | No separate limit | DEBUG lines are dropped unless debug logging is enabled |
Support
| Resource | Link |
|---|---|
| Website | digi77.com |
| Anonymity Verifier | kodachi.cloud |
| Discord Support | discord.gg/KEFErEx |
| GitHub | github.com/WMAL |
Scenario 1: Setting Up Centralized Logging for All Services
Check that Kodachi's services are writing through logs-hook for unified monitoring and management.
# Step 1: Verify logs-hook is operational
sudo logs-hook -v
# Expected: logs-hook version 10.0.3 (the current release)
# Step 2: Test logging from health-control
logs-hook log --script 'health-control' --level info 'Health check initiated'
# Expected: Message logged successfully
# Step 3: Test logging from tor-switch
logs-hook log --script 'tor-switch' --level info 'Tor instance created'
# Expected: Message logged successfully
# Step 4: Verify log files are created
ls -la dashboard/hooks/logs/
# Expected: health-control-log.log, tor-switch-log.log visible
# Step 5: View recent entries to confirm centralized logging
tail -n 20 dashboard/hooks/logs/health-control-log.log
# Expected: Recent log entries with timestamps and levels
# Step 6: Check all service logs are being written
tail -f dashboard/hooks/logs/*.log
# Expected: Live log stream from all services
Cross-binary workflow: logs-hook + health-control + tor-switch + dns-switch + routing-switch
When to run: During initial system setup or after service updates. Automate this by putting these checks in a workflow-manager template and running it daily from cron or a systemd timer (workflow-manager does not schedule).
Scenario 2: Error Logging and Alerting Across Services
Monitor critical errors from security services and investigate issues.
# Step 1: Search for errors across all service logs
grep "ERROR" dashboard/hooks/logs/*.log | tail -50
# Expected: Recent error entries from all services
# Step 2: Log a critical error from health-control
logs-hook log --script 'health-control' --level error 'Network kill switch activation failed'
# Expected: Message logged successfully
# Step 3: Verify error was recorded
grep "Network kill switch" dashboard/hooks/logs/health-control-log.log
# Expected: Error entry with timestamp
# Step 4: Check integrity-check errors
tail -50 dashboard/hooks/logs/integrity-check-log.log | grep "ERROR"
# Expected: Integrity verification errors if any
# Step 5: Run health-control security verification
sudo health-control security-verify
# Expected: Security verification status
# Step 6: Review all ERROR-level logs in JSON format
grep "ERROR" dashboard/hooks/logs/*.log | jq -R 'split(":") | {file: .[0], message: .[1:]}'
# Expected: Structured JSON output of all errors
# Step 7: Generate error report for investigation
grep "ERROR" dashboard/hooks/logs/*.log > /tmp/error-report-$(date +%Y%m%d).txt
# Expected: Error report saved to /tmp
# Step 8: Monitor live errors
tail -f dashboard/hooks/logs/*.log | grep --line-buffered "ERROR"
# Expected: Real-time error stream
Cross-binary workflow: logs-hook + health-control + integrity-check + all Rust services
When to run: After system errors or failed operations. Automate this by putting these checks in a workflow-manager template and running it hourly from cron or a systemd timer (workflow-manager neither schedules nor sends alerts).
Scenario 3: Log Rotation and Disk Space Management
Prevent logs from filling disk space with automatic rotation and cleanup.
# Step 1: Check current log directory size
du -sh dashboard/hooks/logs/
# Expected: Total size of all log files
# Step 2: List all log files with sizes
ls -lh dashboard/hooks/logs/*.log
# Expected: File sizes for each service log
# Step 3: Rotate a log (one --file per call, there is no rotate-all)
sudo logs-hook maintenance rotate --file /opt/kodachi/dashboard/hooks/logs/health-control-log.log
# Expected: Log rotation completed for: ".../health-control-log.log"
# Step 4: Verify the numbered rotations exist
ls -lh dashboard/hooks/logs/*-log.log.[0-9]*
# Expected: health-control-log.log.1 and older numbered copies (not compressed)
# Step 5: Check the directory size again
du -sh dashboard/hooks/logs/
# Expected: About the same total: rotation moves lines, it does not compress them
# Step 6: Wipe logs by the built-in policy (active logs untouched for 30+ days or over 10 MB)
sudo logs-hook maintenance wipe --confirm
# Expected: Logs wiped based on configuration
# Step 7: Verify disk space recovered
df -h dashboard/hooks/logs/
# Expected: More free space if anything was wiped
# Step 8: Confirm the network still works after cleanup
sudo health-control net-check
# Expected: Network check passed
Cross-binary workflow: logs-hook + health-control + workflow-manager
Automate this with workflow-manager to rotate a log weekly and run the policy wipe monthly (creating and editing templates needs an online-auth login):
# Create a weekly log rotation workflow
workflow-manager create weekly-log-rotation --description "Weekly log rotation task"
workflow-manager add weekly-log-rotation --description "Rotate the health-control log" \
"sudo logs-hook maintenance rotate --file /opt/kodachi/dashboard/hooks/logs/health-control-log.log"
# Create monthly log wipe workflow
workflow-manager create monthly-log-wipe --description "Monthly log cleanup task"
workflow-manager add monthly-log-wipe --description "Wipe logs past the 30 day or 10 MB policy" \
"sudo logs-hook maintenance wipe --confirm"
# Execute workflows manually or integrate with system cron/systemd timers
# For scheduling, use system cron or systemd timers to call:
# workflow-manager run weekly-log-rotation
# workflow-manager run monthly-log-wipe
Scenario 4: Secure Log Wiping Before Shutdown
Remove all sensitive log data before system shutdown or when leaving a session.
# Step 1: Run health-control wipe-logs to remove system logs
sudo health-control wipe-logs
# Expected: System logs wiped successfully
# Step 2: See what is about to be wiped
ls -lh dashboard/hooks/logs/
# Expected: The active *-log.log files and their numbered rotations
# Step 3: Wipe every Kodachi log, active and rotated (irreversible)
sudo logs-hook maintenance wipe --all
# Expected: All logs wiped successfully
# Step 4: Verify the log files are gone
ls -la dashboard/hooks/logs/*-log.log* 2>/dev/null || echo "No log files found"
# Expected: "No log files found", or only lines services wrote since step 3
# Step 5: Wipe browser data for complete privacy
sudo health-control wipe-browser-data
# Expected: Browser data wiped successfully
# Step 6: Verify active logs are empty or minimal
for log in dashboard/hooks/logs/*.log; do echo "$log: $(wc -l < $log) lines"; done
# Expected: Low line counts indicating fresh logs
# Step 7: Run security verification
sudo health-control security-verify
# Expected: Security checks passed
# Step 8: Generate final wipe confirmation
logs-hook log --script 'shutdown-procedure' --level info "Log wipe completed at $(date)"
# Expected: Message logged successfully
Cross-binary workflow: logs-hook + health-control
When to run: Before system shutdown, during panic mode, or when handing over control. Use the protection-wipe-logs workflow profile for automated execution:
# Runs health-control wipe-logs and wipe-browser-data after a confirmation pause (not the logs-hook steps)
workflow-manager run protection-wipe-logs
Scenario 5: Log Analysis and Forensic Investigation
Investigate security incidents by analyzing log patterns and service behavior.
# Step 1: Check health-control logs for security events
grep "security" dashboard/hooks/logs/health-control-log.log | tail -100
# Expected: Recent security-related log entries
# Step 2: Analyze integrity-check logs for verification failures
tail -100 dashboard/hooks/logs/integrity-check-log.log | grep -i "failed\|error"
# Expected: Failed integrity checks if any
# Step 3: Search for authentication failures
grep -i "auth\|login" dashboard/hooks/logs/online-auth-log.log | tail -50
# Expected: Authentication attempts and results
# Step 4: Track Tor circuit changes
grep "circuit" dashboard/hooks/logs/tor-switch-log.log | tail -30
# Expected: Tor circuit change events
# Step 5: Investigate DNS leak detection results
tail -50 dashboard/hooks/logs/dns-leak-log.log
# Expected: DNS leak test results
# Step 6: Generate timeline of all critical events
for log in dashboard/hooks/logs/*.log; do grep -H "ERROR\|WARN" "$log"; done | sort -k1
# Expected: Chronological timeline of warnings and errors
# Step 7: Run comprehensive security score
sudo health-control security-score
# Expected: Overall security score with breakdown
# Step 8: Verify system integrity after investigation
sudo integrity-check check-all
# Expected: Comprehensive integrity verification results
Cross-binary workflow: logs-hook + health-control + integrity-check + tor-switch + dns-leak + online-auth
When to run: After suspicious activity, failed security checks, or during security audits. Pair it with the shipped monitoring workflow profile for a read-only network snapshot:
# Read-only snapshot: IP, DNS, routing, Tor status, connections and routes
workflow-manager run monitoring
Related Workflows
- health-control, System health monitoring and emergency controls
- integrity-check, File and system integrity verification
- tor-switch, Tor network management and monitoring
- workflow-manager, Batch command workflows with conditional steps
- Full CLI Reference: logs-hook commands