session

Documentation

Index

• Variables
• type Credentials
• type CredentialsRetriever
• type Provider
  • func NewCredentialsProvider(r CredentialsRetriever) Provider

Variables

var (
	// ErrCredentialNotFound is returned when a CredentialsRetriever can
	// confidently say it does not know of the BMC, or has no credentials for
	// it. This is provided for convenience; no branching is done based on this
	// value being returned.
	ErrCredentialNotFound = errors.New("no credential found for addr")
)

Types

type Credentials

type Credentials struct {

	// Username is the username of the user to connect as. Only ASCII characters
	// (excluding \0) are allowed, and it cannot be more than 16 characters
	// long.
	Username string

	// Password is the password of the above user, stored on the managed system
	// as either 16 bytes (to preserve the ability to log in with a v1.5
	// session) or 20 bytes of uninterpreted data (hence why this isn't a
	// string). Passwords shorter than the maximum length are padded with 0x00.
	// This is called K_[UID] in the spec ("the key for the user with ID
	// 'UID'").
	Password []byte
}

Credentials represents a username and password pair, giving access to a BMC.

type CredentialsRetriever

type CredentialsRetriever interface {

	// Credentials returns the username and password for the BMC at the supplied
	// address. This could be as simple as a map lookup, or it could query a
	// database or remote service.
	Credentials(ctx context.Context, addr string) (*Credentials, error)
}

CredentialsRetriever is implemented by things that can find the username and password for a BMC. This is usually all that is necessary to establish a session, and is slightly simpler to implement than Provider. If you have one of these, you can use NewCredentialsProvider() to turn it into a Provider.

type Provider

type Provider interface {

	// Session opens a new session with the BMC at the supplied address,
	// returning it and a closer for the underlying transport. This is the raw
	// "target" string given to us by Prometheus, so in theory it could be
	// anything, but for the sake of compatibility, it is recommended for this
	// to be the bare IP address, possibly with a port number on the end. This
	// method should return an error if the context expires, the addr is not
	// known, or session establishment fails. The returned session and closer
	// must be nil if the error is non-nil. The exporter will print all errors
	// received, with the requested addr, so it is not necessary to include this
	// in the error string.
	//
	// The exporter will call this method a maximum of once per scrape. We
	// assume currently unknown BMCs will be known at some point in the future.
	// It is recommended for implementations to retry their credential retrieval
	// logic as makes sense (e.g. perhaps not for a local file, but definitely
	// for a remote service), and to retry session creation. The caller of this
	// method does not itself retry as this allows implementations to retry more
	// efficiently, e.g. by reusing data common between retries. We can also
	// provide abstractions to retry session creation if necessary, making that
	// part easy. Essentially, it comes down to flexibility.
	//
	// For the sake of performance, this function must be safe for unbounded
	// concurrent use, with the guarantee that it will never be called
	// concurrently for a given addr value. The exporter will also endeavour to
	// close an addr's session before calling this method to obtain a new one.
	// As a BMC may choose to terminate a session at any time, or it may
	// timeout, this method must be safe for use throughout the exporter's
	// lifetime (not just during startup or once per addr).
	//
	// It is strongly recommended for implementations to support hot reloading,
	// to allow BMCs to be added and removed without having to restart the
	// exporter.
	Session(ctx context.Context, addr string) (bmc.Session, io.Closer, error)
}

Provider is implemented by things that can establish a session with BMCs. This exists to abstract the rest of the exporter away from IPMI versions, secrets and algorithms.

func NewCredentialsProvider

func NewCredentialsProvider(r CredentialsRetriever) Provider

NewCredentialsProvider creates a provider from a CredentialsRetriever.