Hub Agent#

Cegal Hub Agent runs as a stand-alone binary and is generally run in agent mode when connecting to a remote Cegal Hub Server.

The main functionality of Cegal Hub Agent is to

  • Bootstrap applications on demand from wellknown application profiles

  • Launch scripts from a wellknown script location when the agent starts up

  • List files available locally to the agent

Running a Hub Agent#

A Hub Agent establishes a connection with a Hub Server and awaits requests and tasks. This can be to launch an application, execute a script or to list files. When starting the Hub Agent the address for the Hub Server and the port number needs to be supplied. The port number for a Hub Server running locally is usually 9595. For a Hub Server running on a remote network it is recommend to use tls for communication and the standard port number 443. The connection details for a remote connection can be set in the configuration of the Hub installation. You can then use the flag -remote to establish the connection without having to supply the Hub Server address and port number every time.

By default the launching of applications, executing scripts and list files is disabled. This needs to be explicitly allowed when starting the Hub Agent. This is done with the flags –allow-launch-profiles, –allow-scripts and –allow-file-list.

Executing scripts with a Hub Agent#

Cegal Hub Agent has the ability to launch scripts when the Cegal Hub Agent starts up.

To add a PowerShell script to be bootstrapped simply add the script to the wellknown scripts folder in the installation. The scipts folder is found at “C:\Users\<username>\AppData\Local\Cegal\Hub\scripts” on Windows.

../../../_images/hub_installation_dir.png

The first time Hub detects a script it will create a companion file with the same name as the script.

../../../_images/hub_installation_scripts_dir.png

The companion file is a simple json file with true or false values that the Cegal Hub Agent will respect when launching the script. The file can be updated manually to adjust the behavior as necessary.

../../../_images/hub_installation_scripts_companion_file.png

  • AutoLaunch - whether the script will be automatically launched when the Hub Agent –allow-launch-profiles

  • Monitor - whether any stdout or stderror from the script will be logged by the Hub Agent

  • Restart - whether to automatically restart the script if the Hub Agent detects it has exited

  • SetWellknownEnvVariables - whether to make all environment variables available to the script

Setting up application profiles#

Cegal Hub Agent has the ability to launch application profiles. This can be achieved on demand through a Cegal Hub client application which invokes the launch application functionality on a Cegal Hub Agent. The Cegal Hub Client CLI and Cegal Hub Python library support this functionality.

You can set up application profiles in the folder “C:\Users\<username>\AppData\Local\Cegal\Hub\apps”. The application profiles are in json format and require the ‘path’ to the executable, the arguments ‘Args’ to initialize the application with, and the maximum number of instances. Hub comes with a Petrel application profile included. As Cegal Hub is application agnostic you can launch any application.

../../../_images/hub_installation_apps.png

A Petrel application profile is included in the Hub installation. The application profile files are also a json file.

../../../_images/hub_installation_apps_petrel_profile.png

The format of the application profile json is standardized and generalized. Custom profiles may be added.

Restricting Hub Agent functionality in a remote Setting#

When starting a Cegal Hub Agent in stand-alone mode the assumption is that it is connecting to a remote Hub Server. In this scenario we adhere to a principle of least privilege.

By default the agent:

  • cannot launch scripts on startup

  • cannot launch application profiles on demand

  • cannot list files visible to the agent

To enable this functionality the agent needs to be explicitly passed the appropriate flags when it is launched.

cegalhub agent --allow-scripts --allow-launch-profiles --allow-file-list

The output from launching the Hub Agent indicates that the ability to launch scripts, launch application profiles and allow file list has been enabled.

../../../_images/hub_agent_allow_flags.png

Settting up a remote configuration#

To save typing connection details such as the host, port and TLS settings when connecting a Hub Agent to a remote Hub Server it is possible to configure and persist a remote profile.

This remote configuration can be specified when launching a Cegal Hub Agent

See Hub commandline for information on setting up a remote configuration.

cegalhub agent --remote

The output from launching the Hub Agent shows that the remote configuration is being used.

../../../_images/hub_agent_remote.png

Making a Hub Agent tenant-public#

Connector applications such as the Cegal Hub Agent have the possibility to allow other users in your tenant to perform actions on the connector.

By default this is disabled.

To enable this behaviour the allow-public flag must be passed when the agent is launched

cegalhub agent --allow-public

The output from launching the Hub Agent indicates that the ability allow other tenant users to perform actions on the Hub Agent is enabled.

../../../_images/hub_agent_allow_public.png