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.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. Queue directives
    • 3.1.3. Threads directives
      • 3.1.3.1. Scripts
      • 3.1.3.2. Events
    • 3.1.4. Other directives
    • 3.1.5. Clustering directives
    • 3.1.6. Environment directives
      • 3.1.6.1. Performance and log
      • 3.1.6.2. Configuration paths
      • 3.1.6.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. Queue directives
    • 3.2.5. General directives
    • 3.2.6. List directives
    • 3.2.7. Resolver directives
    • 3.2.8. Other directives
    • 3.2.9. Example
    • 3.2.10. Additional configurations
      • 3.2.10.1. Queue policy
      • 3.2.10.2. Queue suspend
      • 3.2.10.3. Queue delivery
      • 3.2.10.4. Rate subsystem
      • 3.2.10.5. Content inspection
  • 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.threads.loader.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.5. Queueing subsystem
      • 3.6.5.1. pooling
    • 3.6.6. Memory tuning
• 4. Queuing subsystem
  • 4.1. Activity diagram
  • 4.2. Queue states
    • 4.2.1. Changing message states
    • 4.2.2. Messages on hold
  • 4.3. Active queue
    • 4.3.1. Active queue pickup
    • 4.3.2. Queue pickup policies
      • 4.3.2.1. Available fields
      • 4.3.2.2. Loading
      • 4.3.2.3. Policy counter thresholds
      • 4.3.2.4. Policy conditions
      • 4.3.2.5. Policy properties
      • 4.3.2.6. 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.3.2. Observing clustered policy in operation
  • 4.5. Queue pickup suspension
    • 4.5.1. Excluding IPs from pool
    • 4.5.2. Delivery settings
  • 4.6. Spool startup
  • 4.7. On-disk format
  • 4.8. Moving messages between instances
• 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
    • 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. Rate function
    • 5.3.2. Shared memory functions
    • 5.3.3. Cache statement
  • 5.4. DNS resolver
  • 5.5. Statistics and information
    • 5.5.1. halontop
    • 5.5.2. halonctl
  • 5.6. Script interpreter
    • 5.6.1. Options
    • 5.6.2. Script interpreter
    • 5.6.3. Interactive shell
• 6. API
  • 6.1. Endpoints
    • 6.1.1. Control sockets
    • 6.1.2. HTTP/JSON
      • 6.1.2.1. Installation
        • 6.1.2.1.1. Distributions
          • 6.1.2.1.1.1. Ubuntu
          • 6.1.2.1.1.2. RHEL
        • 6.1.2.1.2. Startup
      • 6.1.2.2. Upgrade
      • 6.1.2.3. Configuration
        • 6.1.2.3.1. Authentication directives
        • 6.1.2.3.2. Listener directives
        • 6.1.2.3.3. Other directives
        • 6.1.2.3.4. Environment directives
      • 6.1.2.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.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.3. Development
    • 9.3.1. hsh
      • 9.3.1.1. hsh.yaml
      • 9.3.1.2. hsh-app.yaml
  • 9.4. Examples

• Changelog