Halon manual

Halon is a fast, flexible and powerful email infrastructure software (MTA); designed for demanding uses such as large-scale email services. The Halon 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. 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. Environment directives
      • 3.1.5.1. Performance and log
      • 3.1.5.2. Configuration paths
      • 3.1.5.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. Performance tuning
    • 3.3.1. Thread tuning
      • 3.3.1.1. servers[].threads.event
      • 3.3.1.2. threads.scripts[].count
      • 3.3.1.3. queues.threads.pickup
      • 3.3.1.4. resolver.threads.event
    • 3.3.2. Startup configuration
      • 3.3.2.1. environment.syslog.mask
      • 3.3.2.2. spool.fsync
      • 3.3.2.3. environment.uuid.version
    • 3.3.3. Running configuration
      • 3.3.3.1. servers[].logging
      • 3.3.3.2. servers[].phases.connect.remoteptr
      • 3.3.3.3. servers[].phases.data.multipart
      • 3.3.3.4. servers[].phases.data.fixheaders
    • 3.3.4. Resolver subsystem
    • 3.3.5. Queueing subsystem
      • 3.3.5.1. pooling
• 4. Queuing subsystem
  • 4.1. Activity diagram
  • 4.2. Queue states
    • 4.2.1. Moving messages
    • 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. Policy counter thresholds
      • 4.3.2.2. Policy conditions
      • 4.3.2.3. Policy properties
      • 4.3.2.4. Policy counter groups
    • 4.3.3. Queue pickup suspension
      • 4.3.3.1. Excluding IPs from pool
    • 4.3.4. Delivery settings
  • 4.4. Spool startup
  • 4.5. On-disk format
• 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