# Halon Rate Service Version: 10.2-stable This is the documentation for Halon Rate Service *halon-rated*. It’s a lightweight clustered sliding window rate limit service using opportunistic UDP for synchronization. For more advanced use-cases (or where a sliding window rate isn’t needed) softwares like [Redis](https://redis.io) may be more appropriate. - It is important to note that since the rated daemon is using UDP for syncing the rates it’s not possible to 100% guarantee that packets are never lost, either during the initial sync at startup or during regular operation. Because of this we recommend using the rate function for things where it’s not critical that the rates are always 100% identical in the cluster and that rate data is never lost. - The aim of the rated process is to be a very simple and fast rate database which is why it has been designed this way. Other solutions might be a better fit if data consistency is very important. The package consists of one service called *halon-rated* which can be used to coordinate various rates from within HSL in a cluster. It needs the client library of [halon-extras-rate](https://github.com/halon-extras/rate). ## 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_rated) * [Listener directives](#config_rated:listener-directives) * [Clustering directives](#config_rated:clustering-directives) * [Environment directives](#config_rated:environment-directives) * [Configuration paths](#config_rated:configuration-paths) * [Other environment](#config_rated:other-environment) * [Running configuration](#config_rated_app) * [Peers directive](#config_rated_app:peers-directive) * [Command line interface](#cli) * [Configuration management](#cli:configuration-management) * [Reloading configurations](#cli:reloading-configurations) * [Rate function](#cli:rate-function) * [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-rated ``` ### RHEL To install the .rpm package use the following commands. ```console # yum install halon-rated ``` ## Startup When the initial [configuration](#config) is in place, the program can be started with: ```console # systemctl start halon-rated ``` ## 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_rated) loads the running configuration from */etc/halon/rated.yaml*. The default [running configuration](#config_rated_app) loads the running configuration from */etc/halon/rated-app.yaml* as per the [`environment.appconf`](#config_rated:confval-environment.appconf) directive in `rated.yaml`. The [running configuration](#config_rated_app) containing the peers and can be softly reloaded using the API or the [command line interface](#cli). * [Startup configuration](#config_rated) * [Listener directives](#config_rated:listener-directives) * [Clustering directives](#config_rated:clustering-directives) * [Environment directives](#config_rated:environment-directives) * [Configuration paths](#config_rated:configuration-paths) * [Other environment](#config_rated:other-environment) * [Running configuration](#config_rated_app) * [Peers directive](#config_rated_app:peers-directive) # Startup configuration *halon-rated* loads the non-reloadable startup configuration is read from `/etc/halon/rated.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. ## Listener directives ### listen.port Which TCP port to listen on. The default is `13131`. ### listen.address IPv4 or IPv6 address to listen on. The default is to listen to all IPv4 and IPv6 addresses. ## Clustering directives ### key A HMAC-SHA1 key used for rate synchronization between `rated` instances in HEX format. > ```yaml > key: a3faf19660fea508afaab8648b4aa3b9f685acd0 # do not use this specific key > ``` ### syncdelay The microseconds delay between sending rate packages. This prevents network overload when doing UDP synchronization. The default is `25` microseconds. This allows 40’000 PPS. ### reresolve Automatically re-resolve the hostnames of the synchronization peers (as specific in rated-app.yaml) every x seconds (The default is to never re-resolve the hostnames of the synchronization peers automatically) ## 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_rated_app). The default is */etc/halon/rated-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_rated:confval-environment.controlsocket.port) setting. The default is `/var/run/halon/rated.sock`. #### environment.socket.owner This option is only supported with the [`environment.socket.path`](#config_rated:confval-environment.socket.path) setting. #### environment.socket.group This option is only supported with the [`environment.socket.path`](#config_rated:confval-environment.socket.path) setting. #### environment.socket.chmod This option is only supported with the [`environment.socket.path`](#config_rated: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_rated:confval-environment.controlsocket.port) setting. The default is `/var/run/halon/rated.ctl`. #### environment.controlsocket.owner This option is only supported with the [`environment.controlsocket.path`](#config_rated:confval-environment.controlsocket.path) setting. #### environment.controlsocket.group This option is only supported with the [`environment.controlsocket.path`](#config_rated:confval-environment.controlsocket.path) setting. #### environment.controlsocket.chmod This option is only supported with the [`environment.controlsocket.path`](#config_rated: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_rated: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_rated: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. > **Tip** > > The `privdrop.user` and `privdrop.group` settings to use will depend on your Linux distribution: > > * For Ubuntu, suitable values are `nobody` and `nogroup` > * For RHEL and related distibutions, the values are `nobody` and `nobody`. > > After installation, directory */opt/halon/share/examples/minimal/config/rated.yaml* on your host contains an example. # Running configuration *halon-rated* loads the reloadable configuration from `/etc/halon/rated-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. ## Peers directive ### peers[] A list of peers in the cluster. This option can be a list of IPv4, IPv6 or hostnames. It can also be an object. > ```yaml > peers: > - rated2.example.com > ``` ### peers[].address The peer address ### peers[].expand If all addresses (for that address) should be considered individual peers. This pattern in common in eg. Kubernetes. The default is `false`. # Command line interface The `rated` package comes with a program called `ratectl` that can be used to manage any aspect of the rated process. This section is a guide for that program. Every command have a `--help` flag to display available options. The *ratectl* program communicates with the `rated` 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_rated_app) See the [configuration](#config_rated_app) section for more information. ### Reloading configurations You can also invoke the individual reload commands directly: ```console $ ratectl reload # /etc/halon/rated-app.yaml ``` ## Rate function It’s possible to both list and clear rate. As per the example below. ```console $ ratectl list ┌───────────────────┬────────────┬───────┬─────────────┬────────┬────────┬────────────┐ │ Namespace │ Entry │ Count │ Local count │ Oldest │ Newest │ Rate (#/s) │ ├───────────────────┼────────────┼───────┼─────────────┼────────┼────────┼────────────┤ │ delivery-failures │ customer0 │ 1 │ 1 │ 8 │ 8 │ 0 │ │ delivery-failures │ customer1 │ 5 │ 5 │ 12 │ 4 │ 0.625 │ │ delivery-failures │ customer10 │ 1 │ 1 │ 8 │ 8 │ 0 │ ... $ ratectl clear --entry customer10 1 entries deleted ``` # Changelog ## 10.2.2 Released on 2026-04-28 - **Pkg** Update OpenSSL to 3.5.6 ## 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** New and improved table rendering library - **Imp** `LD_LIBRARY_PATH` is no longer required to be set - **Pkg** Update OpenSSL to 3.5.5 ## 10.1.0 Released 2025-06-25 - **Pkg** Clean up of installation package dependencies ## 10.0.1 Released 2025-04-01 - **Bug** Fix issue with unsupported protocol version when using `ratectl` ## 10.0.0 Released 2025-03-25 - **New** Version change from 6.5.x to 10.0 (to be tracked individually)