vault_test_server: Control a test vault server

In vaultr: Vault Client for Secrets and Sensitive Data

Control a test vault server

Description

Control a server for use with testing. This is designed to be used only by other packages that wish to run tests against a vault server. You will need to set VAULTR_TEST_SERVER_BIN_PATH to point at the directory containing the vault binary, to the binary itself, or to the value auto to try and find it on your PATH.

Usage

vault_test_server(
  https = FALSE,
  init = TRUE,
  if_disabled = testthat::skip,
  quiet = FALSE
)

Arguments

https	Logical scalar, indicating if a https-using server should be created, rather than the default vault dev-mode server. This is still entirely insecure, and uses self signed certificates that are bundled with the package.
init	Logical scalar, indicating if the https-using server should be initialised.
if_disabled	Callback function to run if the vault server is not enabled. The default, designed to be used within tests, is testthat::skip. Alternatively, inspect the ⁠$enabled⁠ property of the returned object.
quiet	Logical, indicating if startup should be quiet and not print messages

Details

Once created with vault_test_server, a server will stay alive for as long as the R process is alive or until the vault_server_instance object goes out of scope and is garbage collected. Calling ⁠$kill()⁠ will explicitly stop the server, but this is not strictly needed. See below for methods to control the server instance.

Warning

Starting a server in test mode must not be used for production under any circumstances. As the name suggests, vault_test_server is a server suitable for tests only and lacks any of the features required to make vault secure. For more information, please see the the official Vault documentation on development servers: https://developer.hashicorp.com/vault/docs/concepts/dev-server

Super class

vaultr::vault_client_object -> vault_server_instance

Public fields

port

The vault port (read-only).

addr

The vault address; this is suitable for using with vault_client (read-only).

token

The vault root token, from when the testing vault server was created. If the vault is rekeyed this will no longer be accurate (read-only).

keys

Key shares from when the vault was initialised (read-only).

cacert

Path to the https certificate, if running in https mode (read-only).

Methods

Public methods

• vault_server_instance$new()

• vault_server_instance$version()

• vault_server_instance$client()

• vault_server_instance$env()

• vault_server_instance$export()

• vault_server_instance$clear_cached_token()

• vault_server_instance$kill()

Inherited methods

• vaultr::vault_client_object$format()
• vaultr::vault_client_object$help()

---

Method new()

Create a vault_server_instance object. Not typically called by users.

Usage

vault_server_instance$new(bin, port, https, init, quiet = FALSE)

Arguments

bin

Path to the vault binary

port

Port to use

https

Logical, indicating if we should use TLS/https

init

Logical, indicating if we should initialise

quiet

Logical, indicating if startup should be quiet

---

Method version()

Return the server version, as a numeric_version object.

Usage

vault_server_instance$version()

---

Method client()

Create a new client that can use this server. The client will be a vault_client object.

Usage

vault_server_instance$client(login = TRUE, quiet = TRUE)

Arguments

login

Logical, indicating if the client should login to the server (default is TRUE).

quiet

Logical, indicating if informational messages should be suppressed. Default is TRUE, in contrast with most other methods.

---

Method env()

Return a named character vector of environment variables that can be used to communicate with this vault server (VAULT_ADDR, VAULT_TOKEN, etc).

Usage

vault_server_instance$env()

---

Method export()

Export the variables returned by the ⁠$env()⁠ method to the environment. This makes them available to child processes.

Usage

vault_server_instance$export()

---

Method clear_cached_token()

Clear any session-cached token for this server. This is intended for testing new authentication backends.

Usage

vault_server_instance$clear_cached_token()

---

Method kill()

Kill the server.

Usage

vault_server_instance$kill()

Examples

# Try and start a server; if one is not enabled (see details
# above) then this will return NULL
server <- vault_test_server(if_disabled = message)

if (!is.null(server)) {
  # We now have a server running on an arbitrary high port - note
  # that we are running over http and in dev mode: this is not at
  # all suitable for production use, just for tests
  server$addr

  # Create clients using the client method - by default these are
  # automatically authenticated against the server
  client <- server$client()
  client$write("/secret/password", list(value = "s3cret!"))
  client$read("/secret/password")

  # The server stops automatically when the server object is
  # garbage collected, or it can be turned off with the
  # 'kill' method:
  server$kill()
  tryCatch(client$status(), error = function(e) message(e$message))
}

vaultr documentation built on Nov. 9, 2023, 5:07 p.m.