Halon manual

Halon Engage & Protect is a fast, flexible and powerful email infrastructure software (MTA); designed for demanding uses such as large-scale email services. The software is provided as Linux binaries, tooling for configuration and deployment, and management interfaces for maximum adaptability to specific uses.

This manual references many other resources, such as:

• Script language reference

• Script library

• Knowledge base

Table of contents

• 1. System requirements
  • 1.1. Storage disks
  • 1.2. CPU
  • 1.3. RAM
  • 1.4. DNS
  • 1.5. Linux tunables
• 2. Installation
  • 2.1. Linux
    • 2.1.1. Ubuntu
      • 2.1.1.1. Version pinning
    • 2.1.2. RHEL
      • 2.1.2.1. Version locking
    • 2.1.3. Azure Linux 3
  • 2.2. Docker & K8s
  • 2.3. Upgrade
    • 2.3.1. Versioning scheme
    • 2.3.2. Lifecycle compatibility
  • 2.4. License
  • 2.5. Configuration
  • 2.6. Programs
    • 2.6.1. Default paths
    • 2.6.2. File permissions
    • 2.6.3. Troubleshooting
• 3. Configuration
  • 3.1. Startup configuration
    • 3.1.1. Server directives
    • 3.1.2. Monitor directives
    • 3.1.3. Queue directives
    • 3.1.4. Threads directives
      • 3.1.4.1. Scripts
      • 3.1.4.2. Events
    • 3.1.5. Other directives
    • 3.1.6. Clustering directives
    • 3.1.7. Environment directives
      • 3.1.7.1. Performance and log
      • 3.1.7.2. Configuration paths
      • 3.1.7.3. Other environment
  • 3.2. Running configuration
    • 3.2.1. Script directives
    • 3.2.2. Server directives
    • 3.2.3. Transport directives
    • 3.2.4. Monitor directives
    • 3.2.5. Queue directives
    • 3.2.6. General directives
    • 3.2.7. List directives
    • 3.2.8. Resolver directives
    • 3.2.9. Other directives
    • 3.2.10. Example
  • 3.3. Suspend configuration
    • 3.3.1. Suspend directives
  • 3.4. Policy configuration
    • 3.4.1. Policy directives
    • 3.4.2. Rate directives
  • 3.5. Delivery configuration
    • 3.5.1. Delivery directives
  • 3.6. Performance tuning
    • 3.6.1. Thread tuning
      • 3.6.1.1. servers[].threads.event
      • 3.6.1.2. threads.scripts[].count
      • 3.6.1.3. queues.threads.pickup
      • 3.6.1.4. resolver.threads.event
    • 3.6.2. Startup configuration
      • 3.6.2.1. environment.syslog.mask
      • 3.6.2.2. spool.fsync
      • 3.6.2.3. spool.loader.threads.wait
      • 3.6.2.4. environment.uuid.version
    • 3.6.3. Running configuration
      • 3.6.3.1. servers[].logging
      • 3.6.3.2. servers[].phases.connect.remoteptr
      • 3.6.3.3. servers[].phases.data.multipart
      • 3.6.3.4. servers[].phases.data.fixheaders
    • 3.6.4. Resolver subsystem
      • 3.6.4.1. resolver.concurrency
    • 3.6.5. Queueing subsystem
      • 3.6.5.1. pooling
    • 3.6.6. Memory tuning
• 4. Queuing subsystem
  • 4.1. Active queue
    • 4.1.1. Active queue pickup
  • 4.2. Delivery settings
  • 4.3. Queue policies
    • 4.3.1. Available fields
    • 4.3.2. Loading policy
    • 4.3.3. Policy counter thresholds
      • 4.3.3.1. Policy conditions
      • 4.3.3.2. Policy properties
    • 4.3.4. Policy counter groups
  • 4.4. Cluster-aware policy
    • 4.4.1. Example architecture
    • 4.4.2. Delivery Orchestrator: clusterd
    • 4.4.3. Writing policy for clusters
      • 4.4.3.1. Advanced usage: selective non-clustered properties
    • 4.4.4. Observing clustered policy in operation
    • 4.4.5. Moving messages between instances
  • 4.5. Message suspension
    • 4.5.1. Excluding IPs from pool
  • 4.6. Changing message states
    • 4.6.1. Messages on hold
  • 4.7. Spool startup
  • 4.8. On-disk format
  • 4.9. Queue statistics via CLI/API
