os

README

OS Secret-store Plugin

The os plugin allows to manage and store secrets using the native Operating System keyring. For Windows this plugin uses the credential manager, on Linux the kernel keyring is used and on MacOS we use the Keychain implementation.

To manage your secrets you can either use Telegraf or the tools that natively comes with your operating system. Run

telegraf secrets help

to get more information on how to do this with Telegraf.

Configuration

The configuration differs slightly depending on the Operating System. We first describe the common options here and the refer to the individual interpretation or options in the following sections.

All secret-store implementations require an id to be able to reference the store when specifying the secret. The id needs to be unique in the configuration.

For all operating systems, the keyring name can be chosen using the keyring parameter. However, the interpretation is slightly different on the individual implementations.

The dynamic flag allows to indicate secrets that change during the runtime of Telegraf. I.e. when set to true, the secret will be read from the secret-store on every access by a plugin. If set to false, all secrets in the secret store are assumed to be static and are only read once at startup of Telegraf.

Docker

Access to the kernel keyring is disabled by default in docker containers (see documentation). In this case you will get an opening keyring failed: Specified keyring backend not available error!

You can enable access to the kernel keyring, but as the keyring is not namespaced, you should be aware of the security implication! One implication is for example that keys added in one container are accessible by all other containers running on the same host, not only within the same container.

systemd-nspawn

The memguard dependency that Telegraf uses to secure memory for secret storage requires the CAP_IPC_LOCK capability to correctly lock memory. Without this capability Telegraf will panic. Users will need to start a container with the --capability=CAP_IPC_LOCK flag for telegraf to correctly work.

See github.com/awnumar/memguard#144 for more information.

Windows

# Operating System native secret-store
[[secretstores.os]]
  ## Unique identifier for the secret-store.
  ## This id can later be used in plugins to reference the secrets
  ## in this secret-store via @{<id>:<secret_key>} (mandatory)
  id = "secretstore"

  ## Keyring of the secrets
  ## In Windows, keys follow a fixed pattern in the form `<keyring>:<collection>:<key>`. Please keep this in mind
  ## when creating secrets with the Windows credential tool.
  # keyring = "telegraf"
  # collection = ""

  ## Allow dynamic secrets that are updated during runtime of telegraf
  # dynamic = false

On Windows you can use the Credential Manager Control panel or Telegraf to manage your secrets. Please use generic credentials and respect the special <keyring>:<collection>:<key> format of the secret key. The secret value needs to be stored in the Password field.

Linux

# Operating System native secret-store
[[secretstores.os]]
  ## Unique identifier for the secret-store.
  ## This id can later be used in plugins to reference the secrets
  ## in this secret-store via @{<id>:<secret_key>} (mandatory)
  id = "secretstore"

  ## Keyring name used for the secrets
  # keyring = "telegraf"

  ## Allow dynamic secrets that are updated during runtime of telegraf
  # dynamic = false

On Linux the kernel keyring in the user scope is used to store the secrets. The collection setting is ignored on Linux.

MacOS

# Operating System native secret-store
[[secretstores.os]]
  ## Unique identifier for the secret-store.
  ## This id can later be used in plugins to reference the secrets
  ## in this secret-store via @{<id>:<secret_key>} (mandatory)
  id = "secretstore"

  ## MacOS' Keychain name and service name
  # keyring = "telegraf"
  # collection = ""

  ## MacOS' Keychain password
  ## If no password is specified here, Telegraf will prompt for it at startup time.
  # password = ""

  ## Allow dynamic secrets that are updated during runtime of telegraf
  # dynamic = false

On MacOS the Keychain implementation is used. Here the keyring parameter corresponds to the Keychain name and the collection to the optional Keychain service name. Additionally a password is required to access the Keychain. The password itself is also a secret and can be a string, an environment variable or a reference to a secret stored in another secret-store. If password is omitted, you will be prompted for the password on startup.

Documentation

Index

• type OS
  • func (o *OS) Get(key string) ([]byte, error)
  • func (o *OS) GetResolver(key string) (telegraf.ResolveFunc, error)
  • func (o *OS) Init() error
  • func (o *OS) List() ([]string, error)
  • func (*OS) SampleConfig() string
  • func (o *OS) Set(key, value string) error

Types

type OS

type OS struct {
	ID         string        `toml:"id"`
	Keyring    string        `toml:"keyring"`
	Collection string        `toml:"collection"`
	Dynamic    bool          `toml:"dynamic"`
	Password   config.Secret `toml:"password"`
	// contains filtered or unexported fields
}

func (*OS) Get

func (o *OS) Get(key string) ([]byte, error)

Get searches for the given key and return the secret

func (*OS) GetResolver

func (o *OS) GetResolver(key string) (telegraf.ResolveFunc, error)

GetResolver returns a function to resolve the given key.

func (*OS) Init

func (o *OS) Init() error

Init initializes all internals of the secret-store

func (*OS) List

func (o *OS) List() ([]string, error)

List lists all known secret keys

func (*OS) SampleConfig

func (*OS) SampleConfig() string

func (*OS) Set

func (o *OS) Set(key, value string) error

Set sets the given secret for the given key