The agent-auth program is the client application used with ossec-authd to automatically add agents to an OSSEC manager.


By default there is no authentication or authorization involved in this transaction, so it is recommended that this daemon only be run when a new agent is being added.

agent-auth argument options

-A <agent_name>

Agent name to be used. Default hostname


Directory where OSSEC is installed. Default /var/ossec


Execute agent-auth in debug mode. This option can be used multiple times to increase the verbosity of the debug messages.

-g <group>

Run as group.


Display the help message

-k <path>

Load the certificate’s corresponding PEM encoded private key.

-m <manager_ip>

IP address of the manager.

-p <port>

Port ossec-authd is running on.

Default 1515


Display OSSEC Version and license information.

-v <path>

Load the PEM encoded CA Certificate that will be used to verify ossec-authd if desired. If this option is used then ossec-authd must present a valid certificate signed by this CA.

-x <path>

Load the PEM encoded certificate that will be presented to ossec-authd during establishment of the SSL connection.

Optional Server Authentication - client side

agent-auth can verify that the server it’s connecting to presents a valid X.509 certificate when requesting a key. This is optional and is only useful if hosts in your environment have access to the root certificate of the CA that signed the certificate presented by ossec-authd. If server certificate verification is desired then the relevant CA certificate must be loaded with the -v option, then if the server does not present a valid certificate the agent will not be allocated a key.

A certificate presented by the server may be found to be invalid for the following reasons:

  • It was not signed by the specified CA.

  • It doesn’t contain the IP address or hostname given with the -m option in the subject’s common name field or a subject alternative name extension field.

  • It is expired.

While server authentication is optional it is highly recommended that it be used if possible when running ossec-authd and agent-auth.

Optional Client Authentication

agent-auth can present its own certificate to the server for verification. This is mandatory if ossec-authd was run with the -v option and optional otherwise. This is only useful if hosts in your environment are assigned certificates when they’re provisioned (or at some point before being added to OSSEC). Use the -x and -k options to load a certificate and private key.

agent-auth example usage

Example: Adding an agent with a hostname

# /var/ossec/bin/agent-auth -m -p 1515 -A example-agent
INFO: Connected to
INFO: Using agent name as: melancia
INFO: Send request to manager. Waiting for reply.
INFO: Received response with agent key
INFO: Valid key created. Finished.
INFO: Connection closed.

Example: Adding an agent and verifying the certificate presented by ossec-authd

# /var/ossec/bin/agent-auth -m ossec-manager.localdomain -p 1515 -v /etc/pki/CA/certs/internal_CA.cert
INFO: Connected to
INFO: Verifying manager's certificate
INFO: Using agent name as: melancia

Example: Adding an agent and presenting a certificate to ossec-authd

# /var/ossec/bin/agent-auth -m ossec-manager.localdomain -p 1515 -x /var/ossec/etc/client.cert -k /var/ossec/etc/client.key
INFO: Connected to
INFO: Using agent name as: melancia