Infrastructure guide
Logs Hook Guide
Centralized, rotation-aware logging that every Kodachi service writes 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 | 9.8.4 |
| Build Date | Not disclosed |
| Rust Version | 1.88.0 |
| File Size | 1.6MB |
| 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
Key Features
Centralized Logging
| Feature | Description |
|---|---|
| Unified System | All Kodachi services log to one location |
| Consistent Format | Standardized timestamps and severity levels |
| Automatic Rotation | Prevents logs from filling disk space |
| Secure Wiping | Removes sensitive data from old logs |
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 log files
sudo logs-hook maintenance rotate
# Wipe old logs securely
sudo logs-hook maintenance wipe
# View recent logs
tail -50 dashboard/hooks/logs/*-log.log
Understanding Centralized Logging
How Logs Hook Works
All Kodachi services send their logs through Logs Hook for centralized management:
# 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'
Log Levels:
| Level | Description |
|---|---|
| ERROR | Critical issues requiring attention |
| WARN | Warnings about potential problems |
| INFO | General informational messages |
| DEBUG | Detailed debugging information |
| FATAL | Fatal errors requiring immediate attention |
Log Location and Structure
Logs are stored in dashboard/hooks/logs/:
# 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:
2025-01-15 14:23:17 [INFO] ip-fetch: Successfully fetched IP from Kodachi Cloud
2025-01-15 14:23:18 [ERROR] dns-switch: Failed to connect to DNS server 8.8.8.8
2025-01-15 14:23:19 [WARN] health-control: Network connectivity degraded
2025-01-15 14:23:20 [DEBUG] routing-switch: Connecting to WireGuard server
Log Rotation
Prevent logs from consuming disk space:
# Rotate logs (archives current, starts fresh)
sudo logs-hook maintenance rotate
# Rotate with JSON output for automation
sudo logs-hook maintenance rotate --json
# What happens:
# 1. Current logs → compressed archives (.gz files)
# 2. New empty log files created
# 3. Old archives deleted after retention period (default: 7 days)
Secure Log Wiping
Remove sensitive information from logs:
# Wipe all old rotated logs
sudo logs-hook maintenance wipe --all
# Note: This removes old rotated log archives
# Current active logs are preserved
# Data is securely overwritten before deletion
Logging from Applications
Services use Logs Hook for consistent logging:
# Application logging (script name required)
sudo logs-hook log --script 'my-service' --level info 'Service started'
# Short form with -s and -l
sudo logs-hook log -s 'routing-switch' -l info 'Connection established'
# With JSON output
sudo 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
# Note: Direct log viewing is preferred over logs-hook view commands
Log Management Best Practices
# Regular maintenance workflow
sudo logs-hook maintenance rotate # Rotate logs first
sudo logs-hook maintenance wipe --all # Clean old archives
# 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
sudo logs-hook --json log -s 'test' -l info 'Test message'
# Pretty-printed JSON for readability
sudo 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 --json | jq '.rotated_files[]'
sudo logs-hook -n --json | jq '.data.name'
# Filter log operations
tail -f dashboard/hooks/logs/ip-fetch-log.log | jq 'select(.level == "ERROR")' # Error logs 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 Schedules | Custom rotation schedules |
| Compression | Log compression options |
| 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 | 7 days for archived logs, unlimited for active logs |
Retention Configuration
| Log Type | Retention | Size Limit | Action |
|---|---|---|---|
| Active Logs | Unlimited | 100MB/file | Auto-rotate when full |
| Archived Logs | 7 days | 10GB total | Auto-delete oldest |
| Error Logs | 30 days | 50MB total | Priority retention |
| Debug Logs | 3 days | 1GB total | Quick deletion |
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
Configure all Kodachi services to send logs through logs-hook for unified monitoring and management.
# Step 1: Verify logs-hook is operational
sudo logs-hook -v
# Expected: Version 9.8.4
# Step 2: Test logging from health-control
sudo logs-hook log --script 'health-control' --level info 'Health check initiated'
# Expected: Message logged successfully
# Step 3: Test logging from tor-switch
sudo 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 with workflow-manager to verify logging health daily.
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
sudo 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 with workflow-manager to check for critical errors hourly and alert administrators.
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 all log files
sudo logs-hook maintenance rotate
# Expected: Log rotation completed for all files
# Step 4: Verify rotated archives exist
ls -lh dashboard/hooks/logs/*.log.gz
# Expected: Compressed archived logs with timestamps
# Step 5: Check disk space saved by rotation
du -sh dashboard/hooks/logs/
# Expected: Reduced total size after compression
# Step 6: Wipe old rotated logs (older than 7 days)
sudo logs-hook maintenance wipe --all
# Expected: All old archived logs wiped successfully
# Step 7: Verify disk space recovered
df -h dashboard/hooks/logs/
# Expected: Available space increased
# Step 8: Run health-control to verify system integrity 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 logs weekly and wipe old archives monthly:
# Create weekly log rotation workflow
workflow-manager create weekly-log-rotation "Weekly log rotation task"
workflow-manager add weekly-log-rotation "Rotate all service logs" \
"sudo logs-hook maintenance rotate"
# Create monthly log wipe workflow
workflow-manager create monthly-log-wipe "Monthly log cleanup task"
workflow-manager add monthly-log-wipe "Wipe old archived logs" \
"sudo logs-hook maintenance wipe --all"
# 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: Rotate current logs before wiping
sudo logs-hook maintenance rotate
# Expected: Log rotation completed
# Step 3: Wipe all archived logs
sudo logs-hook maintenance wipe --all
# Expected: All archived logs wiped successfully
# Step 4: Verify no old log archives remain
ls -la dashboard/hooks/logs/*.log.gz 2>/dev/null || echo "No archived logs found"
# Expected: "No archived logs found"
# 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
sudo 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:
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. Automate this with workflow-manager using the monitoring profile with security type:
# Run security monitoring workflow
workflow-manager run monitoring --params '{"monitor_type": "security"}'
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, Automated task scheduling and execution
- Full CLI Reference: logs-hook commands