Skip to main content
Oct 19-21 HashiConf Global is live. Join Now
Type '/' to Search

Start a Development Environment

Boundary provides a dev mode to enable quick testing and exploration. Dev mode provides admin credentials for password authentication.

In this tutorial, you will start Boundary in dev mode and authenticate as the admin user.

»Prerequisites

  1. Docker is installed
  2. A route to download the Postgres Docker image image or a local image cached
  3. A Boundary binary in your PATH

NOTE: An interactive tutorial is also available to demonstrate the basic working of Boundary. Click the Show Terminal button to start.

»Start a dev environment

A deployment of a highly available (HA) Boundary service requires multiple controllers and workers to construct a cluster.

Boundary components

  • Controllers are responsible for understanding configuration, authenticating and authorizing users, and serving user API requests (e.g. to initiate a session).

  • Boundary clusters require an accessible key management service (KMS) and database shared by controllers. Boundary's database maintains the state of Boundary's resources, identities, and access policies. Boundary's KMS is customer-defined and serves as Boundary's root-of-trust for at-rest and in-transit encryption.

  • Workers are responsible for the actual session recording/proxying capability and other tasks that involve storage.

Dev mode brings up a fully functioning instance of Boundary which includes:

  • A controller server
  • A worker server
  • A Postgres database

These components are ephemeral; therefore, data is not persisted and convenient for quick testing.

Dev mode is not suitable for production environments.

Check the help message for boundary dev command.

$ boundary dev -h

$ boundary dev -h

There are optional flags available to configure Boundary environment through the command line.

Command Options:

  -api-listen-address=<string>
      Address to bind to for controller "api" purpose. This can also be
      specified via the BOUNDARY_DEV_CONTROLLER_API_LISTEN_ADDRESS environment
      variable.

  -cluster-listen-address=<string>
      Address to bind to for controller "cluster" purpose. This can also
      be specified via the BOUNDARY_DEV_CONTROLLER_CLUSTER_LISTEN_ADDRESS
      environment variable.

  -combine-logs
      If set, both startup information and logs will be sent to stdout. If not
      set (the default), startup information will go to stdout and logs will
      be sent to stderr. The default is false.

  # ...snip...

Command Options:
  -api-listen-address=<string>      Address to bind to for controller "api" purpose. This can also be      specified via the BOUNDARY_DEV_CONTROLLER_API_LISTEN_ADDRESS environment      variable.
  -cluster-listen-address=<string>      Address to bind to for controller "cluster" purpose. This can also      be specified via the BOUNDARY_DEV_CONTROLLER_CLUSTER_LISTEN_ADDRESS      environment variable.
  -combine-logs      If set, both startup information and logs will be sent to stdout. If not      set (the default), startup information will go to stdout and logs will      be sent to stderr. The default is false.
  # ...snip...

Start Boundary in development mode.

$ boundary dev

==> Boundary server configuration:

        [Controller] AEAD Key Bytes: kNN1tkw9/umvdErDRcOBf8lUZ5JBktLANvc2HOR6yDU=
          [Recovery] AEAD Key Bytes: jWXmQsLNAt9le4EOPL0zlxqwVUOpBIG4T0sKOcIbsvI=
       [Worker-Auth] AEAD Key Bytes: DYI2kzy0HYXpwpk8M4BHHVKE11Ay5YV76fvAknRcE9s=
               [Recovery] AEAD Type: aes-gcm
                   [Root] AEAD Type: aes-gcm
            [Worker-Auth] AEAD Type: aes-gcm
                                Cgo: disabled
     Controller Public Cluster Addr: 127.0.0.1:9201
             Dev Database Container: jolly_goldstine
                   Dev Database Url: postgres://postgres:password@localhost:55001/boundary?sslmode=disable
         Generated Admin Login Name: admin
           Generated Admin Password: password
          Generated Host Catalog Id: hcst_1234567890
                  Generated Host Id: hst_1234567890
              Generated Host Set Id: hsst_1234567890
      Generated Oidc Auth Method Id: amoidc_1234567890
             Generated Org Scope Id: o_1234567890
  Generated Password Auth Method Id: ampw_1234567890
         Generated Project Scope Id: p_1234567890
                Generated Target Id: ttcp_1234567890
  Generated Unprivileged Login Name: user
    Generated Unprivileged Password: password
                         Listener 1: tcp (addr: "127.0.0.1:9200", cors_allowed_headers: "[]", cors_allowed_origins: "[*]", cors_enabled: "true", max_request_duration: "1m30s", purpose: "api")
                         Listener 2: tcp (addr: "127.0.0.1:9201", max_request_duration: "1m30s", purpose: "cluster")
                         Listener 3: tcp (addr: "127.0.0.1:9202", max_request_duration: "1m30s", purpose: "proxy")
                          Log Level: info
                              Mlock: supported: false, enabled: false
                            Version: Boundary v0.7.1
                        Version Sha: abd695e5bc42d01e4412bf6c76211c3fc93a93d7
           Worker Public Proxy Addr: 127.0.0.1:9202

