vaultr (version 1.0.2)

vault_test_server: 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.

Usage

vault_test_server(https = FALSE, init = TRUE,
  if_disabled = testthat::skip)
vault_test_server_install(path = NULL, quiet = FALSE,
  version = "1.0.0", platform = vault_platform())

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.

path

Path in which to install vault test server. Leave as NULL to use the VAULTR_TEST_SERVER_BIN_PATH environment variable.

quiet

Suppress progress bars on install

version

Version of vault to install

platform

For testing, overwrite the platform vault is being installed on, with either "windows", "darwin" or "linux".

Methods

addr

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

port

The vault port (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).

version

Return the server version, as a numeric_version object. Usage:

version()

client

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

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.

env

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

env()

export

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

export()

clear_cached_token

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

clear_cached_token()

kill

Kill the server. Usage:

kill()

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. Please see https://www.vaultproject.io/docs/concepts/dev-server.html for more information

The vault_test_server_install function will download a binary from HashiCorp in order to use a vault server. Use this function with care. The download will happen from https://releases.hashicorp.com/vault (over https). This function is primarily designed to be used from continuous integration services only and for local use you are strongly recommended to curate your own installations.

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.

The function vault_test_server_install will install a test server, but only if the user sets the following environmental variables:

• VAULTR_TEST_SERVER_INSTALL to "true" to opt in to the download.

• VAULTR_TEST_SERVER_BIN_PATH to the directory where the binary should be downloaded to.

• NOT_CRAN to "true" to indicate this is not running on CRAN as it requires installation of a binary from a website.

This will download a ~100MB binary from https://vaultproject.io so use with care. It is intended only for use in automated testing environments.

Examples

# NOT RUN {
# Try and start a server; if one is not enabled (see details
# above) then this will return \code{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
  # \code{kill} method:
  server$kill()
  tryCatch(client$status(), error = function(e) message(e$message))
}
# }