Upgrading to OSSEC 4.x

This guide covers breaking changes and recommended upgrade order when moving from OSSEC 3.8.x or earlier to 4.0.0 and later, including 4.1.0 and 4.2.0.

Agent encryption (4.0.0+)

Starting with 4.0.0, agent-manager traffic uses AES-256-CBC by default. Legacy Blowfish keys and connections are still supported on 4.0+ managers when configured.

Crypto interoperability matrix

Manager

Agent

Result

4.0+ (default) 4.0+ (default) 4.0+ (default) 3.8 or older

4.0+ (default) 3.8 or older 4.0+ blowfish 4.0+ (default)

AES — works Fails — upgrade agent Works if manager accepts Fails — upgrade mgr

Manager configuration

Restrict the manager to AES-only connections:

<remote>
  <crypto_accept>aes</crypto_accept>
</remote>

Accept both AES and Blowfish during a transition (default on 4.0+):

<remote>
  <crypto_accept>any</crypto_accept>
</remote>

Agent configuration

Force legacy Blowfish on a 4.0+ agent (temporary migration aid only):

<client>
  <crypto_method>blowfish</crypto_method>
</client>

New agent keys generated with manage_agents on 4.0+ use AES. See also AES Encryption Support for background on key formats.

File integrity monitoring (4.0.0+)

SHA-256 checksums are enabled by default for all monitored directories in 4.0.0. No configuration change is required for new installations.

Disable SHA-256 on specific paths (compatibility only):

<syscheck>
  <directories check_sha256sum="no">/path</directories>
</syscheck>

Large files (>2GB) are supported starting with 4.1.0 when the platform build enables 64-bit file offsets.

Re-keying agents after crypto changes

If agents fail to connect after a manager upgrade:

  1. Confirm the manager <remote> crypto_accept setting allows the agent’s method.

  2. On the manager, use manage_agents to list and verify the agent key exists.

  3. If keys were generated on an older version, extract a fresh key and re-import on the agent.

  4. Restart ossec-agentd on the agent after updating client.keys.

Email and reporting (4.1.0+)

SMTP TLS and authentication options in <global> apply to both ossec-maild and ossec-monitord report email. See Sending alerts via E-Mail and ossec.conf: Global options.

Analysisd and managers (4.2.0+)

Linux server installs of 4.2.0 use an always-on multi-threaded analysisd pipeline. Manager daemons also use pthreads and a shared thread pool. No configuration change is required for a normal upgrade; after upgrading the manager, confirm ossec-analysisd starts cleanly and that alert volume matches expectations under load.

Windows agents (4.2.0+)

The Windows agent installer for 4.2.0 bundles the MinGW/OpenSSL runtime DLLs required by the agent. Prefer the official 4.2.0 installer over copying an older .exe and pairing it with system DLLs.

See also