config

Documentation

Index

• type CA
• type Config
  • func Read(raw []byte) (Config, error)
  • func ReadFile(path string) (Config, error)
  • func (c Config) Resolve() (Config, error)
• type FS
• type GCS
• type S3
• type Vault
• type WebDAV

Types

type CA

type CA struct {
	// IgnoreSystem instructs the certificate validation
	// machinery to ignore system-provided root authorities,
	// and to instead only consider the authorities
	// specified explicitly by this configuriation object.
	//
	IgnoreSystem bool `yaml:"ignoreSystem"`

	// SkipVerification instructs the certificate
	// validation machinery to skip all X.509 verifications,
	// and to blindly trust any and all certificates.
	//
	SkipVerification bool `yaml:"skipVerification"`

	// Literal supplies an inline string consisting
	// of one or more PEM-encoded X.509 Certificate
	// Authority certificates to serve as trusted roots.
	//
	// Literal is mutually exclusive with File, and
	// if you specify both, the configuration will be
	// considered invalid.
	//
	Literal string `yaml:"literal"`

	// File supplies the path to a single file containing
	// one or more PEM-encoded X.509 Certificate Authority
	// certificates to serve as trusted roots.
	//
	// File is mutually exclusive with Literal, and
	// if you specify both, the configuration will be
	// considered invalid.
	//
	File string `yaml:"file"`
}

A CA represents and X.509 PKI Authority for validating certificates presented by TLS and HTTPS endpoints.

type Config

type Config struct {
	// Cluster defines the named storage cluster
	// that this node belongs to.
	//
	// Names are arbitrary, and operator-defined,
	// but ought to be 64 characters or less, and
	// consist primarily of alphanumeric printable
	// characters.
	Cluster string `yaml:"cluster"`

	// Bind defines the network interface(s) that
	// the API should bind to and listen on.
	//
	Bind string `yaml:"bind"`

	// MaxLease defines how many seconds an upload
	// or download can be idle, before it is canceled,
	// and the token invalidated.
	//
	MaxLease int `yaml:"maxLease"`

	// SweepInterval defines how often (in seconds)
	// leases are examined to determine if any of
	// them have expired and need to be cancelled,
	// and have their token invalidated.
	//
	SweepInterval int `yaml:"sweepInterval"`

	// Metrics contains settings related to metrics,
	// monitoring, and measurements.
	Metrics struct {
		// ReservoirSize sets the number of samples
		// used for sampling segment bytes to get
		// the median.  This imposes an fixed upper
		// limit on the memory usage of the monitoring
		// engine, without losing useful measurements.
		//
		// Defaults to a reasonable value of 100.
		//
		ReservoirSize int `yaml:"reservoirSize"`
	} `yaml:"metrics"`

	// ControlTokens is a list of all control bearer
	// tokens, which should be given to systems that
	// are allowed to orchestrate upload, download,
	// and deletion of blobs.
	//
	ControlTokens []string `yaml:"controlTokens"`

	// MonitorTokens is a list of all monitor bearer
	// tokens, which should be given to systems that
	// track the health and wellbeing of the cluster.
	//
	MonitorTokens []string `yaml:"monitorTokens"`

	// DefaultBucket contains global defaults for
	// all buckets that don't explicitly override
	// them.
	//
	DefaultBucket struct {
		// Compression identifies the algorithm to use
		// for compressing blobs, before encryption.
		//
		// Valid values are: 'none', and 'zlib'.
		//
		Compression string `yaml:"compression"`

		// Encryption identifies the algorithm to use
		// for encrypting blobs, after compression.
		//
		// Valid values are: 'none', 'aes256-ctr',
		// 'aes256-cfb', and 'aes256-ofb'.
		//
		Encryption string `yaml:"encryption"`

		// Vault contains the configuration for storing
		// encryption keys securely.  This configuration
		// is ignored if Encryption is set to 'none'.
		//
		Vault *Vault `yaml:"vault"`
	} `yaml:"defaultBucket"`

	// Buckets defines one or more storage buckets, into
	// which SSG callers can place blobs.  Each Bucket
	// is backed by a single backend storage system
	// (like S3, local filesystem, webDAV, etc.), and
	// specifies the compression and encryption algorithms
	// used (if any).
	//
	Buckets []*struct {
		// Key is a durable, internal identifier for this
		// bucket, which will be used by callers to reference'
		// this bucket and any blobs inside of it.
		//
		Key string `yaml:"key"`

		// Name is a human-friendly identifier for this bucket.
		//
		Name string `yaml:"name"`

		// Description provides a human-friendly explanation
		// of this bucket, how it is configured, what it is
		// intended to store, etc.
		//
		Description string `yaml:"description"`

		// Compression identifies the algorithm to use
		// for compressing blobs, before encryption.
		//
		// Valid values are: 'none', and 'zlib'.
		//
		// This overrides DefaultBucket.Compression.
		//
		Compression string `yaml:"compression"`

		// Encryption identifies the algorithm to use
		// for encrypting blobs, after compression.
		//
		// Valid values are: 'none', 'aes256-ctr',
		// 'aes256-cfb', and 'aes256-ofb'.
		//
		// This overrides DefaultBucket.Encryption.
		//
		Encryption string `yaml:"encryption"`

		// Vault contains the configuration for storing
		// encryption keys securely.  This configuration
		// is ignored if Encryption is set to 'none'.
		//
		// This overrides DefaultBucket.Vault in its
		// entirety.
		//
		Vault *Vault `yaml:"vault"`

		// Provider specifies the configuration details
		// of the backing storage provider, and depends
		// quite heavily on the specific system being
		// employed.
		//
		Provider struct {
			// Kind identifies the type of provider in
			// use, and indicates which of the other
			// members of this object can and should be
			// consulted for the rest of the configuration.
			//
			// Valid values are 'fs', 'gcs', 's3', and 'webdav'.
			//
			Kind string `yaml:"kind"`

			// FS represents a local-filesystem storage provider,
			// where blobs are persisted to local disk, on the SSG.
			//
			// This is not a very scalable solution, and it has
			// terrible availability prospects, but it does work
			// well in test / dev environments, and small deployments.
			//
			FS *FS `yaml:"fs"`

			// GCS represents the configuration for Google's Cloud
			// Storage solution (often called GCS) that makes up part
			// of their Google Cloud Platform.
			//
			GCS *GCS `yaml:"gcs"`

			// S3 represents the configuration for many blob storage
			// providers that export an API similar or identical to
			// that of Amazon's Simple Scalable Storage service, S3.
			//
			S3 *S3 `yaml:"s3"`

			// WebDAV represents a storage backend that implements
			// RFC-4918 Web Distributed Authoring and Versioning
			// extensions for HTTP, a read-write version of a
			// regular web server.
			//
			WebDAV *WebDAV `yaml:"webdav"`
		} `yaml:"provider"`
	} `yaml:"buckets"`
}

