Document OSSEC 4.1.0 SMTP TLS/auth and decoder field limits

atomicturtle · atomicturtle · commit 136e726f1bca · 2026-05-28T10:49:27.000-04:00
Update the documentation on branch v4.1.0 to match ossec-hids 4.1.0 behavior:
authenticated SMTP delivery, higher decoder order limits, and related release notes.

- Add global ossec.conf options for SMTP auth/TLS (auth_smtp, secure_smtp,
  smtp_port, smtp_tls_verify, smtp_user, smtp_password, helo_server) and
  libcurl build requirements
- Add manual page smtp-authenticated-email.rst with configuration examples;
  cross-link from existing email output guides
- Document analysisd.decoder_order_size (default 256) and link from decoder.order
- Document maild.max_workers; extend ossec-maild, install, and syscheck pages
- Bump conf.py release to 4.1.0 and add changelog.rst 4.1.0 section
- Add aes_encryption.rst to the manual notes toctree

Signed-off-by: Scott R. Shinn &lt;scott@atomicorp.com&gt;
diff --git a/changelog.rst b/changelog.rst
@@ -1,6 +1,18 @@
 Change Log
 ----------
 
+4.1.0 (2026/05/28 12:00 +00:00)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Stability and scalability release.
+- Added SMTP TLS and authentication support in ``ossec-maild`` and ``ossec-monitord`` (requires libcurl build).
+- Increased default decoder field limit (``analysisd.decoder_order_size``) to 256.
+- Increased maximum log message buffer (``OS_MAXSTR``) to 6144 to reduce truncation.
+- Improved IPv6 support in active-response whitelisting and ``install.sh``.
+- Added support for large files (>2GB) in file integrity monitoring and hash operations.
+- Added support for Rocky Linux 9.
+- Multiple bug fixes for ``analysisd``, ``logcollector``, FIM, and Windows agent stability.
+
 4.0.0 (2026/02/01 12:00 +00:00)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/conf.py b/conf.py
@@ -9,7 +9,7 @@
 project = 'OSSEC'
 copyright = 'Atomicorp, Inc. 2025'
 author = 'Atomicorp'
-release = '4.0.0'
+release = '4.1.0'
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
diff --git a/docs/manual/installation/install-source-unattended.rst b/docs/manual/installation/install-source-unattended.rst
@@ -125,6 +125,14 @@ Example preloaded-vars.conf:
    # USER_EMAIL_SMTP defines the SMTP server to send the e-mails.
    #USER_EMAIL_SMTP="test.ossec.net"
 
+   # SMTP authentication and TLS (requires USE_CURL=yes at build; install.sh sets this automatically)
+   #USER_SMTP_AUTH="y"
+   #USER_SMTP_USER="user@example.com"
+   #USER_SMTP_PASS="secret"
+   #USER_SMTP_SECURE="n"
+   #USER_SMTP_PORT="587"
+   #USER_SMTP_TLS_VERIFY="y"
+
 
    # USER_ENABLE_SYSLOG enables or disables remote syslog.
    #USER_ENABLE_SYSLOG="y"
@@ -143,9 +151,9 @@ Example preloaded-vars.conf:
    #USER_PF_TABLE="ossec_fwtable"
 
 
-   # USER_WHITE_LIST is a list of IPs or networks
-   # that are going to be set to never be blocked.
-   #USER_WHITE_LIST="192.168.2.1 192.168.1.0/24"
+   # USER_WHITE_LIST is a list of IPs or networks (IPv4 or IPv6) that are never blocked
+   # by active response.
+   #USER_WHITE_LIST="192.168.2.1 192.168.1.0/24 2001:db8::1 2001:db8::/32"
 
 
    #### exit ? ###
diff --git a/docs/manual/installation/installation-requirements.rst b/docs/manual/installation/installation-requirements.rst
@@ -66,14 +66,30 @@ libevent
 `libevent <http://libevent.org/>`_ was added for `ossec-agentd` and `ossec-maild`. A development package
 for this should be installed on the system.
 
