commands

README

Geneos Commands

This package provides access to Geneos commands in the Gateway via the REST interface.

Gateway documentation is here

REST commands must be enabled in the Gateway configuration under the top level Commands section Advanced tab.

Documentation

Overview

Support for Geneos Gateway REST Commands

Based on https://docs.itrsgroup.com/docs/geneos/current/Gateway_Reference_Guide/geneos_commands_tr.html#REST_Service

Index

• Constants
• func AuthBasic(c *http.Request, username, password string) (err error)
• func AuthSSO()
• type Args
  • func Arg(index int, value string) Args
• type Command
• type CommandArgs
• type CommandResponse
• type CommandResponseRaw
• type Connection
  • func DialGateway(u *url.URL, options ...Options) (c *Connection, err error)
  • func DialGateways(urls []*url.URL, options ...Options) (c *Connection, err error)
  • func (c *Connection) CommandTargets(command string, target *xpath.XPath) (matches []*xpath.XPath, err error)
  • func (c *Connection) Do(endpoint string, command *Command) (response CommandResponse, err error)
  • func (c *Connection) LastSampleInfo(target *xpath.XPath) (crs []CommandResponse, err error)
  • func (c *Connection) Match(target *xpath.XPath, limit int) (matches []*xpath.XPath, err error)
  • func (c *Connection) Redial() (err error)
  • func (c *Connection) RunCommand(command string, target *xpath.XPath, args ...Args) (response CommandResponse, err error)
  • func (c *Connection) RunCommandAll(command string, target *xpath.XPath, args ...Args) (responses []CommandResponse, err error)
  • func (c *Connection) SampleNow(target *xpath.XPath) (err error)
  • func (c *Connection) Snapshot(target *xpath.XPath, scope ...Scope) (dataview *Dataview, err error)
  • func (c *Connection) SnoozeInfo(target *xpath.XPath) (crs []CommandResponse, err error)
  • func (c *Connection) SnoozeManual(target *xpath.XPath, info string) (err error)
  • func (c *Connection) Unsnooze(target *xpath.XPath, info string) (err error)
• type DataItem
• type Dataview
• type GeneosRESTError
• type Options
  • func AllowInsecureCertificates(opt bool) Options
  • func Ping(ping func(*Connection) error) Options
  • func SetBasicAuth(username, password string) Options
  • func Timeout(timeout time.Duration) Options
• type SSOAuth
• type Scope

Constants

const (
	None = iota
	Basic
	SSO
)

Authentication types. SSO is not currently implemented.

Functions

func AuthBasic

func AuthBasic(c *http.Request, username, password string) (err error)

func AuthSSO

func AuthSSO()

try to authentication using SSO

Types

type Args

type Args func(*CommandArgs)

func Arg

func Arg(index int, value string) Args

Arg is a positional argument passed to a Geneos REST command. Use multiple Arg() options to [RunCommand] or [RunCommandAll] to set the required values.

type Command

type Command struct {
	Name   string       `json:"command,omitempty"`
	Target *xpath.XPath `json:"target"`
	Args   *CommandArgs `json:"args,omitempty"`
	Scope  Scope        `json:"scope,omitempty"`
	Limit  int          `json:"limit,omitempty"`
}

Command is the wrapper for a Geneos REST Command

type CommandArgs

type CommandArgs map[string]string

CommandArgs is a map of argument indices to values

type CommandResponse

type CommandResponse struct {
	Target         *xpath.XPath      `json:"target"`
	MimeType       map[string]string `json:"mimetype"`
	Status         string            `json:"status"`
	Stdout         string            `json:"stdout"`
	StdoutMimeType string            `json:"stdout_mimetype"`
	Stderr         string            `json:"stderr"`
	ExecLog        string            `json:"execLog"`
	Dataview       *Dataview         `json:"dataview"` // for snapshots only
	XPaths         []string          `json:"xpaths"`
}

A CommandResponse holds the response from a REST command. The fields with values will depends on the command called.

type CommandResponseRaw

type CommandResponseRaw struct {
	Target     *xpath.XPath        `json:"target"`
	MimeType   []map[string]string `json:"mimetype"`
	Status     string              `json:"status"`
	StreamData []map[string]string `json:"streamdata"`
	Dataview   *Dataview           `json:"dataview"` // for snapshots only
	XPaths     []string            `json:"xpaths"`
}

A CommandResponseRaw holds the raw response to a REST command. In general callers will only receive and use CommandResponse

type Connection

type Connection struct {
	BaseURL            *url.URL
	AuthType           int
	Username           string
	Password           string
	SSO                SSOAuth
	InsecureSkipVerify bool
	Timeout            time.Duration
	// contains filtered or unexported fields
}

A Connection defines the REST command connection details to a Geneos Gateway.

func DialGateway

func DialGateway(u *url.URL, options ...Options) (c *Connection, err error)

Connect to a Geneos gateway on the given URL and check the connection. The connection is checked by trying a lightweight REST command (fetch gateway timezone and time) and if an error is returned then the connection should not be reused.

Options can be given to set authentication, ignore unverifiable certificates and to override the default "ping" to check the gateway connection

func DialGateways

