Connect to your first target

7min
|
HCP
Boundary

A target represents a networked service with an associated set of permissions a user can connect to through a Boundary session. A target can be part of a host set or have an address attached directly to the target.

Direct target addressing is useful for stand-alone services or smaller environments. Host sets are useful when there are multiple related network resources that are functionally equivalent.

In this tutorial, you will create a target with a direct address specified. You can learn more about host catalogs and host sets in the HCP Administration tutorials.

Prerequisites

Access to an HCP Boundary instance.
Boundary is installed.
Completed the previous quick start tutorials.
A publicly accessible Ubuntu instance.
A ssh key-pair to authenticate with the Ubuntu instance.

Note

Ubuntu is used in this tutorial for demonstration purposes only. You can follow this guide to create a publicly accessible EC2 instance to use for this tutorial.

Lab setup

Note

The use of environment variables is not required to use HCP Boundary. Environment variables are used throughout the tutorial for ease of following along and copying the required commands.

Verify you have the necessary environment variables set from the previous getting started tutorials.
```
$ printenv | grep 'BOUNDARY_\|ORG_ID\|BOUNDARY_AUTH_METHOD_ID'
```
Example output:
```
BOUNDARY_ADMIN=admin
ORG_ID=o_WxyZ123d
BOUNDARY_AUTH_METHOD_ID=ampw_hiJKlm404
BOUNDARY_ADDR=https://501abc-8675-309e-n1n3-18f2be8b9714.boundary.hashicorp.cloud
```
If you do not have BOUNDARY_ADMIN, BOUNDARY_ADDR, ORG_ID, and BOUNDARY_AUTH_METHOD_ID set, complete the previous tutorials.
Retrieve the public IP address of your Ubuntu instance and export the address as an environment variable. Replace public-ip with the actual IP address.
```
$ export UBUNTU_IP=public-ip
```
Export an environment variable for your Ubuntu host's username and path to the private key. Replace the username and path to the key file with valid values for your host.
```
$ export UBUNTU_USER=actualusername UBUNTU_KEY=private_key.pem
```
Use the same terminal session for this tutorial to avoid setting these environment variables again.

Configure HCP Boundary

