There are several ways to configure agents:


1. Passing specific command line arguments upon agent initiation


The following table shows the agent command line arguments:


Command Line Parameter
Description
-name
Unique name for the agent
-host
OperetoBox host address
-u
Opereto username
-p
Opereto password.
It is recommended to put the password string in single quotes as some special characters (e.g. @) may be deleted by the shell and as a result, agent authentication will fail.
-log
[optional] – location of log file. Default: .opereto/log. [-log console] will output to console only.
-loglevel
[optional] – log level [info, warn, error, debug, fatal]. The default is info.
-agent.lock.port
[optional] – agent lock port to ensure only one agent instance on the host. The default is 53945.
-XX:MinHeapFreeRatio
-XX:MaxHeapFreeRatio
Java internal flags to control heap expansion and shrinking.
-Xms
-Xmx
Java internal flags: Xmx specifies the maximum memory allocation pool for a Java Virtual Machine (JVM), while Xms specifies the initial memory allocation pool.
-polling.frequency
Overrides the default agent polling frequency (e.g. the interval of the requests for new processes from the server (in seconds, default is 5 seconds)



2. Modifying agent name and description


The agent name provided in the execution command line is the agent unique identifier and cannot be changed. However, one may add a name and a short description to any given agent. If a name is provided, it will become the display name of the agent.


3. Modifying agent properties


Agents may have one or more properties, key-value parameters used for classification. Some built-in properties are added automatically by Opereto agent such as:

  • system.arch (e.g. amd64)
  • hostname
  • agent.home (the current agent home directory)
  • total.space, free.space etc..

Also, the user may specify and modify additional properties per agent to improve agent classification. For instance, a web server with Python installed may include the following user defined properties:
  • web_server: true
  • python: 2.7.5

Agent properties are very powerful tools to map specific agents to services. Please check out the service agents mapping section to learn more.


Special user-defined agent properties


Opereto uses several special agent properties as configuration directives as shown in the following table:

 

Property
Description
opereto.termination_protection
Opereto removes agents from the system if not connected for a given period (20 minutes by default). Specifying this agent property protects a given agent from being automatically deleted from the system. The proper usage of this property is as follows:    
opereto.termination_protection: true 

  
  
opereto.shared
This flag indicates that a given agent serves as a shared execution worker. This option is useful if you want to build and share common services that are automatically mapped to run on execution workers w/o giving any explicit permissions to use those workers. In practical terms it means that opereto users that are not opereto administrators and do not have an explicit permission will not "see" those worker agents in UI or API queries or be able to select those agents explicitly when running other services. Still, they will be able to run automation services that are mapped to run on those agents.
opereto.shared: true




Agent properties specified by automation services


Automation service developers may explicitly add/remove properties from the agent running them. This is mainly useful to manage a configuration state of that agent the same as other configuration management tools do. If a given service installs a library on the agent hosts that other services use, it may add a property indicating that the library is installed. Some services included in Opereto's packages implement this approach. For example, the service install_opereto_worker_libs included in the Opereto Core Services package adds the agent the property: opereto.worker: true after installing opereto's worker libs. The service remove_opereto_worker_libs modifies that property to opereto.worker: false.



4. Modifying agent permissions

Agents have two types of permissions: users and owners as follows:

Users
  • May run services on this agent
  • "See" the agent in the agents grid in the UI
Owners
  • Same as Users
  • Owners may modify the agent configuration (name, desc, properties, permissions..)
  • Owners may delete the agent (unless opereto.termination_protection: true is specified. In this case, it will have to be removed prior to deleting the agent)



Example 1: configuring the agent via UI




Example 2: configuring the agent via API (using pyopereto)


## create the client object
client = OperetoClient()
agent_id = 'linux-agent'

## modify agent information and permissions
client.modify_agent(agent_id, name='Worker #1', description='The agent is used as a worker agent', permissions={'users': [], 'owners': ['dror']})

## modify agent property
client.modify_agent_property(agent_id, 'opereto.worker', True)