+libcurl
+-------
+
+.. versionadded:: 4.1.0
+
+`libcurl <https://curl.se/libcurl/>`_ is required to build SMTP authentication and TLS support in
+``ossec-maild`` and ``ossec-monitord``. Install the development package on the build host. The
+installer enables ``USE_CURL=yes`` automatically when SMTP auth, secure SMTP, a non-default port,
+or disabled TLS verification is selected.
+
+If you compile manually and need authenticated or TLS SMTP, build with:
+
+.. code-block:: console
+
+   make USE_CURL=yes
+
 RedHat / Centos / Fedora / Amazon Linux
 ---------------------------------------
 
 Step 1) At a minimum, the following packages should be installed:
 
 .. code-block:: console
 
-   yum install zlib-devel pcre2-devel make gcc sqlite-devel openssl-devel libevent-devel systemd-devel
+   yum install zlib-devel pcre2-devel make gcc sqlite-devel openssl-devel libevent-devel libcurl-devel systemd-devel
 
 Step 2) For optional database support add thepackage mysql-devel and/or postgresql-devel packages
 
@@ -97,7 +113,7 @@ At a minimum, the following packages should be installed:
 
 .. code-block:: console
 
-   apt-get install build-essential make zlib1g-dev libpcre2-dev libevent-dev libssl-dev libsystemd-dev
+   apt-get install build-essential make zlib1g-dev libpcre2-dev libevent-dev libssl-dev libcurl4-openssl-dev libsystemd-dev
 
 On Debian 10 Buster, `zlib` could be `libz`.
 
diff --git a/docs/manual/notes/index.rst b/docs/manual/notes/index.rst
@@ -5,6 +5,7 @@ Misc. Notes
 .. toctree::
     :maxdepth: 2
 
+    aes_encryption
     active_directory_failures
     agentless_script
     checkpoint_configure
diff --git a/docs/manual/output/email-output.rst b/docs/manual/output/email-output.rst
@@ -18,6 +18,7 @@ There are currently three types of email alerts:
 
 .. toctree::
 
-    standard-email-output 
+    standard-email-output
+    smtp-authenticated-email
     granular-email-output
