gcssessions

README

GCS Storage Implementation for Teleport

Introduction

This package enables Teleport auth server to store session recordings in GCS on GCP.

WARNING: Using GCS involves recurring charge from GCP.

Building

GCS session storage is not enabled by default. To enable it you have to compile Teleport with gcs build flag.

To build Teleport with GCS enabled, run:

ADDFLAGS='-tags gcs' make teleport

Quick Start

Configuration options are passed to the GCS handler via a URI/URL. The following is a sample configuration in teleport section of the config file (by default it's /etc/teleport.yaml):

teleport:
  storage:
    audit_sessions_uri: 'gs://teleport-session-storage-2?projectID=gcp-proj&credentialsPath=/var/lib/teleport/gcs_creds'

Full Properties

The full list of configurable properties for this backend are:

• host portion of URI is the GCS bucket used to persist session recordings
• credentialsPath (string, path to GCP creds for Firestore, not-required)
• projectID (string, project ID, required)
• endpoint (string, GCS client endpoint, not-required, ex: localhost:8618)
• path (string, the path inside the GCS bucket to use as storage root, not-required)
• keyName (string, the user-defined GCP KMS key name to use for encryption, not-required)

GCS Client Authentication Options

There are three authentication/authorization modes available;

1. With no credentialsPath and no endpoint defined, the GCS client will use Google Application Default Credentials for authentication. This only works in cases where Teleport is installed on GCE instances and have service accounts with IAM role/profile associations authorizing that GCE instance to use Firestore.
2. With endpoint defined, GCS will create a client with no auth and clients pointed at the specified endpoint. This is only used for tests, see Tests section below.
3. With credentialsPath defined, Firestore will create clients authenticating against live systems with the Service Account bound to the JSON key file referenced in the option.

Get Help

This backend has been contributed by https://github.com/joshdurbin

Documentation

Overview

Package gcssessionsHandler implements GCS storage for Teleport session recording persistence.

gcssessions package implements the Handler session recording storage for auth server. Originally contributed by https://github.com/joshdurbin

Index

• type Config
  • func (cfg *Config) CheckAndSetDefaults() error
  • func (cfg *Config) SetFromURL(url *url.URL) error
• type Handler
  • func DefaultNewHandler(ctx context.Context, cfg Config) (*Handler, error)
  • func NewHandler(ctx context.Context, cancelFunc context.CancelFunc, cfg Config, ...) (*Handler, error)
  • func (h *Handler) Close() error
  • func (h *Handler) CompleteUpload(ctx context.Context, upload events.StreamUpload, parts []events.StreamPart) error
  • func (h *Handler) CreateUpload(ctx context.Context, sessionID session.ID) (*events.StreamUpload, error)
  • func (h *Handler) Download(ctx context.Context, sessionID session.ID, writerAt io.WriterAt) error
  • func (h *Handler) GetUploadMetadata(s session.ID) events.UploadMetadata
  • func (h *Handler) ListParts(ctx context.Context, upload events.StreamUpload) ([]events.StreamPart, error)
  • func (h *Handler) ListUploads(ctx context.Context) ([]events.StreamUpload, error)
  • func (h *Handler) ReserveUploadPart(ctx context.Context, upload events.StreamUpload, partNumber int64) error
  • func (h *Handler) Upload(ctx context.Context, sessionID session.ID, reader io.Reader) (string, error)
  • func (h *Handler) UploadPart(ctx context.Context, upload events.StreamUpload, partNumber int64, ...) (*events.StreamPart, error)

Types

type Config

type Config struct {
	// Bucket is GCS bucket name
	Bucket string
	// Path is an optional bucket path
	Path string
	// Path to the credentials file
	CredentialsPath string
	// The GCS project ID
	ProjectID string
	// KMS key name
	KMSKeyName string
	// Endpoint
	Endpoint string
	// OnComposerRun is used for fault injection in tests
	// runs (or doesn't run composer and returns error
	OnComposerRun func(ctx context.Context, composer *storage.Composer) (*storage.ObjectAttrs, error)
	// AfterObjectDelete is used for fault injection in tests
	// runs (or doesn't run object delete) and returns error
	AfterObjectDelete func(ctx context.Context, object *storage.ObjectHandle, error error) error
}

Config is handler configuration

func (*Config) CheckAndSetDefaults

func (cfg *Config) CheckAndSetDefaults() error

CheckAndSetDefaults checks and sets default values

func (*Config) SetFromURL

func (cfg *Config) SetFromURL(url *url.URL) error

SetFromURL sets values on the Config from the supplied URI

type Handler

type Handler struct {
	// Config is handler configuration
	Config
	// Entry is a logging entry
	*log.Entry
	// contains filtered or unexported fields
}

Handler handles upload and downloads to GCS object storage

func DefaultNewHandler

func DefaultNewHandler(ctx context.Context, cfg Config) (*Handler, error)

DefaultNewHandler returns a new handler with default GCS client settings derived from the config

func NewHandler

func NewHandler(ctx context.Context, cancelFunc context.CancelFunc, cfg Config, client *storage.Client) (*Handler, error)

NewHandler returns a new handler with specific context, cancelFunc, and client

func (*Handler) Close

func (h *Handler) Close() error

Close releases connection and resources associated with log if any

func (*Handler) CompleteUpload

func (h *Handler) CompleteUpload(ctx context.Context, upload events.StreamUpload, parts []events.StreamPart) error

CompleteUpload completes the upload

func (*Handler) CreateUpload

func (h *Handler) CreateUpload(ctx context.Context, sessionID session.ID) (*events.StreamUpload, error)

CreateUpload creates a multipart upload

func (*Handler) Download

func (h *Handler) Download(ctx context.Context, sessionID session.ID, writerAt io.WriterAt) error

Download downloads recorded session from GCS bucket and writes the results into writer return trace.NotFound error is object is not found

func (*Handler) GetUploadMetadata

func (h *Handler) GetUploadMetadata(s session.ID) events.UploadMetadata

GetUploadMetadata gets the metadata for session upload

func (*Handler) ListParts

func (h *Handler) ListParts(ctx context.Context, upload events.StreamUpload) ([]events.StreamPart, error)

ListParts lists upload parts

func (*Handler) ListUploads

func (h *Handler) ListUploads(ctx context.Context) ([]events.StreamUpload, error)

ListUploads lists uploads that have been initiated but not completed with earlier uploads returned first

func (*Handler) ReserveUploadPart

func (h *Handler) ReserveUploadPart(ctx context.Context, upload events.StreamUpload, partNumber int64) error

ReserveUploadPart reserves an upload part.

func (*Handler) Upload

func (h *Handler) Upload(ctx context.Context, sessionID session.ID, reader io.Reader) (string, error)

Upload uploads object to GCS bucket, reads the contents of the object from reader and returns the target GCS bucket path in case of successful upload.

func (*Handler) UploadPart

func (h *Handler) UploadPart(ctx context.Context, upload events.StreamUpload, partNumber int64, partBody io.ReadSeeker) (*events.StreamPart, error)

UploadPart uploads part