func DialGateways(urls []*url.URL, options ...Options) (c *Connection, err error)

Connect to a Geneos gateway given a slice of URLs. This is to support standby pairs. Each URL is checked in a random order and the first working one is returned. If all URLs fail the check then an error is returned.

Options are the same as for DialGateway()

func (*Connection) CommandTargets

func (c *Connection) CommandTargets(command string, target *xpath.XPath) (matches []*xpath.XPath, err error)

CommandTargets returns a slice of all XPaths that support the command for the given target.

func (*Connection) Do

func (c *Connection) Do(endpoint string, command *Command) (response CommandResponse, err error)

Do executes command on the REST endpoint, return the http response

func (*Connection) LastSampleInfo

func (c *Connection) LastSampleInfo(target *xpath.XPath) (crs []CommandResponse, err error)

func (*Connection) Match

func (c *Connection) Match(target *xpath.XPath, limit int) (matches []*xpath.XPath, err error)

Match returns a slice of all matching XPaths for the target up to limit items. If limit is 0 then first a match is tried with the default limit of 100 and if that fails with an error hinting at the approximate number of matches, then retry with twice this vaule. If limit is less than 0 then the default limit of 100 is used.

func (*Connection) Redial

func (c *Connection) Redial() (err error)

Redial the connection, finding the next working endpoint using either the default ping function or the one provided when the connection was originally dialled.

An aggregated error is returned if all endpoints fail the connection test.

func (*Connection) RunCommand

func (c *Connection) RunCommand(command string, target *xpath.XPath, args ...Args) (response CommandResponse, err error)

RunCommand runs command against exactly one target, returning the response

func (*Connection) RunCommandAll

func (c *Connection) RunCommandAll(command string, target *xpath.XPath, args ...Args) (responses []CommandResponse, err error)

RunCommands runs command against all matching data items, returning separately concatenated stdout, stderr and execlog when returned by the underlying command

func (*Connection) SampleNow

func (c *Connection) SampleNow(target *xpath.XPath) (err error)

func (*Connection) Snapshot

func (c *Connection) Snapshot(target *xpath.XPath, scope ...Scope) (dataview *Dataview, err error)

Snapshot fetches the contents of the dataview identified by the target. Only values are fetched unless an optional scope is passed, which can then request severity, snooze and user assignment information. If the underlying REST call fails then the error is returned along with any Stderr output.

Snapshot support is only available in Geneos GA5.14 and above Gateways and requires the REST command API to be enabled.

In GA5.14.x the first column name is not exported and is set to "rowname"

func (*Connection) SnoozeInfo

func (c *Connection) SnoozeInfo(target *xpath.XPath) (crs []CommandResponse, err error)

func (*Connection) SnoozeManual

func (c *Connection) SnoozeManual(target *xpath.XPath, info string) (err error)

func (*Connection) Unsnooze

func (c *Connection) Unsnooze(target *xpath.XPath, info string) (err error)

type DataItem

type DataItem struct {
	Value    string `json:"value,omitempty"`
	Severity string `json:"severity,omitempty"`
	Snoozed  bool   `json:"snoozed,omitempty"`
	Assigned bool   `json:"assigned,omitempty"`
}

DataItem is a Geneos data item and normally represents a headline or table cell.

type Dataview

type Dataview struct {
	Name             string                         `json:"name"`
	XPath            *xpath.XPath                   `json:"xpath"`
	SampleTime       time.Time                      `json:"sample-time,omitempty"`
	Snoozed          bool                           `json:"snoozed,omitempty"`
	SnoozedAncestors bool                           `json:"snoozed-ancestors,omitempty"`
	Headlines        map[string]DataItem            `json:"headlines,omitempty"`
	Table            map[string]map[string]DataItem `json:"table,omitempty"`
	Columns          []string                       `json:"-"`
}

Dataview represents the contents of a Geneos dataview as returned by [Snapshot]. The Columns field is an ordered slice of column names obtained from the ordered JSON data returned from the REST endpoint to allow the Table field to be iterated over in the same order as the Geneos dataview table.

type GeneosRESTError

type GeneosRESTError struct {
	Error string `json:"error"`
}

type Options

type Options func(*Connection)

func AllowInsecureCertificates

func AllowInsecureCertificates(opt bool) Options

allow unverified connections over TLS to the gateway

func Ping

func Ping(ping func(*Connection) error) Options

override the ping() function used to test the availability of the gateway when used with DialGateways() and Redial()

func SetBasicAuth

func SetBasicAuth(username, password string) Options

configure basic authentication on the connection, given a username and password

func Timeout

func Timeout(timeout time.Duration) Options

type SSOAuth

type SSOAuth struct {
	AccessToken string `json:"access_token,omitempty"`
	Expires     int64  `json:"expires,omitempty"`
	TokenType   string `json:"token_type,omitempty"`
}

type Scope

type Scope struct {
	Value          bool `json:"value,omitempty"`
	Severity       bool `json:"severity,omitempty"`
	Snooze         bool `json:"snooze,omitempty"`
	UserAssignment bool `json:"user-assignment,omitempty"`
}

A Scope selects which properties the REST dataview snaptshot command returns.