Skip to content

Latest commit

 

History

History
210 lines (139 loc) · 6.43 KB

agent-management.rst

File metadata and controls

210 lines (139 loc) · 6.43 KB
Raw

Managing Agents

To add an agent to an OSPatrol manager with :ref:`manage_agents` you need to follow the steps below.

  1. Run manage_agents on the OSPatrol server.
  2. Add an agent.
  3. Extract the key for the agent.
  4. Copy that key to the agent.
  5. Run manage_agents on the agent.
  6. Import the key copied from the manager.
  7. Restart the manager's OSPatrol processes.
  8. Start the agent.

manage_agents on the OSPatrol server

The server version of manage_agents provides an interface to:

  • add an OSPatrol agent to the OSPatrol server
  • extract the key for an agent already added to the OSPatrol server
  • remove an agent from the OSPatrol server
  • list all agents already added to the OSPatrol server.

Running manage_agents and start screen

manage_agents should be run as a user with the appropriate privileges (e.g. root).

Run manage_agents:

# /var/ospatrol/bin/manage_agents

The manage_agents menu:

****************************************
* OSPatrol HIDS v2.5-SNP-100809 Agent manager.     *
* The following options are available: *
****************************************
   (A)dd an agent (A).
   (E)xtract key for an agent (E).
   (L)ist already added agents (L).
   (R)emove an agent (R).
   (Q)uit.
Choose your action: A,E,L,R or Q:

Typing the appropriate letter and hitting enter will initiate that function.

Adding an agent

To add an agent type a in the start screen:

Choose your action: A,E,L,R or Q: a

You are then prompted to provide a name for the new agent. This can be the hostname or another string to identify the system. In this example the agent name will be agent1.

- Adding a new agent (use '\q' to return to the main menu).
  Please provide the following:
   * A name for the new agent: agent1

After that you have to specify the IP address for the agent. This can either be a single IP address (e.g. 192.168.1.25), a range of IPs (e.g. 192.168.2.0/24), or any. Using a network range or any is preferable when the IP of the agent may change frequently (DHCP), or multiple systems will appear to come from the same IP address (NAT).

* The IP Address of the new agent: 192.168.2.0/24

Warning

If you use a specific IP address it must be unique. Duplicate IP addresses will cause issues. Multiple systems can use the same IP range or any.

The last information you will be asked for is the ID you want to assign to the agent. :ref:`manage_agents` will suggest a value for the ID. This value should be the lowest positive number that is not already assigned to another agent. The ID 000 is assigned to the OSPatrol server. To accept the suggestion, simply press ENTER. To choose another value, type it in and press ENTER.

* An ID for the new agent[001]:

As the final step in creating an agent, you have to confirm adding the agent:

After that :ref:`manage_agents` appends the agent information to /var/ospatrol/etc/client.keys and goes back to the start screen.

Warning

If this is the first agent added to this server, the server's OSPatrol processes should be restarted using /var/ospatrol/bin/ospatrol-control restart.

Extracting the key for an agent

After adding an agent, a key is created. This key must be copied to the agent. To extract the key, use the e option in the manage_agents start screen. You will be given a list of all agents on the server. To extract the key for an agent, simply type in the agent ID. It is important to note that you have to enter all digits of the ID.

Choose your action: A,E,L,R or Q: e

Available agents:
   ID: 001, Name: agent1, IP: 192.168.2.0/24
Provide the ID of the agent to extract the key (or '\q' to quit): 001

Agent key information for '001' is:
MDAyIGFnZW50MSAxOTIuMTY4LjIuMC8yNCBlNmY3N2RiMTdmMTJjZGRmZjg5YzA4ZDk5m

** Press ENTER to return to the main menu.

The key is encoded in the string (shortened for this example) MDAyIGFnZW50MSAxOTIuMTY4LjIuMC8yNCBlNmY3N2RiMTdmMTJjZGRmZjg5YzA4ZDk5Mm and includes information about the agent. This string can be added to the agent through the agent version of manage_agents.

Removing an agent

If you want to remove an OSPatrol agent from the server, use the r option in the :ref:`manage_agents` start screen. You will be given a list of all agents already added to the server. To remove an agent, simply type in the ID of the agent, press enter, and finally confirm the deletion. It is important to note that you have to enter all digits of the ID.

Choose your action: A,E,L,R or Q: e

Available agents:
   ID: 001, Name: agent1, IP: 192.168.2.0/24
Provide the ID of the agent to extract the key (or '\q' to quit): 001
Confirm deleting it?(y/n): y
Agent '001' removed.

manage_agents then invalidates the agent information in /var/ospatrol/etc/client.keys. Only the values for ID and the key are kept to avoid conflicts when adding agents. The deleted agent can no longer communicate with the OSPatrol server.

manage_agents on OSPatrol agents

The agent version provides an interface for importing authentication keys.

****************************************
* OSPatrol HIDS v2.5-SNP-100809 Agent manager.     *
* The following options are available: *
****************************************
   (I)mport key from the server (I).
   (Q)uit.
Choose your action: I or Q: i

* Provide the Key generated by the server.
* The best approach is to cut and paste it.
*** OBS: Do not include spaces or new lines.

Paste it here (or '\q' to quit): [key extracted via manage_agents on the server]

Agent information:
   ID:001
   Name:agent1
   IP Address:192.168.2.0/24

Confirm adding it?(y/n): y
Added.
** Press ENTER to return to the main menu.

For the changes to be in effect you have to restart the server and start the agent.