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
- Docker is installed
- A route to download the Postgres Docker image image or a local image cached
- 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.
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
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...
Start Boundary in development mode.
$ boundary dev
==> Boundary server configuration:
[Controller] AEAD Key Bytes: WO1h2kTypqzGqPUs+zoDioVAWIoHDtYxRy4m56DEe8A=
[Recovery] AEAD Key Bytes: xL3hZ1ePrJW2QUYx8mRgh4lGmRIf6+fOMFjHRfQJi9s=
[Worker-Auth] AEAD Key Bytes: GJmSp2MHslM698m8i2a14Mvc/9/5bq7/jZLlN9c/oi0=
[Recovery] AEAD Type: aes-gcm
[Root] AEAD Type: aes-gcm
[Worker-Auth] AEAD Type: aes-gcm
Cgo: disabled
Dev Database Container: happy_wing
Dev Database Url: postgres://postgres:password@localhost:32768?sslmode=disable
Generated Auth Method Id: ampw_1234567890
Generated Auth Method Login Name: admin
Generated Auth Method Password: password
Generated Host Catalog Id: hcst_1234567890
Generated Host Id: hst_1234567890
Generated Host Set Id: hsst_1234567890
Generated Org Scope Id: o_1234567890
Generated Project Scope Id: p_1234567890
Generated Target Id: ttcp_1234567890
Listener 1: tcp (addr: "127.0.0.1:9200", 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.1.0
Version Sha: e08ab98a2b128ee202eae46551da23c831b4acfc
Worker Public Addr: 127.0.0.1:9202
==> Boundary server started! Log data will stream in below:
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.
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
.
»Troubleshooting
Boundary clusters require an accessible key management service (KMS). An error may occur if this service is not running. Click on the error message below for solutions.
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 ".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.