==> Boundary server started! Log data will stream in below:

{
  "id": "qqVn6GnPe3",
  "source": "https://hashicorp.com/boundary/dev-controller/boundary-dev",
  "specversion": "1.0",
  "type": "system",
  "data": {
    "version": "v0.1",
    "op": "worker.(Worker).createClientConn",
    "data": {
      "address": "127.0.0.1:9201",
      "msg": "connected to controller"
    }
  },
  "datacontentype": "text/plain",
  "time": "2021-12-06T11:18:33.041494-07:00"
}
{
  "id": "HXvjcn1uZ1",
  "source": "https://hashicorp.com/boundary/dev-controller/boundary-dev",
  "specversion": "1.0",
  "type": "system",
  "data": {
    "version": "v0.1",
    "op": "controller.(interceptingListener).Accept",
    "data": {
      "msg": "worker successfully authed",
      "name": "dev-worker"
    }
  },
  "datacontentype": "text/plain",
  "time": "2021-12-06T11:18:33.058218-07:00"
}

$ boundary dev
==> Boundary server configuration:
        [Controller] AEAD Key Bytes: kNN1tkw9/umvdErDRcOBf8lUZ5JBktLANvc2HOR6yDU=          [Recovery] AEAD Key Bytes: jWXmQsLNAt9le4EOPL0zlxqwVUOpBIG4T0sKOcIbsvI=       [Worker-Auth] AEAD Key Bytes: DYI2kzy0HYXpwpk8M4BHHVKE11Ay5YV76fvAknRcE9s=               [Recovery] AEAD Type: aes-gcm                   [Root] AEAD Type: aes-gcm            [Worker-Auth] AEAD Type: aes-gcm                                Cgo: disabled     Controller Public Cluster Addr: 127.0.0.1:9201             Dev Database Container: jolly_goldstine                   Dev Database Url: postgres://postgres:password@localhost:55001/boundary?sslmode=disable         Generated Admin Login Name: admin           Generated Admin Password: password          Generated Host Catalog Id: hcst_1234567890                  Generated Host Id: hst_1234567890              Generated Host Set Id: hsst_1234567890      Generated Oidc Auth Method Id: amoidc_1234567890             Generated Org Scope Id: o_1234567890  Generated Password Auth Method Id: ampw_1234567890         Generated Project Scope Id: p_1234567890                Generated Target Id: ttcp_1234567890  Generated Unprivileged Login Name: user    Generated Unprivileged Password: password                         Listener 1: tcp (addr: "127.0.0.1:9200", cors_allowed_headers: "[]", cors_allowed_origins: "[*]", cors_enabled: "true", max_request_duration: "1m30s", purpose: "api")                         Listener 2: tcp (addr: "127.0.0.1:9201", max_request_duration: "1m30s", purpose: "cluster")                         Listener 3: tcp (addr: "127.0.0.1:9202", max_request_duration: "1m30s", purpose: "proxy")                          Log Level: info                              Mlock: supported: false, enabled: false                            Version: Boundary v0.7.1                        Version Sha: abd695e5bc42d01e4412bf6c76211c3fc93a93d7           Worker Public Proxy Addr: 127.0.0.1:9202
==> Boundary server started! Log data will stream in below:
{  "id": "qqVn6GnPe3",  "source": "https://hashicorp.com/boundary/dev-controller/boundary-dev",  "specversion": "1.0",  "type": "system",  "data": {    "version": "v0.1",    "op": "worker.(Worker).createClientConn",    "data": {      "address": "127.0.0.1:9201",      "msg": "connected to controller"    }  },  "datacontentype": "text/plain",  "time": "2021-12-06T11:18:33.041494-07:00"}{  "id": "HXvjcn1uZ1",  "source": "https://hashicorp.com/boundary/dev-controller/boundary-dev",  "specversion": "1.0",  "type": "system",  "data": {    "version": "v0.1",    "op": "controller.(interceptingListener).Accept",    "data": {      "msg": "worker successfully authed",      "name": "dev-worker"    }  },  "datacontentype": "text/plain",  "time": "2021-12-06T11:18:33.058218-07:00"}

On Windows systems you may encounter the following error when running boundary dev:

$ boundary dev

