Start a development environment

8min
|
Boundary
Interactive

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

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

Prerequisites

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

Launch Terminal

This tutorial includes a free interactive command-line lab that lets you follow along on actual cloud infrastructure.

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.

Warning

Dev mode is not suitable for production environments.

Check the help message for boundary dev command.

$ boundary dev -h

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

Usage: boundary dev [options]

  Start a dev environment:

      $ boundary dev

  For a full list of examples, refer to the [documentation](/boundary/docs/configuration).

Connection Options:

  -addr=<string>
      Address of the Boundary controller, as a complete URL (for example, 
      https://boundary.example.com:9200). The address can also be specified via the
      BOUNDARY_ADDR environment variable.

  -ca-cert=<string>
      Path on the local disk to a single PEM-encoded CA certificate to
      verify the controller or worker server's SSL certificate. This path
      takes precedence over -ca-path. It can also be specified via the
      BOUNDARY_CACERT environment variable.

  -ca-path=<string>
      Path on the local disk to a directory of PEM-encoded CA certificates to
      verify the SSL certificate of the controller. This path can also be specified
      via the BOUNDARY_CAPATH environment variable.
...snip...

Start Boundary in development mode.

$ boundary dev

==> Boundary server configuration:

                        [Bsr] Aead Key Bytes: gJ6InDZfJmhlLHRiMBSY9wecgR+16WbnWWU/ueOIlY8=
                   [Recovery] Aead Key Bytes: bolGROIz4Ae/YVSASCj7hUS2SyQNL2/AHkGCfy6XpGc=
                       [Root] Aead Key Bytes: dJyHT/5YWo9KOjhZwU2mygdmLK40akAs4yU0KT6ER4c=
        [Worker-Auth-Storage] Aead Key Bytes: 6E8tbDoDtoCFYId5EvjMVlunwzWYzbdkQlYj6W/2zG0=
                [Worker-Auth] Aead Key Bytes: A3WQJnBOv6m1VqtbMizimy9yT15W3na32+w8y79vr8Q=
                             [Bsr] Aead Type: aes-gcm
                        [Recovery] Aead Type: aes-gcm
                            [Root] Aead Type: aes-gcm
             [Worker-Auth-Storage] Aead Type: aes-gcm
                     [Worker-Auth] Aead Type: aes-gcm
                                         Cgo: disabled
              Controller Public Cluster Addr: 127.0.0.1:9201
                      Dev Database Container: charming_bohr
                            Dev Database Url: postgres://postgres:password@localhost:55000/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 Ldap Auth Method Base Search Dns: users="ou=people,dc=example,dc=org" groups="ou=groups,dc=example,dc=org"
        Generated Ldap Auth Method Host:port: 127.0.0.1:52455 (does not have a root DSE; use simple bind)
               Generated Ldap Auth Method Id: amldap_1234567890
               Generated Oidc Auth Method Id: amoidc_1234567890
                      Generated Org Scope Id: o_1234567890
           Generated Password Auth Method Id: ampw_1234567890
        Generated Postgres Target With Alias: postgres.boundary.dev
                  Generated Project Scope Id: p_1234567890
             Generated Ssh Target With Alias: ssh.boundary.dev
            Generated Target With Address Id: ttcp_1234567890
        Generated Target With Host Source Id: ttcp_0987654321
           Generated Unprivileged Login Name: user
             Generated Unprivileged Password: password
             Generated Web Target With Alias: www.hashicorp.com
                                  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:9203", max_request_duration: "1m30s", purpose: "ops")
                                  Listener 4: tcp (addr: "127.0.0.1:9202", max_request_duration: "1m30s", purpose: "proxy")
                                   Log Level: info
                                       Mlock: supported: false, enabled: false
                                     Version: Boundary v0.16.0
                                 Version Sha: 3a3ae23c029711a26687e76d6a3e226f9f4479d5
                  Worker Auth Current Key Id: deceased-stallion-deplete-sermon-much-sharper-occupy-dimmed
                    Worker Auth Storage Path: /var/folders/nv/3nsbzcxn1ds56yrrf2s3d8040000gn/T/nodeenrollment3659877706
                    Worker Public Proxy Addr: 127.0.0.1:9202

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

Troubleshooting "Error creating dev database container" on Windows

Warning

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.

Warning

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").

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

In a browser window, navigate to the Boundary Admin console at http://127.0.0.1:9200
This launches the Boundary Admin console.
Enter admin in the Username field.
This is the Generated Auth Method Login Name.
Enter password in the Password field.
This is the Generated Auth Method Password.
Click Authenticate.
You are presented with the global scope, which contains the Generated org scope with the ID o_1234567890.

Display the help message for boundary authenticate command.

$ boundary authenticate -h
Usage: boundary authenticate [sub command] [options] [args]

  This command authenticates the Boundary commandline client using a specified auth method. Examples:

    Authenticate with the primary auth method in the global scope:

      $ boundary authenticate

    Authenticate using the primary auth method in a specific scope

      $ boundary authenticate password -scope-id o_1234567890

    Authenticate with a password auth method using a specific auth method ID:

      $ boundary authenticate password -auth-method-id ampw_1234567890

    Authenticate with an OIDC auth method using a specific auth method ID:

      $ boundary authenticate oidc -auth-method-id amoidc_1234567890

    Authenticate with an LDAP auth method:

      $ boundary authenticate ldap -auth-method-id amldap_1234567890

  Please see the auth method subcommand help for detailed usage information.Connection Options:

  -addr=<string>
      Addr of the Boundary controller, as a complete URL (e.g.
      https://boundary.example.com:9200). This can also be specified via the
      BOUNDARY_ADDR environment variable.
...
... snip ...
...

The CLI supports password authentication.

Authenticate using the boundary authenticate command:

$ boundary authenticate
Please enter the login name (it will be hidden):
Please enter the password (it will be hidden):

Authentication information:
  Account ID:      acctpw_1234567890
  Auth Method ID:  ampw_1234567890
  Expiration Time: Fri, 24 May 2024 14:31:22 MDT
  User ID:         u_1234567890

The token name "default" was successfully stored in the chosen keyring and is not displayed here.

The default login name is: admin
The default password is: password

The login saves a token to the KMS running on the system. Future requests use this token to authenticate until it expires.

The boundary authenticate command uses the default authentication method, called an auth method ID. Dev mode uses the default password auth method type, but other methods like OIDC and LDAP can be configured. When these are set up, you can supply the auth method ID you want to use to the boundary authenticate command, if you don't want to use the default auth method.

You can also utilize Boundary's environment variables to make authentication simpler.

Export the following environment variables:

BOUNDARY_ADDR: The controller address, http://127.0.0.1:9200 in dev mode
BOUNDARY_AUTH_METHOD_ID: The generated password auth method ID, ampw_1234567890 in dev mode

$ export BOUNDARY_ADDR="http://127.0.0.1:9200"

$ export BOUNDARY_AUTH_METHOD_ID="ampw_1234567890"

When using Boundary in the future, keep in mind that auth methods can be set up at different scopes. A Boundary scope defines a resource boundary, which can contain its own auth methods and resources. A Boundary admin may configure different auth methods for different scopes.

To log into a different scope, you may need to set a different BOUNDARY_AUTH_METHOD_ID shell variable, or pass it as the auth-method-id option when executing boundary authenticate.

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 Deploy 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.

ERROR MESSAGE: Error reading auth token from system credential store

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.

If you are using Boundary 0.9.1 or lower, use this command:

$ 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")

If you are using Boundary 0.10.0 or higher, use these commands:

$ export BOUNDARY_PASS=password
$ export BOUNDARY_TOKEN=$(boundary authenticate password \
  -auth-method-id=ampw_1234567890 \
  -login-name=admin \
  -password=env://BOUNDARY_PASS \
  -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

Create the variable KEYRING_PASSWORD with a password.

$ 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)"

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

$ 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.

Install the Boundary CLI

Explore the Boundary Admin Console web UI.

Prerequisites

Start a dev environment

Login to the Boundary console

Troubleshooting

Method 1: Bypass the keyring

Method 2: Enable the system KMS

Next steps