Open a web browser and log into the HCP Portal.
Click Boundary in the left navigation menu and select your Boundary instance.
Click the Open Admin UI button.
Log in with the username and password you created in the Create a Boundary Instance on HCP tutorial.
Note: If you were already authenticated from the previous tutorial, you will redirected to the Orgs page.
Click quick-start-org to load the Projects page.
Projects are contained within an org, and are organizational scopes to contain roles, host catalogs, hosts, and targets.
From the Projects page, click New.
In the Name field enter quick-start-project and then click Save.
After creating a new project, the project ID is displayed.
Click the copy icon for the project ID.
Switch to the terminal used in the Lab setup section.
Create an environment variable named PROJECT_ID with the value copied from the previous step.
```
$ export PROJECT_ID=<actual-project-id>
```
Return to the Boundary Admin UI.
Click Targets in the left navigation menu.
Targets are defined within a project and their associated permissions end users can interact with. Users that have permission to establish sessions with a target through a role can connect to targets through Boundary.
Click New, enter ubuntu-target in the Name field and select Generic TCP for the Type.
Enter 22 in the Default Port field and enter the IP address of your Ubuntu host in the Address field. Enter -1 in the **Maximum Connections` field to allow an unlimited number of connections to the target.
Click Save. The target ID is then displayed.
Click the copy icon for the target ID.
Switch to the terminal used in the Lab setup section and create an environment variable named TARGET_ID with the value copied from the previous step.
```
$ export TARGET_ID=<actual-host-id>
```

Log into your HCP Boundary instance. Enter password at the Please enter the password (it will be hidden): prompt.

$ boundary authenticate
Please enter the login name (it will be hidden):
Please enter the password (it will be hidden):
Authentication information:
  Account ID:      acctpw_VOeNSFX8pQ
  Auth Method ID:  ampw_wxzojlKJLN
  Expiration Time: Mon, 13 Feb 2023 12:35:32 MST
  User ID:         u_1vUkf5fPs9
The token was successfully stored in the chosen keyring and is not displayed here.

Projects are contained within an org, and are organizational scopes to contain roles, host catalogs, hosts, and targets.

A new project can be created using the boundary scopes create command, and passing an org ID to create the project under:

$ boundary scopes create \
   -scope-id $ORG_ID \
   -name my-project

Scope information:
  Created Time:        Wed, 31 Aug 2022 10:33:44 MDT
  ID:                  p_9fcesfVKOO
  Name:                my-project
  Updated Time:        Wed, 31 Aug 2022 10:33:44 MDT
  Version:             1

  Scope (parent):
    ID:                o_XVoiuPfG1D
    Name:              Marketing Department
    Parent Scope ID:   global
    Type:              org

  Authorized Actions:
    no-op
    read
    update
    delete

After creating a new project, it's ID is displayed, as shown in the output above.

To make many Boundary tutorials simple to follow along with, resource IDs are often stored as environment variables. The command below will create the new project, format the output as JSON, select the ID, and store it as the PROJECT_ID variable.

Create a new project and export the project ID as the PROJECT_ID environment variable.

$ export PROJECT_ID=$(boundary scopes create \
   -scope-id=$ORG_ID \
   -name=quick-start-project \
   -description="My first project" \
   -format json | jq -r '.item | .id')

Targets are defined within a project. Users that have permission to establish sessions with a target through a role can connect to targets through Boundary.

A target can be created using the boundary targets create command, where the type of target is then provided, such as tcp or ssh. The tcp target type is the simplest to get started with, and requires a default-port and scope-id when being defined.

For example:

$ boundary targets create tcp \
   -name="my-first-target" \
   -description="my first target" \
   -default-port=22 \
   -scope-id=$PROJECT_ID

Target information:
  Created Time:               Wed, 31 Aug 2022 13:44:50 MDT
  Description:                my first target
  ID:                         ttcp_Gymo7Vcq7Y
  Name:                       my-first-target
  Session Connection Limit:   -1
  Session Max Seconds:        28800
  Type:                       tcp
  Updated Time:               Wed, 31 Aug 2022 13:44:50 MDT
  Version:                    1

  Scope:
    ID:                       p_vM7cfGEgq8
    Name:                     quick-start-project
    Parent Scope ID:          o_XVoiuPfG1D
    Type:                     project

  Authorized Actions:
    no-op
    read
    update
    delete
    add-host-sources
    set-host-sources
    remove-host-sources
    add-credential-sources
    set-credential-sources
    remove-credential-sources
    authorize-session

  Attributes:
    Default Port:             22

After creating a target, it's ID is displayed, like shown in the output above.

Create a target and export the target ID as the TARGET_ID environment variable.

$ export TARGET_ID=$(boundary targets create tcp \
   -name="ubuntu-target" \
   -description="ubuntu target" \
   -default-port=22 \
   -scope-id=$PROJECT_ID \
   -address=$UBUNTU_IP \
   -session-connection-limit="-1" \
   -format json | jq -r '.item | .id')

You now have a single target available with an address added to it.

Connect to a target

You are now ready to connect to the target and establish a session.

Connect to the ubuntu-target using Boundary.

Note

$UBUNTU_USER should reference the login user for the Ubuntu host and $UBUNTU_KEY should reference the path to your private key. See the Lab setup section if these values are not defined. If prompted, enter yes to continue connecting.

$ boundary connect ssh -target-id=$TARGET_ID -- -l $UBUNTU_USER -i $UBUNTU_KEY

The authenticity of host 'ec2-198-52-100-1.compute-1.amazonaws.com (198-51-100-1)' can't be established.
ECDSA key fingerprint is l4UB/neBad9tvkgJf1QZWxheQmR59WgrgzEimCG6kZY.
Are you sure you want to continue connecting (yes/no)? yes

ubuntu@ip-172-32-88-177:~

You are now connected to your Ubuntu host!

Next steps

In this tutorial you learned how to configure Boundary and connect to an external host. Next, you will learn how to broker static credentials to the client when connecting to a target.

Access HCP Boundary

Broker static credentials to a target