# Halon

> Halon 6.12-stable documentation

## Pages

- [Halon manual](index.html.md): Halon Engage & Protect is a fast, flexible and powerful email infrastructure software (MTA); designed for demanding uses such as large-scale email services.
- [System requirements](requirements.html.md): This section describes hardware requirements and software tuning for correct and performant operations.
- [Installation](install.html.md): The programs are installed using a Linux distribution package manager according to the corresponding instructions, or by manually copying the files to the /opt/halon directory.
- [Configuration](config.html.md): The configuration consists of files in YAML format on disk.
- [Startup configuration](config_startup.html.md): This is the non-reloadable part of the configuration.
- [Running configuration](config_smtpd.html.md): The SMTP server (smtpd) handles all email going in and out, including the queue subsystem.
- [Suspend configuration](config_suspend.html.md): This file holds all static suspends that should be enforced when the system starts.
- [Policy configuration](config_policy.html.md): This file holds all static policies that should be enforced when the system starts.
- [Delivery configuration](config_delivery.html.md): This file contains delivery configuration, including settings like pooling and retries.
- [Performance tuning](config_tuning.html.md): Halon will perform well with the default configuration.
- [Queuing subsystem](queue.html.md): Halon provides control and flexibility on how messages are handled and delivered, according to policies that you define.
- [Active queue](queue_active.html.md): Message delivery goes through five stages:
- [Delivery settings](queue_delivery.html.md): The active queue delivery configuration can be used to set parameters such as timeouts and connection pooling based on fields that are only available in the active queue state, such as remotemx and remoteip.
- [Queue policies](queue_policy.html.md): Halon provides powerful policy features to control the flow of emails from the queue to recipients.
- [Cluster-aware policy](queue_cluster.html.md): Generated messages are network load-balanced across all Halon instances, which are configured identically.
- [Message suspension](queue_suspend.html.md): The pickup policy subsystem implements a suspension list to enforce concurrency, rate and connectinterval limits.
- [Changing message states](queue_changing.html.md): Messages are automatically moved between the active and defer queue in accordance with the normal behavior of an MTA (try-defer-retry-defer, etc).
- [Spool startup](queue_load.html.md): Upon startup the spool directory (spool.path directive) is scanned for queued messages (.hqf files).
- [Queue statistics via CLI/API](queue_cli.html.md): The Protocol Buffer API and CLI provides statistics:
- [Command line interface](cli.html.md): There are three primary ways of managing hosts (or clusters of); the web administration, API (Protocol Buffer) or CLI.
- [Queue management](cli_queue.html.md): These sub-commands operate on the queue (which contains queued email messages) in various ways.
- [Configuration management](cli_config.html.md): These sub-commands can reload the running configuration (including its Halon script) and control the built-in blue-green testing that we call “live stage”.
- [Script engine](cli_script.html.md): These sub-commands can work on various parts of the Halon script engine.
- [DNS resolver](cli_dns.html.md): These commands can clear and view statistics about the asynchronous DNS resolver’s built-in cache.
- [Statistics and information](cli_stats.html.md): Shows information about process statistics (cache hits, internal queue sizes) and other information such as email queue size.
- [Metrics summary](openmetrics.html.md): The following standard metrics are output by the halonctl process-stats command and the monitor interface in OpenMetrics format.
- [Script interpreter](cli_hsh.html.md): The hsh program is a Halon script interpreter and interactive shell (REPL).
- [API](api.html.md): The smtpd process is controlled via an API, which in turn is used by management tools such as the command line interface, Visual Studio Code integration, and web administration.
- [Endpoint](api_endpoints.html.md): The primary API is the control socket.
- [Monitor](api_monitor.html.md): The monitor.type endpoint provides an OpenMetrics compatible endpoint as well as health check endpoints which can signal the (un)ready and health states of the process.
- [Control socket](api_control_sockets.html.md): The smtpd process has a control socket as specified by environment.controlsocket.path or environment.controlsocket.port.
- [HTTP/JSON](api_http_json.html.md): Rather than connecting directly to the control socket, there is a JSON over HTTP endpoint that proxies calls to the smtpd control socket.
- [Installation](api_install.html.md): The HTTP/JSON API is installed using a Linux distribution package manager according to the corresponding instructions, or by manually copying the files to the /opt/halon/api directory.
- [Upgrade](api_upgrade.html.md): In order to upgrade the package, install the new package over the previous installed one (see the installation chapter).
- [Configuration](api_config.html.md): halon-api loads the non-reloadable configuration from /etc/halon/api.yaml.
- [Examples](api_examples.html.md): Simple example without request body (payload)
- [API reference](api_reference.html.md): The API request and response bodies are defined by the Protocol Buffer schemas.
- [HTTP submission](http_submission.html.md): Halon supports message submission through a HTTP API.
- [Web administration](web.html.md): There are three primary ways of managing hosts (or clusters of); the web administration, API (Protocol Buffer) or CLI.
- [Code editor integrations](editors.html.md): We have created integrations for working with the configuration using the code editors listed below.
- [Visual Studio Code](vscode.html.md): Halon has a fully-featured integration with Visual Studio Code that leverages Visual Studio Code Remote Development which allows you to connect to a container or remote machine (where Halon is installed) to work with it’s configuration, including linting and debugging it’s Halon script (HSL) source files.
- [Vim](vim.html.md): We have created a Vim plugin to make it easier to work with our configuration.
- [Plugins](plugins.html.md): This section describes methods for extending the functionality of the MTA by loading C-compatible libraries written in programming languages other than Halon script (HSL).
- [FFI](plugins_ffi.html.md): The FFI system allows you to load C-compatible libraries and call their functions from Halon script (HSL).
- [Native plugins](plugins_native.html.md): There are multiple types of native plugins that can be built working with Halon script (HSL), queue, policies, suspensions and delivery.
- [HSL plugins](plugins_hsl.html.md): Plugins written in HSL should be installed inside a per-plugin folder inside of environment.pluginspath/hsl/example.
- [Development](plugins_development.html.md): The hsh program allows for a convenient building and testing environment when developing functions for the Halon scripting language.
- [Examples](plugins_examples.html.md): Plugin examples written in HSL, C, C++, Rust and Go are available in the GitHub repository.
- [Changelog](changelog.html.md): Released 2026-10-28

## Optional

- [llms-full.txt](llms-full.txt): Complete documentation in a single file.