var Default Config

func Read

func Read(raw []byte) (Config, error)

func ReadFile

func ReadFile(path string) (Config, error)

func (Config) Resolve

func (c Config) Resolve() (Config, error)

type FS

type FS struct {
	// Root specifies the topmost directory into which
	// blob files can be stored.  The FS provider will
	// create directories underneath this root, and
	// store files under those.
	//
	Root string `yaml:"root"`
}

FS represents a local-filesystem storage provider, where blobs are persisted to local disk, on the SSG.

This is not a very scalable solution, and it has terrible availability prospects, but it does work well in test / dev environments, and small deployments.

type GCS

type GCS struct {
	// Key represents the JSON service account key used to
	// access Google Cloud Services.  This should be given
	// as an inline JSON / YAML object, to make life easier
	// on operators -- SSG will handle its eventual conversion
	// into compact JSON.
	//
	Key interface{} `yaml:"key"`

	// Bucket specifies the name of the GCS bucket to
	// store blobs in.
	//
	Bucket string `yaml:"bucket"`

	// Prefix allows operators to share GCS buckets amongst
	// multiple storage providers without fear of collision.
	//
	// Note that if you wish this to appear filesystem-like,
	// you will need to explicitly end the prefix value
	// with a trailing forward slash ('/').
	//
	Prefix string `yaml:"prefix"`
}

GCS represents the configuration for Google's Cloud Storage solution (often called GCS) that makes up part of their GCS Cloud Platform.

type S3

type S3 struct {
	// URL identifies where the S3 (or S3-like) API endpoint
	// can be found.  This is mostly used for non-Amazon
	// implementations, like Minio or Linode OBJ.
	//
	URL string `yaml:"url"`

	// Region identifies the Amazon region in which S3
	// bucket operations are to be carried out.  Usually,
	// this is the region in which the bucket was created.
	//
	Region string `yaml:"region"`

	// Bucket specifies the name of the S3 bucket to
	// store blobs in.
	//
	Bucket string `yaml:"bucket"`

	// Prefix allows operators to share S3 buckets amongst
	// multiple storage providers without fear of collision.
	//
	// Note that if you wish this to appear filesystem-like,
	// you will need to explicitly end the prefix value
	// with a trailing forward slash ('/').
	//
	Prefix string `yaml:"prefix"`

	// UsePath indicates that the bucket should be sent in
	// the request URL path, not in the hostname, when
	// communicating with the backend.  Official S3 uses
	// DNS-based bucket addressing, but most work-alikes
	// do not.
	//
	UsePath bool `yaml:"usePath"`

	// PartSize sets the size of the pieces to send to the
	// S3 API server, in MiB (1024 * 1024 bytes).
	// Amazon AWS requires this to be at // least 5MiB,
	// but allows it to be larger.
	//
	PartSize int `json:"partSize"`

	// AccessKeyID contains the Access Key ID to use for
	// authenticating to the S3 API.
	//
	// This configuration is ignored if InstanceMetadata
	// is set to true.
	//
	AccessKeyID string `yaml:"accessKeyID"`

	// SecretAccessKey contains the Secret Access Key
	// that corresponds to the given Access Key ID, for
	// authenticating to the S3 API.
	//
	// This configuration is ignored if InstanceMetadata
	// is set to true.
	//
	SecretAccessKey string `yaml:"secretAccessKey"`

	// InstanceMetadata instructs the S3 provider to
	// dynamically acquire S3 authentication tokens
	// using the Amazon EC2 instance metadata API,
	// by crafting a specific HTTP request to a known
	// 169.x.x.x endpoint.
	//
	InstanceMetadata bool `yaml:"instanceMetadata"`
}

