web

README

web package

This package can be used by Prometheus exporters to enable TLS and authentication.

We actively encourage the community to use this repository, to provide a consistent experience across the ecosystem.

Developers documentation can be found on pkg.go.dev.

Documentation

Index

• Variables
• func ConfigToTLSConfig(c *TLSConfig) (*tls.Config, error)
• func Listen(server *http.Server, flags *FlagConfig, logger *slog.Logger) error
• func ListenAndServe(server *http.Server, flags *FlagConfig, logger *slog.Logger) error
• func Serve(l net.Listener, server *http.Server, flags *FlagConfig, logger *slog.Logger) error
• func ServeMultiple(listeners []net.Listener, server *http.Server, flags *FlagConfig, ...) error
• func Validate(tlsConfigPath string) error
• type Cipher
  • func (c Cipher) MarshalYAML() (interface{}, error)
  • func (c *Cipher) UnmarshalYAML(unmarshal func(interface{}) error) error
• type Config
• type Curve
  • func (c *Curve) MarshalYAML() (interface{}, error)
  • func (c *Curve) UnmarshalYAML(unmarshal func(interface{}) error) error
• type FlagConfig
• type HTTPConfig
• type LandingConfig
• type LandingForm
• type LandingFormInput
• type LandingLinks
• type LandingPageHandler
  • func NewLandingPage(c LandingConfig) (*LandingPageHandler, error)
  • func (h *LandingPageHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type TLSConfig
  • func (t *TLSConfig) SetDirectory(dir string)
  • func (t *TLSConfig) VerifyPeerCertificate(rawCerts [][]byte, _ [][]*x509.Certificate) error
• type TLSVersion
  • func (tv *TLSVersion) MarshalYAML() (interface{}, error)
  • func (tv *TLSVersion) UnmarshalYAML(unmarshal func(interface{}) error) error

Variables

var (
	ErrNoListeners = errors.New("no web listen address or systemd socket flag specified")
)

Functions

func ConfigToTLSConfig

func ConfigToTLSConfig(c *TLSConfig) (*tls.Config, error)

ConfigToTLSConfig generates the golang tls.Config from the TLSConfig struct.

func Listen

func Listen(server *http.Server, flags *FlagConfig, logger *slog.Logger) error

Listen starts the server on the given address. Based on the file tlsConfigPath, TLS or basic auth could be enabled.

Deprecated: Use ListenAndServe instead.

func ListenAndServe

func ListenAndServe(server *http.Server, flags *FlagConfig, logger *slog.Logger) error

ListenAndServe starts the server on addresses given in WebListenAddresses in the FlagConfig. When address starts looks like vsock://:{port}, it listens on vsock. More info check https://wiki.qemu.org/Features/VirtioVsock . Or instead uses systemd socket activated listeners if WebSystemdSocket in the FlagConfig is true. The FlagConfig is also passed on to ServeMultiple.

func Serve

func Serve(l net.Listener, server *http.Server, flags *FlagConfig, logger *slog.Logger) error

Server starts the server on the given listener. Based on the file path WebConfigFile in the FlagConfig, TLS or basic auth could be enabled.

func ServeMultiple

func ServeMultiple(listeners []net.Listener, server *http.Server, flags *FlagConfig, logger *slog.Logger) error

ServeMultiple starts the server on the given listeners. The FlagConfig is also passed on to Serve.

func Validate

func Validate(tlsConfigPath string) error

Validate configuration file by reading the configuration and the certificates.

Types

type Cipher

type Cipher uint16

func (Cipher) MarshalYAML

func (c Cipher) MarshalYAML() (interface{}, error)

func (*Cipher) UnmarshalYAML

func (c *Cipher) UnmarshalYAML(unmarshal func(interface{}) error) error

type Config

type Config struct {
	TLSConfig  TLSConfig                     `yaml:"tls_server_config"`
	HTTPConfig HTTPConfig                    `yaml:"http_server_config"`
	Users      map[string]config_util.Secret `yaml:"basic_auth_users"`
}

type Curve

type Curve tls.CurveID

func (*Curve) MarshalYAML

func (c *Curve) MarshalYAML() (interface{}, error)

func (*Curve) UnmarshalYAML

func (c *Curve) UnmarshalYAML(unmarshal func(interface{}) error) error

type FlagConfig

type FlagConfig struct {
	WebListenAddresses *[]string
	WebSystemdSocket   *bool
	WebConfigFile      *string
}

type HTTPConfig

type HTTPConfig struct {
	HTTP2  bool              `yaml:"http2"`
	Header map[string]string `yaml:"headers,omitempty"`
}

type LandingConfig

type LandingConfig struct {
	RoutePrefix string         // The route prefix for the exporter.
	HeaderColor string         // Used for the landing page header.
	CSS         string         // CSS style tag for the landing page.
	Name        string         // The name of the exporter, generally suffixed by _exporter.
	Description string         // A short description about the exporter.
	Form        LandingForm    // A POST form.
	Links       []LandingLinks // Links displayed on the landing page.
	ExtraHTML   string         // Additional HTML to be embedded.
	ExtraCSS    string         // Additional CSS to be embedded.
	Version     string         // The version displayed.
}

Config represents the configuration of the web listener.

type LandingForm

type LandingForm struct {
	Action string
	Inputs []LandingFormInput
	Width  float64
}

LandingForm provides a configuration struct for creating a POST form on the landing page.

type LandingFormInput

type LandingFormInput struct {
	Label       string
	Type        string
	Name        string
	Placeholder string
	Value       string
}

LandingFormInput represents a single form input field.

type LandingLinks

type LandingLinks struct {
	Address     string // The URL the link points to.
	Text        string // The text of the link.
	Description string // A descriptive textfor the link.
}

type LandingPageHandler

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

func NewLandingPage

func NewLandingPage(c LandingConfig) (*LandingPageHandler, error)

func (*LandingPageHandler) ServeHTTP

func (h *LandingPageHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)

type TLSConfig

type TLSConfig struct {
	TLSCert                  string             `yaml:"cert"`
	TLSKey                   config_util.Secret `yaml:"key"`
	ClientCAsText            string             `yaml:"client_ca"`
	TLSCertPath              string             `yaml:"cert_file"`
	TLSKeyPath               string             `yaml:"key_file"`
	ClientAuth               string             `yaml:"client_auth_type"`
	ClientCAs                string             `yaml:"client_ca_file"`
	CipherSuites             []Cipher           `yaml:"cipher_suites"`
	CurvePreferences         []Curve            `yaml:"curve_preferences"`
	MinVersion               TLSVersion         `yaml:"min_version"`
	MaxVersion               TLSVersion         `yaml:"max_version"`
	PreferServerCipherSuites bool               `yaml:"prefer_server_cipher_suites"`
	ClientAllowedSans        []string           `yaml:"client_allowed_sans"`
}

func (*TLSConfig) SetDirectory

func (t *TLSConfig) SetDirectory(dir string)

SetDirectory joins any relative file paths with dir.

func (*TLSConfig) VerifyPeerCertificate

func (t *TLSConfig) VerifyPeerCertificate(rawCerts [][]byte, _ [][]*x509.Certificate) error

VerifyPeerCertificate will check the SAN entries of the client cert if there is configuration for it

type TLSVersion

type TLSVersion uint16

func (*TLSVersion) MarshalYAML

func (tv *TLSVersion) MarshalYAML() (interface{}, error)

func (*TLSVersion) UnmarshalYAML

func (tv *TLSVersion) UnmarshalYAML(unmarshal func(interface{}) error) error