Common workflows for managing targets, identities, and sessions within Boundary.

Boundary Resource Management Workflows

Introduction to Boundary common workflow tutorials.

Introduction

Scopes are a fundamental part of Boundary which allow users to partition resources and assing ownership.

Manage Scopes

Configure targets to define an endpoint with a default port and protocol to establish a session.

Manage Targets

Define users and groups to assign role-based access controls.

Manage Users and Groups

Define roles to manage the permissions given to principals (users and groups).

Manage Roles and Permissions

Sessions are Boundary resources created when connecting to a target.

Manage Sessions

Quick start with a new identity-based access management tool.

Getting Started

What is Boundary and what security challenge it solves?

Introduction to Boundary

Visit the Boundary downloads page and download the appropriate installer or package for your platform.

Install Boundary

Start and authenticate to a local Boundary dev environment.

Start a Development Environment

Explore the Boundary admin console to manage resources.

Admin Console

After starting Boundary in dev mode and logging in, you can connect to your first target.

Connect to Your First Target

Install the Boundary Desktop app and connect to a running controller instance.

Install Boundary Desktop

Configure your Boundary environment using Terraform to codify the initial setup to make the process repeatable.

Configure Boundary using Terraform

Resources and further tracks now that you're confident using Boundary.

Next Steps

Learn the standard operational tasks to manage and maintain your Boundary environment.

Manage Boundary Environments

Step-by-step instructions to successfully upgrade Boundary to its
latest version, including database backup and data migration.

Upgrade and Database Migration

