Logs Hook
INFRASTRUCTURE TOOL
Operate Kodachi support services with confidence.
These guides cover workflows, logs, launchers, dependency checks, and status plumbing used by the rest of Kodachi.
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.0.1 |
| Build Date | REDACTED-BUILD-TIME |
| 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.0.1
# 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