HSL

From Halon, SMTP software for hosting providers
Revision as of 15:45, 19 November 2015 by Erik (talk | contribs)
Jump to: navigation, search
Halon Scripting Language (HSL) is documented in the reference manual.

The Halon Scripting Language (HSL) is the core component for configuration of e-mail, user authentication and IP flows. The language itself has a shared core (library), and extensions that are implemented per context by different processes, such as system user authentication, IP firewall and most importantly the e-mail oriented flows that maps to SMTP commands; AUTH (SASL), RCPT TO, DATA and queue processing pre- and post- delivery.

The core functions are "shared", and can be executed in any context. You can think of the other contexts (IP, e-mail context, etc) as language extensions since they both add a few pre-defined variables and functions that can be used in each one of the flows. In practice, the core functions are part of the scripting library, and the contexts are implemented in the respective process: for example, the IP flow process ippolicyd implements functions such as Allow() and Block(), that operates on the IP packets.

Although the syntax and function names in HSL are very much similar to PHP, Python, Perl and C, it is important to remember that it's a completely different scripting language. There are syntax differences, and the performance characteristics of different coding styles are not comparable between these languages.

Learning HSL

In order to master HSL you need to know the essence of the language, which is inspired by C, Perl and PHP. This includes the syntax, control structures, data types and core functions. This reference guide assumes you have some basic knowledge on computer programming. One can also learn by reviewing the code/blocks before saving.

Functions and contexts

Core functions are recognized by their lowercase names, and can be used in any flow (which maps to a script executed by a process). Most functions are indeed core functions, for reusability. Other functions which are context dependent, such as the Block() function, blocking an IP packet, have capitalized names.

Below is a table relating functions and SMTP commands to HSL contexts/extensions

Context Process Description
Core all processes Global functions shared among all processes
IP ippolicyd Handling IP packets, like a scripted firewall
Mail AUTH mailpolicyd Handling SMTP AUTH LOGIN (SASL) requests
Mail RCPT TO mailpolicyd Handling the SMTP RCPT TO command
Mail DATA mailscand Handling the SMTP DATA command; in other words "the mail message"
Mail pre-delivery (queue) mailqueued Decides what is to be done before a delivery is attempted
Mail post-delivery (transport) mailqueued Decides what is to be done when a delivery attempt is done
System user authentication backend Handling administration (SOAP API) sign-ins, suitable for RADIUS/TACACS+ integration

IP flow context

The IP Policy variables and functions are only available when creating a IP flow. It operates on IP packets, and have thus only functions like Block() and Allow(). In order to produce meaningful scripts/flows, network functions from the core component can be used, such as in_network(), dns() or globalview(). The scripts are processed by ippolicyd.

Mail flow context

The mail flows are all closely tied to SMTP, as they are executed in each stage of the SMTP conversation, by different processes. The Authentication and Recipient flows are very much alike (and both part of the process mailpolicyd) but are processed in two different steps (EHLO/AUTH vs. MAIL FROM/RCPT TO). The Mail Content flow is issued when the entire e-mail is received (DATA), and processed by the mailscand process. The pre-delivery (queue) flow is issued before a delivery attempt is made (it's where you may dynamically change transport settings, such as destination and SASL credentials). The post-delivery (transport) flow is issued after each delivery attempt, either successful or failed. Both are processed in the outgoing queue transport process; mailqueued.