S3 represents the configuration for many blob storage providers that export an API similar or identical to that of Amazon's Simple Scalable Storage service, S3.

type Vault

type Vault struct {
	FixedKey struct {
		Enabled bool   `yaml:"enabled"`
		PBKDF2  string `yaml:"pbkdf2"`
		AES128  struct {
			Key string `yaml:"key"`
			IV  string `yaml:"iv"`
		} `yaml:"aes128"`
		AES192 struct {
			Key string `yaml:"key"`
			IV  string `yaml:"iv"`
		} `yaml:"aes192"`
		AES256 struct {
			Key string `yaml:"key"`
			IV  string `yaml:"iv"`
		} `yaml:"aes256"`
	} `yaml:"fixedKey"`

	// Kind identifies what type of secure storage
	// system this configuration represents.
	//
	// Currently, the only supported value is
	// "hashicorp"
	//
	Kind string `yaml:"kind"`

	// Hashicorp contains the configuration for
	// Vaults whose `Kind` is set to "hashicorp".
	//
	Hashicorp struct {
		// URL is the base URL of the Vault instance,
		// including the scheme.  Normally this will
		// be an HTTPS URL, but for test / dev purposes,
		// you may want to use a non-TLS endpoint.
		//
		URL string `yaml:"url"`

		// Prefix specifies the path prefix at which
		// to store credentials, and must be specified
		// since it also includes the mountpoint of
		// the KV v2 backend.
		//
		Prefix string `yaml:"prefix"`

		// Token contains a (root) token for accessing
		// the Vault.  This token will not be renewed,
		// so pragmatically, only a root token works.
		//
		// For more secure authentication, use AppRole,
		// by specifying a Role and a Secret.
		//
		// Token is mutually exclusive with Role / Secret,
		// and if you specify both, the configuration will
		// be considered invalid.
		//
		Token string `yaml:"token"`

		// Role contains the AppRole `role_id` value
		// to use when authenticating to this Vault.
		//
		// Role / Secret are mutually exclusive with Token,
		// and if you specify both, the configuration will
		// be considered invalid.
		//
		Role string `yaml:"role"`

		// Secret contains the AppRole `secret_id` value
		// to use when authenticating to this Vault.
		//
		// Role / Secret are mutually exclusive with Token,
		// and if you specify both, the configuration will
		// be considered invalid.
		//
		Secret string `yaml:"secret"`

		// CA provides authority configuration for
		// validating the TLS certificates presented
		// by the Vault instance during normal operation.
		//
		CA CA `yaml:"ca"`
	} `yaml:"hashicorp"`
}

Vault represents the configuration of secure credentials storage system that exists outside of the storage gateway.

type WebDAV

type WebDAV struct {
	// URL specifies the base URL at which to store and
	// retrieve files.  This may contains a request path,
	// to enable sharing of one WebDAV server amongst
	// many different buckets.
	//
	URL string `yaml:"url"`

	// BasicAuth provides the credentials for authenticating
	// to the WebDAV server using HTTP Basic Authentication,
	// a cleartext username / password scheme.
	//
	BasicAuth struct {
		// Username contains the username to authenticate with.
		//
		Username string `yaml:"username"`

		// Password contains the password to authenticate with.
		// Due to the nature of Basic Auth, this password will
		// be sent in the clear to the WebDAV server.
		//
		Password string `yaml:"password"`
	} `yaml:"basicAuth"`

	// CA provides the Certificate Authority configuration
	// to use when validating TLS X.509 Certificates
	// presented by the WebDAV server, during the course of
	// normal operation.
	//
	CA CA `yaml:"ca"`
}

WebDAV represents a storage backend that implements RFC-4918 Web Distributed Authoring and Versioning extensions for HTTP, a read-write version of a regular web server.