KrakenHashes System Configuration Guide¶

This guide provides comprehensive documentation for all configuration options available in the KrakenHashes system, including environment variables, configuration files, and settings for all components.

Table of Contents¶

• Overview
• Environment Variables
• Core System Settings
• Database Configuration
• Backend Configuration
• Frontend Configuration
• Agent Configuration
• TLS/SSL Configuration
• Debug and Logging
• Docker-Specific Settings
• Configuration Files
• Common Configuration Scenarios

Overview¶

KrakenHashes uses environment variables for all runtime configuration. Configuration can be provided through:

1. Environment Variables: Direct system environment variables
2. .env Files: Local environment files (development)
3. Docker Compose: Environment variables in docker-compose.yml
4. Kubernetes ConfigMaps: For production deployments

Configuration Hierarchy¶

The system follows this precedence order (highest to lowest): 1. Runtime environment variables 2. Docker Compose environment settings 3. .env file values 4. Default values in code

Environment Variables¶

Core System Settings¶

Database Configuration¶

Backend Configuration¶

Server Settings¶

File Handling¶

JWT Authentication¶

WebSocket Configuration¶

Frontend Configuration¶

Agent Configuration¶

TLS/SSL Configuration¶

General TLS Settings¶

Certificate Details¶

Provided Certificate Mode¶

Certbot Mode (Let's Encrypt)¶

Debug and Logging¶

General Debug Settings¶

Component-Specific Debug Flags¶

Frontend Debug Settings¶

Log Directories¶

Docker-Specific Settings¶

Volume Mounts¶

Nginx Configuration¶

CORS Configuration¶

Configuration Files¶

Directory Structure¶

The system creates and uses the following directory structure:

${KH_CONFIG_DIR}/
├── certs/              # TLS certificates
│   ├── ca.crt         # CA certificate
│   ├── ca.key         # CA private key
│   ├── server.crt     # Server certificate
│   └── server.key     # Server private key
└── config/            # Application configuration

${KH_DATA_DIR}/
├── binaries/          # Hashcat and other tools
├── wordlists/         # Wordlist files
│   ├── general/       # General purpose wordlists
│   ├── specialized/   # Domain-specific wordlists
│   ├── targeted/      # Target-specific wordlists
│   └── custom/        # User-uploaded wordlists
├── rules/             # Rule files
│   ├── hashcat/       # Hashcat rule files
│   ├── john/          # John the Ripper rules
│   └── custom/        # Custom rule files
├── hashlists/         # Hash files
└── hashlist_uploads/  # Temporary upload directory

Configuration File Locations¶

• Backend: No configuration files - all settings via environment variables
• Frontend: .env file in frontend directory (development only)
• Agent: Configuration stored in ${KH_CONFIG_DIR}/agent.json (auto-generated)
• Docker: .env file in project root for docker-compose

Common Configuration Scenarios¶

Development Setup¶

# .env file for development
DEBUG=true
LOG_LEVEL=DEBUG
KH_TLS_MODE=self-signed
JWT_SECRET=dev-secret-key
DB_HOST=localhost
DB_PASSWORD=dev-password

Production with Let's Encrypt¶

# .env file for production
DEBUG=false
LOG_LEVEL=INFO
KH_TLS_MODE=certbot
KH_CERTBOT_DOMAIN=kraken.example.com
KH_CERTBOT_EMAIL=admin@example.com
CLOUDFLARE_API_TOKEN=your-token
JWT_SECRET=secure-random-secret
DB_PASSWORD=strong-password

High-Security Environment¶

# .env file for high security
KH_TLS_MODE=provided
KH_CERT_FILE=/etc/ssl/certs/server.crt
KH_KEY_FILE=/etc/ssl/private/server.key
KH_CA_FILE=/etc/ssl/certs/ca-bundle.crt
KH_CERT_KEY_SIZE=4096
JWT_SECRET=very-long-secure-secret
DEBUG=false
DEBUG_SQL=false
DEBUG_HTTP=false

Agent Configuration¶

# Agent environment
KH_CONFIG_DIR=/opt/krakenhashes/config
KH_DATA_DIR=/opt/krakenhashes/data
HASHCAT_EXTRA_PARAMS=-O -w 3

Docker Production Deployment¶

# Production docker-compose override
PUID=1000
PGID=1000
KH_CONFIG_DIR_HOST=/opt/krakenhashes/config
KH_DATA_DIR_HOST=/data/krakenhashes
LOG_DIR=/var/log/krakenhashes
NGINX_CLIENT_MAX_BODY_SIZE=100M

Best Practices¶

1. Security:
2. Always use strong, unique values for JWT_SECRET in production
3. Never commit .env files with secrets to version control

4. Use environment-specific configurations

5. File Permissions:

6. Set PUID and PGID to match your host user for proper permissions

7. Ensure certificate files have restricted permissions (600 or 640)

8. TLS/SSL:

9. Use Let's Encrypt (certbot mode) for production
10. Self-signed certificates only for development

11. Always include all required DNS names and IP addresses

12. Performance:

13. Adjust KH_HASHLIST_BATCH_SIZE based on available memory
14. Configure NGINX_CLIENT_MAX_BODY_SIZE for expected file sizes

15. Set appropriate WebSocket timeouts for your network

16. Logging:

17. Use INFO level for production
18. Enable component-specific debugging only when needed

19. Regularly rotate log files

20. Database:

21. Use strong passwords in production
22. Consider using SSL for database connections in production
23. Regular backups of the PostgreSQL data volume

Troubleshooting¶

Common Issues¶

1. Certificate Errors:
2. Check KH_ADDITIONAL_DNS_NAMES includes all hostnames
3. Verify certificate paths are correct

4. Ensure proper file permissions

5. Database Connection:

6. Verify database credentials
7. Check network connectivity between containers

8. Ensure PostgreSQL is healthy before backend starts

9. File Upload Issues:

10. Check KH_MAX_UPLOAD_SIZE_MB setting
11. Verify NGINX_CLIENT_MAX_BODY_SIZE is sufficient

12. Ensure data directories have proper permissions

13. WebSocket Disconnections:

14. Adjust timeout values (KH_PONG_WAIT, KH_PING_PERIOD)
15. Check for proxy/firewall interference
16. Verify WebSocket URL configuration