Error creating dev database container: unable to start dev database with dialect postgres: could not start resource: : Post "http://localhost:2375/images/create?fromImage=postgres&tag=12": dial tcp [::1]:2375: connectex: No connection could be made because the target machine actively refused it.

$ boundary dev
Error creating dev database container: unable to start dev database with dialect postgres: could not start resource: : Post "http://localhost:2375/images/create?fromImage=postgres&tag=12": dial tcp [::1]:2375: connectex: No connection could be made because the target machine actively refused it.

If the error is similar to the one printed above, the Docker daemon may need to be exposed on port 2375 without TLS.

Open Docker Desktop, and navigate to the Settings panel by clicking on the gear icon at the top-right of the screen.

Under General settings, click the checkbox next to Expose deamon on tcp://localhost:2375 without TLS to enable the setting. Then click Apply & Restart to restart Docker Desktop. The screenshot below shows the setting that should be enabled.

After Docker Desktop restarts, attempt running boundary dev again.

Boundary starts in dev mode with default authentication credentials and a set of pre-defined resources.

These admin credentials enable you to log in the Boundary console.

  • Generated Auth Method Id: ampw_1234567890
  • Generated Auth Method Login Name: admin
  • Generated Auth Method Password: password

The default login name and password can be overwritten with -login-name and -password flags (e.g. boundary dev -login-name="dev-admin" -password="p@ssw0rd").

»Login to the Boundary console

You can authenticate to the Boundary console via the Admin console or the CLI.

  1. In a browser window, navigate to the Boundary Admin console at http://127.0.0.1:9200

    This launches the Boundary Admin console.

  2. Enter admin in the Username field.

    This is the Generated Auth Method Login Name.

  3. Enter password in the Password field.

    This is the Generated Auth Method Password.

  4. Click Authenticate.

    You are presented with the global scope, which contains the Generated org scope with the ID o_1234567890.

    Organizations

»Troubleshooting

Boundary clusters require an accessible key management service (KMS). An error may occur if this service is not running.

If you are having problems logging in with boundary authenticate, especially on Unix-like operating systems other than MacOS, you may be having problems with your local key store. See the Run and Login to Boundary page in Boundary's documentation for more details.

Click on the error message below for step-by-step solutions to continue the Getting Started tutorials.

In a Unix shell this error implies that the freedesktop.org Secret Service implementation is not available. To fix this issue you can either bypass the keyring or enable the system KMS.

»Method 1: Bypass the keyring

The CLI can bypass the operating system's keyring manager by overriding the keyring type and managing the token in the environment variable.

Set the BOUNDARY_TOKEN environment variable to the authentication token.

$ export BOUNDARY_TOKEN=$(boundary authenticate password \
  -auth-method-id=ampw_1234567890 \
  -login-name=admin \
  -password=password \
  -keyring-type=none \
  -format=json | jq -r ".item.attributes.token")

$ export BOUNDARY_TOKEN=$(boundary authenticate password \  -auth-method-id=ampw_1234567890 \  -login-name=admin \  -password=password \  -keyring-type=none \  -format=json | jq -r ".item.attributes.token")

The keyring is bypassed by setting keyring-type to disabled (none). The results are formatted to json -format=json, and parsed by jq for the token value.

»Method 2: Enable the system KMS

You can fix this error by installing the dbus-x11 and gnome-keyring packages and manually invoking the keyring daemon.

On Ubuntu, install the dbus-x11 and gnome-keyring packages.

$ sudo apt install dbus-x11 gnome-keyring

$ sudo apt install dbus-x11 gnome-keyring

Create the variable KEYRING_PASSWORD with a password.

$ KEYRING_PASSWORD="FOOBAR\n"

$ KEYRING_PASSWORD="FOOBAR\n"

You can prevent the password from being captured on the command line by running the gnome-keyring-daemon command directly and entering in the password when requested, followed by a newline (return) and an EOF (Ctrl+D).

Substitute FOOBAR with a password of your choice. Leave the \n.

Create a default keyring and unlock it with a password.

$ eval "$(printf '$KEYRING_PASSWORD' | gnome-keyring-daemon --unlock)"

$ eval "$(printf '$KEYRING_PASSWORD' | gnome-keyring-daemon --unlock)"

Connect to the keyring daemon and initialize it with the same password.

$ eval "$(printf 'KEYRING_PASSWORD' | gnome-keyring-daemon --start)"

$ eval "$(printf 'KEYRING_PASSWORD' | gnome-keyring-daemon --start)"

Run this in any shell where the Boundary CLI is invoked.

»Next steps

You started Boundary in dev mode and authenticated as the admin user. Next you will manage resources using the Boundary admin console.

stdin: is not a tty