-    reports-email-output 
+    reports-email-output
diff --git a/docs/manual/output/granular-email-output.rst b/docs/manual/output/granular-email-output.rst
@@ -9,6 +9,8 @@ OSSEC allows very granular options for the e-mail alerting and its format (full
     Note that there must be at least one <email_to> recipient mentioned in the <global> 
     section of the configuration or no emails will be sent at all.
 
+If your mail provider requires authentication or TLS, configure the ``<global>`` section as
+described in :ref:`manual-out-smtp-auth` before adding ``<email_alerts>`` entries.
 
 .. include:: ../../examples/output/granular_email_examples.trst
 
diff --git a/docs/manual/output/smtp-authenticated-email.rst b/docs/manual/output/smtp-authenticated-email.rst
@@ -0,0 +1,146 @@
+
+.. _manual-out-smtp-auth:
+
+SMTP authentication and TLS
+===========================
+
+.. versionadded:: 4.1.0
+
+Starting with OSSEC 4.1.0, ``ossec-maild`` and ``ossec-monitord`` can send email through SMTP servers
+that require authentication and TLS. This requires OSSEC to be built with libcurl (``USE_CURL=yes``).
+The installer sets this automatically when you enable SMTP authentication, secure SMTP, a custom port,
+or disable TLS certificate verification during ``install.sh``.
+
+All options are configured in the ``<global>`` section of ``ossec.conf``. See :ref:`ossec_config.global`
+for the full syntax reference.
+
+Build requirements
+------------------
+
+Install libcurl development packages on the build host before compiling:
+
+Red Hat family:
+
+.. code-block:: console
+
+   yum install libcurl-devel
+
+Debian / Ubuntu:
+
+.. code-block:: console
+
+   apt-get install libcurl4-openssl-dev
+
+If you build manually without ``install.sh``, pass ``USE_CURL=yes`` to ``make``:
+
+.. code-block:: console
+
+   cd ossec-hids-*
+   make USE_CURL=yes
+   ./install.sh
+
+Submission port with STARTTLS (port 587)
+----------------------------------------
+
+Typical configuration for providers that use authenticated submission with STARTTLS
+(``auth_smtp=yes``, ``secure_smtp=no``):
+
+.. code-block:: xml
+
+    <ossec_config>
+        <global>
+            <email_notification>yes</email_notification>
+            <email_to>alerts@example.com</email_to>
+            <email_from>ossec@example.com</email_from>
+            <smtp_server>smtp.example.com</smtp_server>
+            <auth_smtp>yes</auth_smtp>
+            <secure_smtp>no</secure_smtp>
+            <smtp_port>587</smtp_port>
+            <smtp_user>ossec@example.com</smtp_user>
+            <smtp_password>your-secret-here</smtp_password>
+            <smtp_tls_verify>yes</smtp_tls_verify>
+        </global>
+        <alerts>
+            <email_alert_level>7</email_alert_level>
+        </alerts>
+    </ossec_config>
+
+If ``smtp_port`` is omitted and ``auth_smtp`` is ``yes``, port **587** is used automatically.
+
+SMTPS (implicit TLS, port 465)
+------------------------------
+
+Use ``secure_smtp=yes`` when the server expects TLS from the first byte (SMTPS):
+
+.. code-block:: xml
+
+    <ossec_config>
+        <global>
+            <email_notification>yes</email_notification>
+            <email_to>alerts@example.com</email_to>
+            <email_from>ossec@example.com</email_from>
+            <smtp_server>smtp.example.com</smtp_server>
+            <secure_smtp>yes</secure_smtp>
+            <smtp_port>465</smtp_port>
+            <smtp_user>ossec@example.com</smtp_user>
+            <smtp_password>your-secret-here</smtp_password>
+        </global>
+    </ossec_config>
+
+If ``smtp_port`` is omitted and ``secure_smtp`` is ``yes``, port **465** is used automatically.
+
+Plain SMTP (port 25)
+--------------------
+
+Legacy servers without authentication continue to work as before. Do not set ``auth_smtp`` or
+``secure_smtp`` unless the server requires them:
+
+.. code-block:: xml
+
+    <ossec_config>
+        <global>
+            <email_notification>yes</email_notification>
+            <email_to>alerts@example.com</email_to>
+            <smtp_server>192.168.1.10</smtp_server>
+        </global>
+    </ossec_config>
+
+Testing and restarting
+----------------------
+
+Test the configuration without sending mail:
+
+.. code-block:: console
+
+    # /var/ossec/bin/ossec-maild -t
+
+Restart OSSEC after changing mail settings:
+
+.. code-block:: console
+
+    # /var/ossec/bin/ossec-control restart
+
+Unattended installation
+-----------------------
+
+For unattended installs, set the following in ``etc/preloaded-vars.conf`` in addition to
+``USER_ENABLE_EMAIL``, ``USER_EMAIL_ADDRESS``, and ``USER_EMAIL_SMTP``:
+
+.. code-block:: console
+
+   USER_SMTP_AUTH="y"
+   USER_SMTP_USER="user@example.com"
+   USER_SMTP_PASS="secret"
+   USER_SMTP_SECURE="n"
+   USER_SMTP_PORT="587"
+   USER_SMTP_TLS_VERIFY="y"
+
+See :ref:`install_source_unattended` for the full preloaded-vars example.
+
+Security notes
+--------------
+
+- Restrict permissions on ``ossec.conf`` because ``smtp_password`` is stored in plain text.
+- Avoid ``smtp_tls_verify=no`` in production; it disables certificate and hostname verification.
+- If ``smtp_server`` is a hostname, ensure name resolution works from ``/var/ossec/etc`` (copy
+  ``/etc/resolv.conf`` when needed).
diff --git a/docs/manual/output/standard-email-output.rst b/docs/manual/output/standard-email-output.rst
@@ -17,11 +17,13 @@ The destination email address and mail host should be configured inside the
         <global>
             <email_notification>yes</email_notification>
             <email_to>me@example.com</email_to>
-            <smtp_server>mx.example.com..</smtp_server>
+            <smtp_server>mx.example.com</smtp_server>
             <email_from>ossec@example.com</email_from>
 
 Full details on all the options are available at :ref:`ossec_config.global`
 
+If your mail provider requires authentication or TLS, see :ref:`manual-out-smtp-auth`.
+
 .. note::
 
    If the `smtp_server` entry contains a hostname, `/etc/resolv.conf` will probably have to be 
diff --git a/docs/manual/syscheck/index.rst b/docs/manual/syscheck/index.rst
@@ -48,6 +48,10 @@ Quick facts
   
   - The scans are performed slowly to avoid using too much CPU/memory.
 
+* Are large files supported?
+
+  - Starting with OSSEC 4.1.0, files larger than 2GB can be monitored and hashed.
+
 * How are false positives handled? 
   
   - Files can be ignored manually in the configuration or using rules. By default when a file has changed 3 times further changes are automatically ignored.
diff --git a/docs/programs/ossec-maild.rst b/docs/programs/ossec-maild.rst
@@ -8,6 +8,10 @@ The ``ossec-maild`` daemon sends OSSEC alerts via email.
 ``ossec-maild`` is started by ossec-control.
 Configuration for ossec-maild is handled in the ossec.conf. (see :ref:`ossec_config.global`)
 
+When OSSEC is built with libcurl (``USE_CURL=yes``, enabled automatically by ``install.sh`` when
+SMTP authentication or TLS is configured), ``ossec-maild`` delivers mail over authenticated SMTP
+with TLS support. See :ref:`manual-out-smtp-auth`.
+
 ossec-maild argument options
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -43,7 +47,8 @@ ossec-maild argument options
 
 .. option:: -t
 
-    Test configuration.
+    Test the email configuration. When libcurl SMTP is enabled, this validates connectivity and
+    TLS settings against the configured ``smtp_server`` without sending alert mail.
 
 .. option:: -u <user>
 
diff --git a/docs/syntax/decoders.trst b/docs/syntax/decoders.trst
@@ -94,6 +94,12 @@
    This option names the fields used by the `regex` or `pcre2` options.
    The field names are comma separated.
 
+   The number of fields in ``order`` and the number of capture groups in ``regex`` or ``pcre2``
+   are both limited by ``analysisd.decoder_order_size`` in ``internal_options.conf`` (default
+   **256** in 4.1.0). See :ref:`intopt_analysisd`. If the limit is exceeded, analysisd logs
+   ``Order has too many fields`` or ``Regex has too many groups``; raise the value in
+   ``local_internal_options.conf`` and restart.
+
    .. versionadded: 3.3
 
       The list below was previously the only field names that could be used.
diff --git a/docs/syntax/internal_options.analysisd.trst b/docs/syntax/internal_options.analysisd.trst
@@ -49,3 +49,20 @@
        **Default:** 0
 
        **Allowed:** Any integer 
+
+   - analysisd.decoder_order_size
+
+       .. versionadded:: 4.1.0
+
+       Maximum number of fields in a decoder ``<order>`` list and maximum number of capture
+       groups in a decoder ``<regex>`` or ``<pcre2>`` pattern.
+
+       **Default:** 256
+
+       **Allowed:** 8 to 1024
+
+       If a decoder exceeds this limit, ``ossec-analysisd`` logs an error such as
+       ``Order has too many fields`` or ``Regex has too many groups``. Increase this value in
+       ``/var/ossec/etc/local_internal_options.conf`` (not ``ossec.conf``) and restart OSSEC.
+
+       See also :ref:`rules_decoders` (``decoder.order``).
diff --git a/docs/syntax/internal_options.maild.trst b/docs/syntax/internal_options.maild.trst
@@ -30,3 +30,13 @@
        **Default:** 1
 
        **Allowed:** 0 or 1
+
+   - maild.max_workers
+
+       .. versionadded:: 4.1.0
+
+       Maximum number of parallel SMTP send threads used by ``ossec-maild``.
+
+       **Default:** 6
+
+       **Allowed:** 1 to 32
diff --git a/docs/syntax/ossec_config.global.trst b/docs/syntax/ossec_config.global.trst
