commands

package
v1.12.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 15, 2024 License: MIT Imports: 16 Imported by: 0

README

commands Package

The commands package provides a Go interface to the Geneos Gateway REST Command API.

Gateway documentation for the REST Commands

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

Documentation

Overview

Package commands wraps the Geneos Gateway REST Command API in Go

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

Index

Constants

View Source 
const (
	None = iota
	Basic
	SSO
)

Authentication types. SSO is not currently implemented.

Variables

This section is empty.

Functions

func AuthBasic 

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

AuthBasic sets up HTTP Basic Authentication on client c using the plaintext username and password pw. The password is a config.Plaintext enclave

func AuthSSO 

func AuthSSO()

AuthSSO is a placeholder for future SSO authentication

Types

type Args 

type Args func(*CommandArgs)

Args is an option type used to add positional arguments to Geneos commands called via the REST API

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. e.g.

fn(..., Arg(1, "value"), Arg(5, "string"))

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           *config.Plaintext
	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)

DialGateway connects 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)

DialGateways connects 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)

LastSampleInfo calls the internal command of the same name and returns a slice of CommandResponse types, one for each matching data item, on the connection c. While errors from the Gateway are returned in the CommandResponse structures, if there is an error connecting or running the command then that is returned in err

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 value. 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)

RunCommandAll 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)

SampleNow calls the internal command of the same name on the connection c and against the target XPath. An error is returned on failure to run the command.

func (*Connection) Snapshot 

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

Snapshot fetches the contents of the dataview identified by the target XPath. The target must match exactly one dataview. Only headline and cell values are requested unless an optional scope is passed, which can 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 existing releases the first column name is not exported and is set to rowname, which defaults to the literal "rowname" if passed an empty rowname.

func (*Connection) SnoozeInfo 

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

SnoozeInfo runs the internal command of the same name

func (*Connection) SnoozeManual 

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

SnoozeManual runs the internal command of the same name

func (*Connection) Unsnooze 

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

Unsnooze runs the internal command of the same name

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"`
	Snoozed          bool         `json:"snoozed"`
	SnoozedAncestors bool         `json:"snoozed-ancestors"`

	// Headlines is a map of headline names to data items
	Headlines map[string]DataItem `json:"headlines,omitempty"`

	// Table is a map of row names to column names to data items, the
	// first column (row name) not included in the map. A specific
	// DataItem is Table["row"]["column"].
	Table map[string]map[string]DataItem `json:"table,omitempty"`

	// HeadlineOrder, ColumnOrder and RowOrder are slice of the
	// respective names based on the order in the Gateway REST response
	//
	// While JSON does not support fixed orders for objects, the Geneos
	// Gateway responds with the "natural" (i.e. internal) order for
	// these object maps
	HeadlineOrder []string `json:"-"`
	ColumnOrder   []string `json:"-"`
	RowOrder      []string `json:"-"`
}

Dataview represents the contents of a Geneos dataview as returned by commands.Snapshot. Name and XPath are populated from the request to Snapshot while the three "Order" slices are constructed from the order of the received JSON data.

func (*Dataview) UnmarshalJSON added in v1.11.2 

func (dv *Dataview) UnmarshalJSON(d []byte) (err error)

UnmarshalJSON preserves the order of the Headline, Rows and Columns from a snapshot in dv Order fields. If the input is empty an os.ErrInvalid is returned as an empty Dataview object should not be used.

type GeneosRESTError 

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

GeneosRESTError is the error returned from the REST API

type Options 

type Options func(*Connection)

Options is an option type used for commands functions

func AllowInsecureCertificates 

func AllowInsecureCertificates(opt bool) Options

AllowInsecureCertificates allows unverified connections over TLS to the gateway

func Ping 

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

Ping overrides the built-in ping() function used to test the availability of the gateway when used with DialGateways() and Redial()

func SetBasicAuth 

func SetBasicAuth(username string, password *config.Plaintext) Options

SetBasicAuth configures basic authentication on the connection, given a username and password (both as plain strings)

func Timeout 

func Timeout(timeout time.Duration) Options

Timeout sets the timeout of the REST connection as a time.Duration

type SSOAuth 

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

SSOAuth is a placeholder struct for SSO authentication in the command Connection struct

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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.