Orca Documentation

Getting Started Guide

Getting Started With Orca

This guide provides an overview of Orca, its terminology, and general concepts. Understanding these basic concepts will help you get started with Orca quickly and give you the foundation to start using more advanced features and capabilities within Orca. Orca provides specific help callouts within the Orca Desktop Application to give you more detailed information. There are also other guides like this one on specific topics that you’ll want to get more detail on.


Pods in Orca are an organizational entity. Pods simply provide a means to group together related things that you’ll be managing with Orca. What you put in a Pod is up to you. You can group together systems by purpose, location, or just use a Pod as a catchall bucket and fill it with whatever type of data you want.

Pods are also the shared entities in Orca. When you share a Pod with other users, those users can reference the configuration data you’ve collected in those pods in their own comparisons. They cannot view target specifics, only compare against the active config data on those targets.


Targets in Orca define what configuration data you’re collecting. A Target has a data collection interface associated with it, as well as one or more servers. This interface collects a specific type of configuration information from the target’s associated servers in a process called an inventory. Targets are also where you view status and log information on inventories. Targets operate in two basic phases, data collection followed by data promotion. When you inventory a target you collect data from the associated servers. If the inventory jobs are successful and the data collected is good, the configuration state is promoted to the latest active for the target. The active configuration data on a target is what is used by Comparison Sets to generate drift reports. Inventory jobs can be cancelled manually from within the Orca App, or will be cancelled automatically if they run longer than 30 minutes.

Servers associated with targets are presumed to be identical. If there are multiple servers on a target, an inventory job will be run on each of them. When the jobs are complete, Orca will compare the data amongst the servers to ensure there are no differences. If differences are found, the configuration data will NOT be promoted to the active state, but a drift report will be created so you can view the differences and the servers that are out of sync. All of the servers on a given target must be in sync before the data will be promoted and thus be available for use in comparison to other targets via comparison sets you’ve created.

NOTE: Scheduled inventories and email alerts are run from and managed by the Orca Desktop Application. The Orca Application must be running in order for these to function!


In Orca, a server is probably exactly what you’d expect, a physical or virtual server on which you’ll install an Orca Agent. Orca Agents are lightweight services that Orca uses to inventory configuration information from the server. Once an agent has been installed on a server, it will appear in Orca and you can associate it with one or more targets.


In some cases, the inventory scripts Orca runs on servers will need authentication credentials to access the files and services necessary to return the desired configuration data. It’s likely that these credentials are common across groups of servers and are changed fairly often. Credentials allow you to
store username/password information in Orca in a single location and then have any inventory scripts reference those credentials at runtime.

Comparison Sets and Snapshots

Comparison sets in Orca are how you view configuration drift between targets. Whenever Orca compares sets of configuration data, a Comparison Set Snapshot is created. Some snapshots are created automatically, for instance when a target promotes configuration data that’s changed, a snapshot is automatically created for you on any comparison set that the target is associated with. You can also generate your own snapshots manually. Snapshots will report on all of the sources involved, and will list the specific changes detected between the sources. If a target state changes to where it cannot be used (failed inventory, bad config data) or if a target is removed from a comparison set (target deleted, shared target unshared) then the comparison set will be put in a Frozen state and will not be re-run if one of the other currently valid targets is updated. Comparison sets in a frozen state can be un-frozen by running them manually or will be automatically un-frozen when the target at issue is stable again.


In Orca an interface is a logical name for a set of shell scripts that are platform specific. An interface lets you define the type of configuration data you want to collect (system services, for example) and to collect it from multiple platforms in a single target.


These are the platform specific shell scripts that Orca will send to the server and use to collect configuration data. Each interface can have a number of platform specific shell scripts associated with it. When a target is inventoried, Orca will scan the list of associated servers and select the appropriate script to run on each one. Refer to the Scripts help document for more detailed information on scripts.


Parameters in Orca are probably just what you expect – variables you define that are referenced in the scripts used to inventory configuration data. You can define parameters in several places in Orca allowing you to create high-level generic parameters or server specific parameters. Parameter values are passed as environment variables for scripts. If your parameters have special characters interpreted by the shell in use, you must quote them appropriately. When determining the final parameter value to use in a script, Server parameters take precedence over Target parameters. You can assign default Target/Server parameters to interfaces and scripts, Interface parameters will be copied to the Target when created, and Script parameters will be copied to the Server when added to a target.


Tokens in Orca are used to mask out pieces of configuration data that you don’t want to influence drift comparisons in some way. Typically you’d use tokenization patterns to mask a server’s IP address with a generic term, like SERVER_ADDRESS so that when multiple servers are compared to each other you won’t create a false positive. It’s normal and expected for the server IP address to be different in that case. Tokens use a regular expression to match configuration data as it comes into Orca and replace the matched portion with a token value. When token replacement patterns are applied to incoming configuration data, a pattern match and token substitution causes the original value to be stored as a parameter on the server the data came from. This allows you to “dereference” the token should the need arise.

SMTP Configuration

In order for Orca to be able to send email (for alerts and emailing drift reports) you must configure the connection information for your SMTP server. To set these values you must ssh into your Orca cloud server and at the command line, issue the following commands to set the appropriate values:

./orca sysprop set smtp_server <smtp_server_hostname>

./orca sysprop set smtp_username <smtp_server_authentication_login>

./orca sysprop set smtp_password <smtp_server_authentication_password>

You can verify the values were set properly by issuing the command:

./orca sysprop list

You can also specify a custom SMTP server port (default is 587) by setting the ‘smtp_port’ property as per above. The Orca Cloud Service sends SMTP emails and must be allowed to connect to the SMTP server if it is inside your corporate network. Messaging alerts (Slack, Discord, etc.) do not require any special configuration.


By default Orca service instances are set to UTC. Most time values should display properly in the Desktop App, but reports generated by the Orca service will show UTC times unless you set the time zone on the service. Refer to the OS documentation for specific instructions on setting the time zone for your service. The default OS for Orca services on Amazon is Amazon Linux 2. Once you’ve set the time zone on the Orca service, you can reboot the server or restart the orca-service system daemon for the change to be propagated to Orca.