116 lines
4.4 KiB
Markdown
116 lines
4.4 KiB
Markdown
# 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 the
|
|
[secrets command of Telegraf](/docs/COMMANDS_AND_FLAGS.md#secrets-management)
|
|
or the tools that natively comes with your operating system.
|
|
|
|
## 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](https://docs.docker.com/engine/security/seccomp/)).
|
|
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.
|
|
|
|
### Windows
|
|
|
|
```toml @sample_windows.conf
|
|
# 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](../../../cmd/telegraf/README.md) 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
|
|
|
|
```toml @sample_linux.conf
|
|
# 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
|
|
|
|
```toml @sample_darwin.conf
|
|
# 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.
|