Orca Documentation

Orca Agents Guide

Agents & Servers

This guide will provide more detailed information on Orca Agents, their installation and configuration, and how to manage them within Orca.


Orca agents are supplied in platform appropriate installation files (rpm/deb for Linux, etc.). The agent installers will install the agent in a typical location for the platform which is usually /opt for Linux platforms, and C:\Program Files for Windows systems.
All agent installers must be run with root or administrator privileges as they will create system service definitions to run the agent as a service and doing so requires those privileges. The installers will run the agent service as root/Administrator by default. If you need to restrict the agent service to a specific user, you can do so by editing the appropriate service control files and specifying the user account there and restarting the service.

Orca agents depend on a correctly configured DNS system to communicate with the Orca App and if need be with the Orca Cloud Service. Currently Orca agents only support IPv4 but should function correctly on systems that have IPv6 enabled.

If you would like to install an Orca agent on a system that is not currently supported with an installer, an agent source kit is available to allow you to compile the agent on those systems. The source kit comes with a configure script to generate Makefiles for the system, although you may need to adjust the generated Makefile to properly link with the required libraries.

The Orca agent will compile, link, and run successfully with the following libraries: • OpenSSL 1.0.2t or newer • libCurl 7.65 or newer

The Orca agent also requires libz but should run correctly with any recent version of that standard library. Contact Orca Support to obtain the Agent Source Kit.

Agent Startup and Communication

When the Orca agent is first started either at installation time or upon a system reboot, it will attempt to register with Orca. To do this, it will send out a series of broadcast packets to port 13578 on the network and wait for a response from the Orca Desktop Application (Make sure the Desktop App is running when you install agents!) Once the agent receives a response from the Orca App, it will proceed to register itself with Orca, at which point you will see the server’s hostname appear in the Orca App.

The agent will query the OS hostname value and use that when registering with Orca. If the OS hostname value is not correct for your network, you can force the agent to use the correct hostname by editing the appropriate service control file for your platform and adding the

-H hostname

option to the agent startup. Restarting the agent service will re-run the registration process with that new hostname.

All agent communication is done via the Orca Desktop App. The App acts as a proxy to the Orca cloud service for your agents so the servers the agents run on only need to be able to connect to the system running the Orca Desktop App.

The following outline describes the process that occurs when Orca runs a job on an agent:

  1. The Desktop App connects to the agent on the server and passes it a job token.
  2. The agent connects to and authenticates with the Orca Service (via proxy through the App) to retrieve the job script and other controlling information.
  3. The agent will perform the job on the server and capture any log and configuration data.
  4. The agent connects to the Orca Service (again, via the App proxy) and uploads the job results.

Agent job connections are performed via HTTPS with an additional layer of authentication that occurs inside of that protocol.

Manually Defining an Agent

If your network restrictions prevent the normal broadcast process from succeeding you can define the agent server in Orca manually. To do this, install and configure the Orca agent service on the destination system as a first step. Once that’s complete and the agent service is running and listening on port 13579, you can create the server’s hostname in the Orca App.

In the Orca App select the system menu from the hamburger icon at the top right. In the menu that’s displayed, select the Global Server List entry. This pulls up a dialog that will list the servers known to Orca, who they are registered to, and also allow you to manually register an agent.

Select the link to register an agent and enter the hostname of the server where the agent is installed. Orca will attempt to connect to the agent on that server and give it the necessary connection information to properly register with Orca. If the connection from the App to the agent is successful, a success message will be displayed and the App will wait for the agent to register itself. This should happen within just a few seconds.

If while attempting the manual registration process the App indicates it cannot connect to the agent, you must verify:

  1. The hostname is correct and resolves to the correct IP address.
  2. The system the App is installed on can make outbound connections to the server in question.
  3. The agent service is running on the server and able to receive inbound connections on port 13579.

Once the App has connected to the agent and initiated the registration process, the server hostname will appear in the global server list. You can exit the registration dialog and scroll through the server list to verify that the server has successfully registered with Orca.

If after a successful registration request process you still don’t see the server in the list, you’ll need to verify:

  1. The server the agent is running on can make outbound connections to the server the App is running on.
  2. The hostname of the server the App is running on is correct and resolves to the correct IP address from the perspective of the server the agent is running on.
  3. The agent is able to make outbound HTTPS requests to the App’s proxy service on port 13578.

The Orca Agent must successfully connect and register with the Orca App before it can be assigned to targets. If you have unique network restrictions to work around, contact Orca support for assistance.

Server Ownership

Orca users own servers in Orca. Once a server is assigned to a user (by being associated with a target the user owns) the server cannot be used by any other users. The scripts that you run on servers can and likely will contain secure information that you don’t want exposed to other people, restricting server ownership enables that information to be protected. The configuration data post-inventory/promotion can be shared with other users via the Pod sharing settings.

A new server, prior to being assigned to a user, is listed as unassigned in the global server list. At this point any Orca user can assign the server to one of their targets and take ownership. If you find that your new agent properly registered but you can’t assign the server to any targets that just means someone else grabbed it. The user that did so will be listed in the global server list so you can contact them and get them to release your server.

Once you have removed a given server from all targets that you own, the server becomes available to any user again. You can use this to transfer control of a server to another Orca user. If you are decommissioning the server or no longer need it, you can delete the server’s entry from the global server list after it is no longer assigned to any targets. Keep in mind that if the agent remains installed on the server and the server is restarted, the agent will re-register itself and appear in the global server list once again. When decommissioning a server you should remove the agent from it prior to removing it from Orca. Servers with no owner that remain in the Orca server list for more than 30 days are automatically removed from Orca.