iBootbar Agent

The iBootbar Agent is an OCS Agent which monitors and sends commands to the iBoot PDU. Monitoring and commanding is performed via SNMP.

usage: python3 agent.py [-h] [--address ADDRESS] [--port PORT]
                        [--snmp-version {1,2,3}] [--mode {acq,test}]
                        [--lock-outlet LOCK_OUTLET [LOCK_OUTLET ...]]

Agent Options

--address

Address to listen to.

--port

Port to listen on.

Default: 161

--snmp-version

Possible choices: 1, 2, 3

SNMP version for communication. Must match configuration on the ibootbar.

Default: “2”

--mode

Possible choices: acq, test

Default: “acq”

--lock-outlet

List of outlets to lock on startup.

Configuration File Examples

Below are configuration examples for the ocs config file and for running the Agent in a docker container.

OCS Site Config

To configure the iBootbar Agent we need to add a ibootbarAgent block to our ocs configuration file. Here is an example configuration block using all of the available arguments:

{'agent-class': 'ibootbarAgent',
 'instance-id': 'ibootbar',
 'arguments': [['--address', '10.10.10.50'],
               ['--port', 161],
               ['--mode', 'acq'],
               ['--snmp-version', 2]]},

Note

The --address argument should be the address of the iBoot PDU on the network.

Docker Compose

The iBootbar Agent should be configured to run in a Docker container. An example docker-compose service configuration is shown here:

ocs-ibootbar:
  image: simonsobs/socs:latest
  hostname: ocs-docker
  network_mode: "host"
  volumes:
    - ${OCS_CONFIG_DIR}:/config:ro
  environment:
    - INSTANCE_ID=ibootbar
    - SITE_HUB=ws://127.0.0.1:8001/ws
    - SITE_HTTP=http://127.0.0.1:8001/call
    - LOGLEVEL=info

The LOGLEVEL environment variable can be used to set the log level for debugging. The default level is “info”.

Description

The iBootbar, or iBoot PDU, will be used to power various components on the SO site. The iBootbar Agent allows the monitoring and commanding of the iBoot PDU. It monitors the state of each outlet, can set the state of each outlet, can cycle each outlet, and reboot the system. The iBootbar has an Simple Network Management Protocol (SNMP) interface.

The iBootbar Agent actively issues SNMP GET commands to request the status from several Object Identifiers (OIDs) specified by the provided Management Information Base (MIB). We sample only a subset of the OIDs defined by the MIB. The MIB has been converted from the original .mib format to a .py format that is consumable via pysnmp and is provided by socs. The iBootbar Agent also contains three tasks: set_outlet, cycle_outlet, and set_initial_state. These tasks issues SNMP SET commands to change the value of OIDs, resulting in changing the state of outlets.

Agent Fields

The fields returned by the Agent are built from the SNMP GET responses from the iBoot PDU. The field names consist of the OID name and the last value of the OID, which often serves as an index for duplicate pieces of hardware that share a OID string, i.e. outlets on the OID “outletStatus”. This results in field names such as “outletStatus_0” and “outletStatus_1”.

These queries mostly return integers which map to some state. These integers get decoded into their corresponding string representations and stored in the OCS Agent Process’ session.data object. For more details on this structure, see the Agent API below. For information about the states corresponding to these values, refer to the MIB file.

Agent API

class socs.agents.ibootbar.agent.ibootbarAgent(agent, address, port=161, version=2, lock_outlet=None)[source]

Monitor the ibootbar system via SNMP.

Parameters:

agent (OCSAgent) – OCSAgent object which forms this Agent
address (str) – Address of the ibootbar.
port (int) – SNMP port to issue GETs to, default to 161.
version (int) – SNMP version for communication (1, 2, or 3), defaults to 2.
lock_outlet (list of ints) – List of outlets to lock on agent startup. Outlets are numbered 1-8.

agent

OCSAgent object which forms this Agent

Type:: OCSAgent

is_streaming

Tracks whether or not the agent is actively issuing SNMP GET commands to the ibootbar. Setting to false stops sending commands.

Type:: bool

log

txaio logger object, created by the OCSAgent

Type:: txaio.tx.Logger

acq()[source]

Process - Fetch values from the ibootbar via SNMP.

Notes

The most recent data collected is stored in session.data in the structure:

>>> response.session['data']
{'outletStatus_0':
    {'status': 1,
     'name': 'Outlet-1',
     'description': 'on'},
 'outletStatus_1':
    {'status': 0,
     'name': 'Outlet-2',
     'description': 'off'},
 ...
 'ibootbar_connection':
    {'last_attempt': 1656085022.680916,
     'connected': True},
 'timestamp': 1656085022.680916,
 'address': '10.10.10.50'}

set_outlet(outlet, state)[source]

Task - Set a particular outlet to on/off.

Parameters:

outlet (int) – Outlet number to set. Choices are 1-8 (physical outlets).
state (str) – State to set outlet to, which may be ‘on’ or ‘off’

cycle_outlet(outlet, cycle_time=10)[source]

Task - Cycle a particular outlet for given amount of seconds.

Parameters:

outlet (int) – Outlet number to cycle. Choices are 1-8 (physical outlets).
cycle_time (int) – The amount of seconds to cycle an outlet. Default is 10 seconds.

set_initial_state()[source]

Task - Set outlets to their initial states.

Performs a software reboot. The outlets are then set to their respective initial states. This takes about 30 seconds.

lock_outlet(outlet, lock)[source]

Task - Lock/unlocks a particular outlet, preventing change of state.

Parameters:

outlet (int) – Outlet number to lock/unlock. Choices are 1-8 (physical outlets).
lock (bool) – Set to true to lock, set to false to unlock

Example Clients

Below is an example client to control outlets:

from ocs.ocs_client import OCSClient
client = OCSClient('ibootbar')

# Turn outlet on/off
client.set_outlet(outlet=1, state='off')
client.set_outlet(outlet=1, state='on')

# Cycle outlet for 10 seconds
client.cycle_outlet(outlet=1, cycle_time=10)

# Set outlets to their initial states
client.set_initial_state()

Supporting APIs

class socs.agents.ibootbar.agent.update_cache(get_result, names, outlet_locked, timestamp)[source]

Update the OID Value Cache.

The OID Value Cache is used to store each unique OID and will be passed to session.data

The cache consists of a dictionary, with the unique OIDs as keys, and another dictionary as the value. Each of these nested dictionaries contains the OID values, name, and description (decoded string). An example for a single OID, with connection status and timestamp information:

{"outletStatus_0": {"status": 1,
                    "name": Outlet-1,
                    "description": "on"},
 "ibootbar_connection": {"last_attempt": 1598543359.6326838,
                         "connected": True},
 "timestamp": 1656085022.680916}

Parameters:

get_result (pysnmp.smi.rfc1902.ObjectType) – Result from a pysnmp GET command.
names (list) – List of strings for outlet names
outlet_locked (list of bool) – List of bool for outlets (1-8) that are locked
timestamp (float) – Timestamp for when the SNMP GET was issued.