# Halon DLP (content inspection) Service
Version: 10.2-stable
This is the documentation for Halon DLP (content inspection) Service *halon-dlpd*.
It’s a lightweight content inspection engine.
The package consists of one service called *halon-dlpd* which can be used to deeper inspect message content from within HSL.
It needs the client library of [halon-extras-dlp](https://github.com/halon-extras/dlp).
## Table of contents
* [Installation](#install)
* [Prerequisites](#install:prerequisites)
* [Distributions](#install:distributions)
* [Ubuntu](#install:ubuntu)
* [RHEL](#install:rhel)
* [Startup](#install:startup)
* [Docker & K8s](#install:docker-k8s)
* [Upgrade](#upgrade)
* [Configuration](#config)
* [Startup configuration](#config_dlpd)
* [Environment directives](#config_dlpd:environment-directives)
* [Configuration paths](#config_dlpd:configuration-paths)
* [Other environment](#config_dlpd:other-environment)
* [Running configuration](#config_dlpd_app)
* [Limits directive](#config_dlpd_app:limits-directive)
* [Rules directive](#config_dlpd_app:rules-directive)
* [Command line interface](#cli)
* [Configuration management](#cli:configuration-management)
* [Reloading configurations](#cli:reloading-configurations)
* [Changelog](#changelog)
# Installation
## Prerequisites
Make sure you have followed the [instructions](https://docs.halon.io/manual/install.html#installation) in our manual to add our package repository.
## Distributions
### Ubuntu
To install the .deb package use the following commands.
```console
# apt-get update
# apt-get install halon-dlpd
```
### RHEL
To install the .rpm package use the following commands.
```console
# yum install halon-dlpd
```
## Startup
When the initial [configuration](#config) is in place, the program can be started with:
```console
# systemctl start halon-dlpd
```
## Docker & K8s
For instructions on how to build a container image of the program as well as deploying it on K8s (Kubernetes),
see our [halon-docker](https://github.com/halon/halon-docker) GitHub repository.
# Upgrade
In order to upgrade the package, install the new package over the previous installed one (see the installation chapter).
After the upgrade the service needs to be manually restarted.
# Configuration
The configuration consists of files in YAML format on disk.
The package comes with multiple example configurations
in */opt/halon/share/examples*.
The default
[startup configuration](#config_dlpd)
loads the running configuration from */etc/halon/dlpd.yaml*.
The default
[running configuration](#config_dlpd_app)
loads the running configuration from */etc/halon/dlpd-app.yaml*
as per the [`environment.appconf`](#config_dlpd:confval-environment.appconf) directive in `dlpd.yaml`.
The [running configuration](#config_dlpd_app) containing the peers and can be softly reloaded
using the API or the [command line interface](#cli).
* [Startup configuration](#config_dlpd)
* [Environment directives](#config_dlpd:environment-directives)
* [Configuration paths](#config_dlpd:configuration-paths)
* [Other environment](#config_dlpd:other-environment)
* [Running configuration](#config_dlpd_app)
* [Limits directive](#config_dlpd_app:limits-directive)
* [Rules directive](#config_dlpd_app:rules-directive)
# Startup configuration
*halon-dlpd* loads the non-reloadable startup configuration is read from `/etc/halon/dlpd.yaml`.
Below are some of the most important settings that can be configured.
> **Note**
>
> The example configuration in */opt/halon/share/examples/* that is usually copied
> to */etc/halon/* during installation contains reasonable defaults.
> Normally you only need to modify the secret key to use.
## Environment directives
The default startup configuration that came with the installation package
contains reasonable defaults for your platform. Some settings should however
be revised.
### Configuration paths
Those paths can normally be left unchanged.
#### environment.appconf
From where to load the [running configuration](#config_dlpd_app).
The default is */etc/halon/dlpd-app.yaml*.
### Other environment
Those settings should normally be left unchanged.
The default startup configuration in */opt/halon/examples*
that came with the installation package should contain
correct parameters for your operating system or distribution.
#### environment.socket.path
Have the API socket on a UNIX socket. This option is mutually exclusive with the [`environment.controlsocket.port`](#config_dlpd:confval-environment.controlsocket.port) setting. The default is `/var/run/halon/dlpd.sock`.
#### environment.socket.owner
This option is only supported with the [`environment.socket.path`](#config_dlpd:confval-environment.socket.path) setting.
#### environment.socket.group
This option is only supported with the [`environment.socket.path`](#config_dlpd:confval-environment.socket.path) setting.
#### environment.socket.chmod
This option is only supported with the [`environment.socket.path`](#config_dlpd:confval-environment.socket.path) setting.
#### environment.controlsocket.path
Have the control socket on a UNIX socket. This option is mutually exclusive with the [`environment.controlsocket.port`](#config_dlpd:confval-environment.controlsocket.port) setting. The default is `/var/run/halon/dlpd.ctl`.
#### environment.controlsocket.owner
This option is only supported with the [`environment.controlsocket.path`](#config_dlpd:confval-environment.controlsocket.path) setting.
#### environment.controlsocket.group
This option is only supported with the [`environment.controlsocket.path`](#config_dlpd:confval-environment.controlsocket.path) setting.
#### environment.controlsocket.chmod
This option is only supported with the [`environment.controlsocket.path`](#config_dlpd:confval-environment.controlsocket.path) setting.
#### environment.controlsocket.port
Have the control socket on a TCP port. This option is mutually exclusive with the [`environment.controlsocket.path`](#config_dlpd:confval-environment.controlsocket.path) setting.
#### environment.controlsocket.address
Have the control socket listen on a specific IP address. This option is only supported with the [`environment.controlsocket.port`](#config_dlpd:confval-environment.controlsocket.port) setting.
#### environment.privdrop.user
The user to run the process as.
#### environment.privdrop.group
The group to run the process as.
#### environment.umask
Application umask after privdrop
#### environment.tmpdir
The default temp path for storing extracted files. The default is `/var/spool/halon/tmp/dlpd`.
# Running configuration
*halon-dlpd* loads the reloadable configuration from `/etc/halon/dlpd-app.yaml`.
Below are some of the most important settings that can be configured.
> **Note**
>
> The example configuration in */opt/halon/share/examples/* that is usually copied
> to */etc/halon/* during installation contains reasonable defaults.
> Normally you only need to modify the secret key to use.
## Limits directive
### limits.filememory
The max bytes for in memory file scanning. The default is `1048576` bytes.
## Rules directive
A list of named rules. Rules can also be passed to the service over the API.
### rules[].name
The rule name. Needs to be uppercase A-Z,0-9. This field is required.
### rules[].type
The rule type. This field is required.
> - regex
> - filename
> - mimetype
> - md5hash
> - sha1hash
> - sha2hash
### rules[].data
The rule data. Supports multiple patterns seperated one per line.
# Command line interface
The `dlpd` package comes with a program called `dlpctl` that
can be used to manage any aspect of the dlpd process. This section is a guide for
that program.
Every command have a `--help` flag to display available options.
The *dlpctl* program communicates with the `dlpd`
processes over the control sockets.
The raw JSON response data can be useful
when using the CLI for scripting with tools like *jq*,
and the request data can be useful when learning about the API.
Therefore, the commands have a `--json` output flag making it return the raw response
and a `--json-request` flag that prints the raw request (JSON encoded).
## Configuration management
These sub-commands can reload the [running configuration](#config_dlpd_app)
See the [configuration](#config_dlpd_app) section for more information.
### Reloading configurations
You can also invoke the individual reload commands directly:
```console
$ dlpctl reload # /etc/halon/dlpd-app.yaml
```
# Changelog
## 10.2.2
Released on 2026-04-28
- **Pkg** Update OpenSSL to 3.5.6
- **Bug** Fixed rare memory leak during regex checks
## 10.2.1
Released 2026-04-08
- **Bug** Fix issue with build-id symlinks for rpm packages
## 10.2.0
Released 2026-03-19
- **New** Performance improvements in message parser
- **Imp** `LD_LIBRARY_PATH` is no longer needed to be set
- **Pkg** Update OpenSSL to 3.5.5
## 10.1.0
Released 2025-06-25
- **Pkg** Clean up of installation package dependencies
- **Pkg** Upgraded pcre dependency to pcre2
## 10.0.1
Released 2025-04-01
- **Bug** Fix issue with unsupported protocol version when using `dlpctl`
## 10.0.0
Released 2025-03-25
- **New** Version change from 6.5.x to 10.0 (to be tracked individually)