agent-auth

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

Warning

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

-D

Directory where OSSEC is installed. Default /var/ossec

-d

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.

-h

Display the help message

-k <path>

Full path to the agent key.

-m <manager_ip>

IP address of the manager.

-p <port>

Port ossec-authd is running on.

Default 1515

-V

Display OSSEC Version and license information.

-v <path>
Full path to the CA certificate used to verify the server.

Note

This option was added after 2.8.1.

-x <path>

Full path to the agent certificate.

Note

The following options are only necessary if verification of server or client certificates is desired. See Optional Server Authentication and Optional Client Authentication below.

Note

This option was added after 2.8.1.

-x </path/to/certificate>

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

Note

This option was added after 2.8.1.

-k </path/to/private_key>

Load the certificate’s corresponding PEM encoded private key.

Note

This option was added after 2.8.1.

-v </path/to/CA_certificate>

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.

Note

This option was added after 2.8.1.

Optional Server Authentication

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 192.168.1.1 -p 1515 -A example-agent
INFO: Connected to 192.168.1.1:1515
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 192.168.1.1:1515
INFO: Verifing 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 192.168.1.1:1515
INFO: Using agent name as: melancia
...