client

README

SCADA Client

This library provides a Golang client for the HashiCorp SCADA service. SCADA stands for Supervisory Control And Data Acquisition, and as the name implies it allows Atlas to provide control functions and request data from the tools that integrate.

The technical details about how SCADA works are fairly simple. Clients first open a connection to the SCADA service at scada.hashicorp.com on port 7223. This connection is secured by TLS, allowing clients to verify the identity of the servers and to encrypt all communications. Once connected, a handshake is performed where a client provides it's Atlas API credentials so that Atlas can verify the client identity. Once complete, clients keep the connection open in an idle state waiting for commands to be received. Commands map to APIs exposed by the product, and are subject to any ACLs, authentication or authorization mechanisms of the client.

This library is used in various HashiCorp products to integrate with the SCADA system.

Environmental Variables

This library respects the following environment variables:

• ATLAS_TOKEN: The Atlas token to use for authentication
• SCADA_ENDPOINT: Overrides the default SCADA endpoint

Documentation

Index

• Constants
• type CapabilityProvider
• type Client
  • func Dial(addr string) (*Client, error)
  • func DialOpts(opts *Opts) (*Client, error)
  • func DialTLS(addr string, tlsConf *tls.Config) (*Client, error)
  • func (c *Client) Accept() (net.Conn, error)
  • func (c *Client) Addr() net.Addr
  • func (c *Client) Close() error
  • func (c *Client) NumStreams() int
  • func (c *Client) Open() (net.Conn, error)
  • func (c *Client) RPC(method string, args interface{}, resp interface{}) error
• type ConnectRequest
• type ConnectResponse
• type DisconnectRequest
• type DisconnectResponse
• type FlashRequest
• type FlashResponse
• type HandshakeRequest
• type HandshakeResponse
• type HijackFunc
• type Opts
• type Provider
  • func NewProvider(config *ProviderConfig) (*Provider, error)
  • func (p *Provider) IsShutdown() bool
  • func (p *Provider) SessionAuthenticated() bool
  • func (p *Provider) SessionID() string
  • func (p *Provider) Shutdown()
• type ProviderConfig
• type ProviderService

Constants

const (
	// DefaultEndpoint is the endpoint used if none is provided
	DefaultEndpoint = "scada.hashicorp.com:7223"

	// DefaultBackoff is the amount of time we back off if we encounter
	// and error, and no specific backoff is available.
	DefaultBackoff = 120 * time.Second

	// DisconnectDelay is how long we delay the disconnect to allow
	// the RPC to complete.
	DisconnectDelay = time.Second
)

Types

type CapabilityProvider

type CapabilityProvider func(capability string, meta map[string]string, conn io.ReadWriteCloser) error

CapabilityProvider is used to provide a given capability when requested remotely. They must return a connection that is bridged or an error.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is a SCADA compatible client. This is a bare bones client that only handles the framing and RPC protocol. Higher-level clients should be prefered.

func Dial

func Dial(addr string) (*Client, error)

Dial is used to establish a new connection over TCP

func DialOpts

func DialOpts(opts *Opts) (*Client, error)

DialOpts is a parameterized Dial

func DialTLS

func DialTLS(addr string, tlsConf *tls.Config) (*Client, error)

DialTLS is used to establish a new connection using TLS/TCP

func (*Client) Accept

func (c *Client) Accept() (net.Conn, error)

Accept is used to accept an incoming connection

func (*Client) Addr

func (c *Client) Addr() net.Addr

Addr is so that client can act like a net.Listener

func (*Client) Close

func (c *Client) Close() error

Close is used to terminate the client connection

func (*Client) NumStreams

func (c *Client) NumStreams() int

NumStreams returns the number of open streams on the client

func (*Client) Open

func (c *Client) Open() (net.Conn, error)

Open is used to open an outgoing connection

func (*Client) RPC

func (c *Client) RPC(method string, args interface{}, resp interface{}) error

RPC is used to perform an RPC

type ConnectRequest

type ConnectRequest struct {
	Capability string
	Meta       map[string]string

	Severity string
	Message  string
}

type ConnectResponse

type ConnectResponse struct {
	Success bool
}

type DisconnectRequest

type DisconnectRequest struct {
	NoRetry bool          // Should the client retry
	Backoff time.Duration // Minimum backoff
	Reason  string
}

type DisconnectResponse

type DisconnectResponse struct {
}

type FlashRequest

type FlashRequest struct {
	Severity string
	Message  string
}

type FlashResponse

type FlashResponse struct {
}

type HandshakeRequest

type HandshakeRequest struct {
	Service        string
	ServiceVersion string
	Capabilities   map[string]int
	Meta           map[string]string
	ResourceType   string
	ResourceGroup  string
	Token          string
}

HandshakeRequest is used to authenticate the session

type HandshakeResponse

type HandshakeResponse struct {
	Authenticated bool
	SessionID     string
	Reason        string
}

type HijackFunc

type HijackFunc func(io.ReadWriteCloser)

type Opts

type Opts struct {
	// Addr is the dial address
	Addr string

	// TLS controls if TLS is used
	TLS bool

	// TLSConfig or nil for default
	TLSConfig *tls.Config

	// Modifies the log output
	LogOutput io.Writer
}

Opts is used to parameterize a Dial

type Provider

type Provider struct {
	// contains filtered or unexported fields
}

Provider is a high-level interface to SCADA by which clients declare themselves as a service providing capabilities. Provider manages the client/server interactions required, making it simpler to integrate.

func NewProvider

func NewProvider(config *ProviderConfig) (*Provider, error)

NewProvider is used to create a new provider

func (*Provider) IsShutdown

func (p *Provider) IsShutdown() bool

IsShutdown checks if we have been shutdown

func (*Provider) SessionAuthenticated

func (p *Provider) SessionAuthenticated() bool

SessionAuth checks if the current session is authenticated

func (*Provider) SessionID

func (p *Provider) SessionID() string

SessionID provides the current session ID

func (*Provider) Shutdown

func (p *Provider) Shutdown()

Shutdown is used to close the provider

type ProviderConfig

type ProviderConfig struct {
	// Endpoint is the SCADA endpoint, defaults to DefaultEndpoint
	Endpoint string

	// Service is the service to expose
	Service *ProviderService

	// Handlers are invoked to provide the named capability
	Handlers map[string]CapabilityProvider

	// ResourceGroup is the named group e.g. "hashicorp/prod"
	ResourceGroup string

	// Token is the Atlas authentication token
	Token string

	// Optional TLS configuration, defaults used otherwise
	TLSConfig *tls.Config

	// LogOutput is to control the log output
	LogOutput io.Writer
}

ProviderConfig is used to parameterize a provider

type ProviderService

type ProviderService struct {
	Service        string
	ServiceVersion string
	Capabilities   map[string]int
	Meta           map[string]string
	ResourceType   string
}

ProviderService is the service being exposed