Boundary is an identity-based access management tool.


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](https://docs.docker.com/get-docker/) is installed
1. A route to download the [Postgres Docker image](https://hub.docker.com/_/postgres) image or a local image cached
1. A [Boundary binary](https://www.boundaryproject.io/downloads) in your `PATH`

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

<KatacodaToggleButton forceScenarioContentMode />

## Start a dev environment

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

![Boundary components](/img/boundary/boundary-components-min.png)

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

```shell-session
$ boundary dev -h
```

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

```shell-session hideClipboard
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.

```shell-session
$ 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](https://boundaryproject.io/docs/concepts/domain-model).

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.

<Tabs>
<Tab heading="Admin console">


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

   This launches the Boundary Admin console.

   ![](/img/boundary/boundary-ui-login.png)

1. Enter `admin` in the **Username** field.

   This is the _Generated Auth Method Login Name_.

1. Enter `password` in the **Password** field.

   This is the _Generated Auth Method Password_.

1. Click **Authenticate**.

   You are presented with the _global_ scope, which contains the _Generated org scope_
   with the ID `o_1234567890`.

   ![Organizations](/img/boundary/boundary-ui-org.png)

</Tab>


<Tab heading="CLI command">


Display the help message for `boundary authenticate` command.

```shell-session
$ boundary authenticate help

Usage: boundary authenticate [sub command] [options] [args]

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

    Authenticate with password auth method:

      $ boundary authenticate password -auth-method-id ampw_1234567890 -login-name foo -password "bar"

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

Subcommands:
    password    Invoke the password auth method to authenticate with Boundary
```

The CLI supports password authentication.

Authenticate with the password method using `auth-method-id`, `login-name`, and
`password` options.

```shell-session
$ boundary authenticate password
    -auth-method-id=ampw_123456790 \
    -login-name=admin \
    -password=password
```

- The `auth-method-id` is the Generated Auth Method Id: `ampw_1234567890`
- The `login-name` is the Generated Auth Method Login Name: `admin`
- The `password` is the Generated Auth Method Password: `password`

**Example output:**

```shell-session hideClipboard
Authentication information:
  Account ID:      apw_BPPNtEX82N
  Auth Method ID:  ampw_1234567890
  Expiration Time: Wed, 14 Oct 2020 18:30:40 PDT
  Token:
  at_6FOC0R3hDG_s1FFYccNfP479aLeEMpbGptDrQyG...snip...
  User ID:         u_1234567890
```

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

</Tab>
</Tabs>


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

<Accordion heading="ERROR MESSAGE: Error reading auth token from system
credential store" collapse="true">


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.

```shell-session
$ 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.

```shell-session
$ sudo apt install dbus-x11 gnome-keyring
```

Create the variable `KEYRING_PASSWORD` with a password.

```shell-session
$ 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.

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

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

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

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

</Accordion>


## Next steps

You started Boundary in dev mode and authenticated as the admin user. Next you
will manage resources using the [Boundary admin
console](/tutorials/boundary/getting-started-console).



Boundary must first be installed on your machine. Boundary is available as source
code, as a pre-compiled binary, or in packaged formats.

This tutorial will not cover how to compile Boundary from source, but compiling from
source is covered in the [README](https://github.com/hashicorp/boundary#build-and-start-boundary-in-dev-mode) for those who
want to be sure they're compiling source they trust into the final binary.

<Tabs>
<Tab heading="Manual">

To install Boundary, find the [appropriate
package](https://www.boundaryproject.io/downloads) for your system and
download it. Boundary is packaged as a zip archive.

After downloading Boundary, unzip the package. Boundary runs as a single binary
named `boundary`. Make sure that the `boundary` binary is available on your
`PATH`. You can check the locations available on your path by running this
command.

```shell-session
$ echo $PATH
```

**Example output:**

```shell-session hideClipboard
/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
```

The output is a list of locations separated by colons. You can make Boundary
available by moving the binary to one of the listed locations, or by adding
Boundary's location to your `PATH`.

-> **Tip (Linux-based or Mac):** Permanently add a new location to your path by
editing your shell's settings file (usually called something like `~/.bashrc`,
where the part of the file name after the `.` and before `rc` is the name of
your shell). In that file you will see a line that starts with `export PATH=`,
followed by a colon-separated list of locations. Add the location of the Boundary
binary to that list and save the file. Then reload your shell's configuration
with the command `source ~/.bashrc`, replacing `bash` with the name of your
shell.

-> **Tip (Windows):** Add a location to your path via the GUI by navigating to
`Environment Variables` in your system settings, and looking for the variable
called `PATH`. You will see a semicolon-separated list of locations. Add the
Boundary binary's location to that list and then launch a new console window.

</Tab>
<Tab heading="macOS">

[Homebrew](https://brew.sh) is a free and open-source package management system
for Mac OS X. Install the official [boundary
formula](https://github.com/hashicorp/homebrew-tap) from the terminal.

```shell-session
$ brew install hashicorp/tap/boundary
```

~> **NOTE:** This installs a signed binary and is automatically updated with
every new official release.

To update to the latest, run

```shell-session
$ brew upgrade hashicorp/tap/boundary
```

</Tab>
<Tab heading="Windows">

[Scoop](https://scoop.sh/) is a free and open-source package management system
for Windows. Install Boundary from the command-line.

```shell-session
$ scoop install boundary
```

~> **NOTE:** The [Scoop main bucket
repository](https://github.com/ScoopInstaller/Main/blob/master/bucket/boundary.json)
is **NOT** maintained by HashiCorp. The latest version of Boundary is always
available by manual installation.

</Tab>
<Tab heading="Linux">

HashiCorp officially maintains and signs packages for the following Linux distributions.

<Tabs>
<Tab heading="Ubuntu/Debian">

Add the HashiCorp [GPG key][gpg-key].

```shell-session
$ curl -fsSL https://apt.releases.hashicorp.com/gpg | sudo apt-key add -
```

Add the official HashiCorp Linux repository.

```shell-session
$ sudo apt-add-repository "deb [arch=amd64] https://apt.releases.hashicorp.com $(lsb_release -cs) main"
```

Update and install.

```shell-session
$ sudo apt-get update && sudo apt-get install boundary
```

</Tab>
<Tab heading="CentOS/RHEL">

Install `yum-config-manager` to manage your repositories.

```shell-session
$ sudo yum install -y yum-utils
```

Use `yum-config-manager` to add the official HashiCorp Linux repository.

```shell-session
$ sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/RHEL/hashicorp.repo
```

Install.

```shell-session
$ sudo yum -y install boundary
```

</Tab>
<Tab heading="Fedora">

Install `dnf config-manager` to manage your repositories.

```shell-session
$ sudo dnf install -y dnf-plugins-core
```

Use `dnf config-manager` to add the official HashiCorp Linux repository.

```shell-session
$ sudo dnf config-manager --add-repo https://rpm.releases.hashicorp.com/fedora/hashicorp.repo
```

Install.

```shell-session
sudo dnf -y install boundary
```

</Tab>
<Tab heading="Amazon Linux">

Install `yum-config-manager` to manage your repositories.

```shell-session
$ sudo yum install -y yum-utils
```

Use `yum-config-manager` to add the official HashiCorp Linux repository.

```shell-session
$ sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/AmazonLinux/hashicorp.repo
```

Install.

```shell-session
$ sudo yum -y install boundary
```

</Tab>
</Tabs>

-> **TIP:** Now that you have added the HashiCorp repository, you can install
[Terraform](/tutorials/terraform/install-cli), [Consul](/tutorials/consul/get-started-install), [Nomad](/tutorials/nomad/get-started-install) and [Packer](/tutorials/packer/get-started-install) with the same command.

</Tab>
</Tabs>


## Verify the installation

After installing Boundary, verify the installation worked by opening a new
command prompt or console, and checking that `boundary` is available.

-> **Tip:** If you receive an error that Boundary is not
found, try logging out and logging back in to your system (particularly
necessary sometimes for Windows).

```shell-session
$ boundary
Usage: boundary <command> [args]

Commands:
    accounts           Manage Boundary accounts
    auth-methods       Manage Boundary auth-methods
    auth-tokens        Manage Boundary auth-tokens
    authenticate       Authenticate the Boundary command-line client
    config             Manage resources related to Boundary's local configuration
    connect            Authorize a session against a target and launch a proxied connection
    database           Manage Boundary's database
    dev                Start a Boundary dev environment
    groups             Manage Boundary groups
    host-catalogs      Manage Boundary host-catalogs
    host-sets          Manage Boundary host-sets
    hosts              Manage Boundary hosts
    proxy              Launch the Boundary CLI in proxy mode
    roles              Manage Boundary roles
    scopes             Manage Boundary scopes
    server             Start a Boundary server
    sessions           Manage Boundary sessions
    targets            Manage Boundary targets
    users              Manage Boundary users
```

You have successfully downloaded and installed Boundary! Continue to the next
tutorial to set up your first Boundary project.


[gpg-key]: https://apt.releases.hashicorp.com/gpg 'HashiCorp GPG key'



Boundary enables simple and secure access to dynamic infrastructure by:

- **Identity-based access controls:** Streamline just-in-time access to
privileged sessions (e.g. TCP, SSH, RDP) for users and applications. Tightly
control access permissions with extensible role-based access controls.

- **Access Automation:** Define your perimeter of resources, identities, and
access controls as code through Boundary's fully-instrumented Terraform
Provider, REST API, CLI, and SDK. Automate the discovery of new resources and
enforcement of existing policies as resources are provisioned.

- **Session Visibility:** Security administrators gain monitor and managed the
privileged sessions established with Boundary. Export session logs to your
analytics tool of choice.

![Boundary Workflow](/img/boundary/boundary-workflow.png)

Traditional approaches like SSH bastion hosts or VPNs that require distributing
and managing credentials, configure network controls like firewalls, and expose
the private network.  Boundary provides a secure way to access to hosts and
critical systems without having to manage credentials or expose your network.

![Boundary overview](/img/boundary/boundary-overview-2.png)

Refer to the [Boundary documentation
page](https://boundaryproject.io/docs/concepts).

The Boundary getting started tutorials will walk you through your first
Boundary project, highlighting major features of Boundary.


Get Started

Jump start with Boundary!

Introduction to Boundary

Install Boundary

Start a Development Environment

Manage Boundary Resource

Infrastructure

Security

Networking

Applications

Get Started

Jump start with Boundary!

Introduction to Boundary

Install Boundary

Start a Development Environment

Manage Boundary Resource