• 5. Command line interface
  • 5.1. Queue management
    • 5.1.1. List messages
    • 5.1.2. Export messages
    • 5.1.3. Take actions on messages
      • 5.1.3.1. Actions and working states
    • 5.1.4. Show messages distribution
    • 5.1.5. Active queue policies
    • 5.1.6. Active queue suspensions
    • 5.1.7. Active queue delivery settings
    • 5.1.8. Moving the queue files with hqfmove
    • 5.1.9. Trace messages
    • 5.1.10. Loading queue files
  • 5.2. Configuration management
    • 5.2.1. Script syntax and packing
    • 5.2.2. Reloading configurations
    • 5.2.3. Blue-green testing
    • 5.2.4. Remote configuration
  • 5.3. Script engine
    • 5.3.1. Shared memory functions
    • 5.3.2. Cache statement
  • 5.4. DNS resolver
  • 5.5. Statistics and information
    • 5.5.1. halontop
    • 5.5.2. halonctl process-stats
  • 5.6. Metrics summary
  • 5.7. Script interpreter
    • 5.7.1. Options
    • 5.7.2. Script interpreter
    • 5.7.3. Interactive shell
• 6. API
  • 6.1. Endpoints
    • 6.1.1. Monitor
      • 6.1.1.1. Endpoints
        • 6.1.1.1.1. /metrics
        • 6.1.1.1.2. /ready
        • 6.1.1.1.3. /healthy
    • 6.1.2. Control sockets
    • 6.1.3. HTTP/JSON
      • 6.1.3.1. Installation
        • 6.1.3.1.1. Distributions
          • 6.1.3.1.1.1. Ubuntu
          • 6.1.3.1.1.2. RHEL
        • 6.1.3.1.2. Startup
      • 6.1.3.2. Upgrade
      • 6.1.3.3. Configuration
        • 6.1.3.3.1. Authentication directives
        • 6.1.3.3.2. Listener directives
        • 6.1.3.3.3. Other directives
        • 6.1.3.3.4. Environment directives
      • 6.1.3.4. Examples
  • 6.2. API reference
    • 6.2.1. Command list
  • 6.3. Version compatibility
  • 6.4. HTTP submission
    • 6.4.1. Endpoint reference
      • 6.4.1.1. Authentication
      • 6.4.1.2. HTTP request format
      • 6.4.1.3. HTTP response format
    • 6.4.2. Examples
• 7. Web administration
• 8. Code editor integrations
  • 8.1. Visual Studio Code
    • 8.1.1. Extensions
      • 8.1.1.1. Configuration Packer
      • 8.1.1.2. HSL Syntax
      • 8.1.1.3. HSL Linter
      • 8.1.1.4. HSL Debugger
      • 8.1.1.5. Code Companion
        • 8.1.1.5.1. Providing feedback
        • 8.1.1.5.2. Working with Dev Containers and Remote SSH
        • 8.1.1.5.3. Limitations
        • 8.1.1.5.4. Copilot error messages
    • 8.1.2. Setting up a development environment
  • 8.2. Vim
    • 8.2.1. Features
    • 8.2.2. Installation
      • 8.2.2.1. Upgrade
    • 8.2.3. Screenshots
• 9. Plugins
  • 9.1. FFI
  • 9.2. Native plugins
    • 9.2.1. Exported by plugin
      • 9.2.1.1. Command plugin
      • 9.2.1.2. HSL plugin
      • 9.2.1.3. Queue plugin
      • 9.2.1.4. Delivery plugin
    • 9.2.2. Exported by MTA
      • 9.2.2.1. Objects
      • 9.2.2.2. Callable
      • 9.2.2.3. HSL plugin
      • 9.2.2.4. Lists plugin
      • 9.2.2.5. Inject plugin
      • 9.2.2.6. Import plugin
      • 9.2.2.7. Queue plugin
      • 9.2.2.8. Delivery plugin
      • 9.2.2.9. Monitor plugin
  • 9.3. Development
    • 9.3.1. hsh
      • 9.3.1.1. hsh.yaml
      • 9.3.1.2. hsh-app.yaml
  • 9.4. Examples

• Changelog