mirror of https://github.com/hashicorp/boundary
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
286 lines
14 KiB
286 lines
14 KiB
---
|
|
layout: docs
|
|
page_title: Aliases
|
|
description: |-
|
|
Aliases let you associate a string with a Boundary resource. Learn how to use an alias instead of a target ID when you connect.
|
|
---
|
|
|
|
# Aliases
|
|
|
|
An alias is a globally unique, DNS-like string that is associated with a destination resource.
|
|
You can establish a session to a target by referencing its alias, instead of having to provide a target ID or target name and scope ID.
|
|
For example, if you have an alias `boundary.dev`, you can use it to connect to a target with the following command: `boundary connect ssh boundary.dev`.
|
|
|
|
## Background
|
|
|
|
When you create a resource in Boundary, it assigns the resource a randomly generated identifier.
|
|
You must use those IDs to perform actions in Boundary.
|
|
|
|
When you connect to a target using the terminal, you must reference the target ID or target name and scope name.
|
|
As an example, to SSH to a target, you can execute the command `boundary connect ssh -target-id ttcp_123456789`.
|
|
Since it can be difficult to remember the unique IDs, users frequently have to look up the identifiers for any resources they want to operate on.
|
|
|
|
Aliases simplify this process.
|
|
When you create an alias and associate it with a target, you can later use the alias `value` instead of the target ID in commands.
|
|
Boundary automatically resolves to the target that the alias references.
|
|
|
|
## Permissions
|
|
|
|
The existence of an alias for a Boundary resource does not change how permissions function.
|
|
Anyone can attempt to use an alias to access a target, but if you do not have permission to access the target, the attempt fails.
|
|
You can create an alias for a target, even if you do not have permission to access the target.
|
|
|
|
Separating the permissions from aliases and destination resources means a different set of people can manage the aliases than the people who have permission to operate on targets.
|
|
For example, you may have a project with a sensitive set of targets.
|
|
You can configure Boundary to allow a select few users to manage those targets, while a different group of users manage the aliases.
|
|
|
|
## Naming conventions
|
|
|
|
An alias is a globally unique, DNS-like string that is associated with a destination resource. The alias `value` parameter does not have to be delimited by a suffix, and can be just a hostname.
|
|
|
|
Examples of valid aliases include `database.boundary` and `webserver.boundary`.
|
|
|
|
### Single word aliases and transparent sessions
|
|
|
|
HashiCorp recommends that you do not use single-word aliases such as `webserver` as opposed to `webserver.boundary`, because single-word aliases do not work intuitively on Windows.
|
|
Windows DNS resolution does not support resolving unqualified single word DNS hostnames.
|
|
You can make the hostname fully qualified, but is not intuitive to most users.
|
|
|
|
For example the following hostname works:
|
|
|
|
```
|
|
ssh mytarget.
|
|
```
|
|
|
|
But this hostname does not work:
|
|
|
|
```
|
|
ssh mytarget
|
|
```
|
|
|
|
For this reason, if you expect any Windows users to use an alias, it contains a dot (`.`) anywhere in the value.
|
|
|
|
See the [transparent sessions](/boundary/docs/concepts/transparent-sessions) documentation for more information.
|
|
|
|
## Scopes
|
|
|
|
You can only create aliases in the `global` scope.
|
|
However, you can associate aliases with targets or hosts from any scope.
|
|
Support for additional resource types may be added in the future.
|
|
|
|
If you delete a project, Boundary clears the `destination_id` parameter for any aliases that resolve to targets in that project, so that they no longer function.
|
|
|
|
## Connect to a target using an alias
|
|
|
|
Whenever you could use the `-id` flag or `-target` flag in the CLI, you can substitute an alias.
|
|
|
|
For example, you can use the following command to connect to an SSH target with the ID `ttcp_1234567890`:
|
|
|
|
```shell-session
|
|
$ boundary connect ssh -target -id ttcp_1234567890
|
|
```
|
|
|
|
If you configured an alias named `example.alias.boundary` for the target, you could alternatively use the following command to connect to the target:
|
|
|
|
```shell-session
|
|
$ boundary connect ssh example.alias.boundary
|
|
```
|
|
|
|
## Create aliases
|
|
|
|
There are multiple ways that you can create aliases and associate them with targets in Boundary.
|
|
|
|
You can:
|
|
|
|
- [Create an alias for an existing target](#create-an-alias-for-an-existing-target)
|
|
- [Create an alias during target creation](#create-an-alias-during-target-creation)
|
|
- [Associate an existing alias with a target](#associate-an-existing-alias-with-a-target)
|
|
|
|
### Create an alias for an existing target
|
|
|
|
You can create a new alias and associate it with an existing target at the same time.
|
|
Complete the following steps to create a new alias and associate it with a target:
|
|
|
|
<Tabs>
|
|
<Tab heading="UI" group="ui">
|
|
|
|
1. Log in to Boundary.
|
|
1. Select **Aliases** in the navigation pane.
|
|
1. Click **New Alias**.
|
|
1. Complete the following fields:
|
|
- **Name**: (Optional) Enter an optional name for the alias to use for identification purposes.
|
|
- **Description**: (Optional) Enter an optional description for the alias to use for identification purposes.
|
|
- **Type**: Select **Target**.
|
|
At this time, targets are the only Boundary resources that supports aliasing.
|
|
- **Alias Value**: Enter the string that you want to use as the alias to represent the target.
|
|
An alias's value can be a hostname or a DNS-like string.
|
|
- **Target ID**: (Optional) Specify any targets you want to associate with the alias.
|
|
- **Host ID**: (Optional) Enter an optional host ID, if you would like to specify that the alias always uses the same host when you use it to connect to a target.
|
|
1. Click **Save**.
|
|
|
|
</Tab>
|
|
<Tab heading="CLI" group="cli">
|
|
|
|
1. Log in to Boundary.
|
|
1. Use the following command to create an alias:
|
|
|
|
```shell-session
|
|
$ boundary aliases create target \
|
|
-description 'This is an example alias for target tcp_1234567890' \
|
|
-destination-id tcp_1234567890 \
|
|
-name Example Boundary alias \
|
|
-scope-id global \
|
|
-value example.alias.boundary \
|
|
-authorize-session-host-id hst_1234567890
|
|
```
|
|
|
|
You can use any of the following [attributes](/boundary/docs/concepts/domain-model/aliases) when you create an alias:
|
|
|
|
- `-description=<string>` - Specifies the optional description you want to use for identification purposes.
|
|
- `-destination-id=<string>` - Specifies the ID of the target that the alias references.
|
|
- `-name=<string>` - Specifies the optional name you want to use to describe the alias for identification purposes.
|
|
- `-scope-id=<string>` - Scope in which to create the alias. The default is `global`.
|
|
You can also specify the scope using the BOUNDARY_SCOPE_ID environment variable.
|
|
At this time, aliases are only supported for the global scope.
|
|
- `-value=<string>` - Specifies the string that you want to use as the alias to represent the target.
|
|
The alias `value` can be a hostname or a DNS-like string.
|
|
- `-authorize-session-host-id=<string>` - Optionally indicates the host ID to use when you use the alias to authorize a session.
|
|
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
### Create an alias during target creation
|
|
|
|
You can create a new target and new alias at the same time and associate the two.
|
|
|
|
Complete the following steps to create a new target and new alias at the same time:
|
|
|
|
<Tabs>
|
|
<Tab heading="UI" group="ui">
|
|
|
|
1. Log in to Boundary.
|
|
1. Select **Targets** in the navigation pane.
|
|
1. Click **New Target**.
|
|
1. Complete the following fields:
|
|
- **Name**: Enter the target name for identification purposes.
|
|
- **Description**: (Optional) Enter an optional description for identification purposes.
|
|
- **Type**: Select the target type.
|
|
You can create SSH or TCP targets.
|
|
- **Target Address**: (Optional) Enter a valid IP address or DNS name.
|
|
Alternatively, you can configure host catalogs and host sets.
|
|
- **Default Port**: (Optional) Enter an optional default port for the target to use for connections.
|
|
- **Default Client Port**: (Optional) Enter an optional local proxy port on which to listen when a session is started on a client.
|
|
- **Maximum Duration**: (Optional) Enter an optional maximum duration for sessions on this target, in seconds.
|
|
- **Maximum Connection**: (Optional) Enter the maximum number of connections allowed per session on this target.
|
|
For unlimited connections, enter `-1`.
|
|
- **Workers**: (Optional) Select whether you want the worker to function as an ingress and/or egress worker.
|
|
- **Aliases**: (Optional) Enter the value fpr any aliases you want to associate with this target, and then click **Add**.
|
|
An alias's value can be a hostname or a DNS-like string.
|
|
You can associate multiple aliases with a target.
|
|
1. Click **Save**.
|
|
|
|
</Tab>
|
|
<Tab heading="CLI" group="cli">
|
|
|
|
1. Log in to Boundary.
|
|
1. Use the following command to create a target:
|
|
|
|
```shell-session
|
|
$ boundary targets create ssh \
|
|
-description 'This is an example ssh target' \
|
|
-name Example Boundary SSH target \
|
|
-scope-id global \
|
|
-with-alias-authorize-session-host-id hst_1234567890 \
|
|
-with-alias-scope-id global \
|
|
-with-alias-value example.alias.boundary
|
|
```
|
|
|
|
You can use any of the following [attributes](/boundary/docs/concepts/domain-model/targets) when you create a target:
|
|
|
|
- `description` - (optional)
|
|
An optional description that you can use for identification purposes.
|
|
- `name` - (required)
|
|
The `name` must be unique within the target's project.
|
|
- `scope-id` - (required)
|
|
The scope in which to create the target.
|
|
The default is `global`.
|
|
You can also specify the scope using the BOUNDARY_SCOPE_ID environment variable.
|
|
- `-address=<string>` - An optional valid network address for the target to connect to.
|
|
You cannot use an address alongside host sources.
|
|
- `-default-client-port=<string>` - The default client port on the target.
|
|
- `-default-port=<string>` - The default port on the target.
|
|
If you do not specify a default port, Boundary uses port 22.
|
|
- `-egress-worker-filter=<string>` - A Boolean expression that filters which egress workers can process sessions for the target.
|
|
- `-enable-session-recording=<string>` - A Boolean expression you can use to enable session recording for the target.
|
|
- `-ingress-worker-filter=<string>` - A Boolean expression that filters which ingress workers can process sessions for the target.
|
|
- `-session-connection-limit=<string>` - The maximum number of connections allowed for a session.
|
|
A value of `-1` means the connections are unlimited.
|
|
- `-session-max-seconds=<string>` - The maximum lifetime of the session, including all connections.
|
|
You can specify an integer number of seconds or a duration string.
|
|
- `-storage-bucket-id=<string>` - The public ID of the storage bucket to associate with the target.
|
|
- `-with-alias-authorize-session-host-id=<string>` - The host ID that an alias uses to authorize sessions for the target.
|
|
- `-with-aliasscope-id=<string>` - The scope ID that you want to create the target and alias in.
|
|
The default is `global`.
|
|
At this time, aliases are only supported for the global scope.
|
|
- `-with-alias-value=<string>` - The value of the alias that you want to use to represent the target.
|
|
Use this parameter to create the alias and target, and associate them with each other, at the same time.
|
|
|
|
Note that you can create SSH or TCP [target types](/boundary/docs/concepts/domain-model/targets#target-types).
|
|
The example command in this section creates an SSH target.
|
|
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
### Associate an existing alias with a target
|
|
|
|
If you already created an alias, you can update it with an existing target.
|
|
Complete the following steps to add an alias to a target:
|
|
|
|
<Tabs>
|
|
<Tab heading="UI" group="ui">
|
|
|
|
1. Log in to Boundary.
|
|
1. Select **Targets** in the navigation pane.
|
|
1. Select the target you want to add an alias to.
|
|
1. Under the **Aliases** heading in the right sidebar, click **Add an alias**.
|
|
1. Complete the following fields:
|
|
- **Name**: (Optional) Enter an optional name for the alias to use for identification purposes.
|
|
- **Description**: (Optional) Enter an optional description for the alias to use for identification purposes.
|
|
- **Type**: Select **Target**.
|
|
At this time, targets are the only Boundary resources that supports aliasing.
|
|
- **Alias Value**: Enter the alias value you want to use in commands to represent the target.
|
|
An alias's value can be a hostname or a DNS-like string.
|
|
- **Target ID**: This field contains the ID of the target you selected to add an alias to.
|
|
It is read only.
|
|
- **Host ID**: (Optional) Enter an optional host ID, if you would like to specify that the alias always uses the same host when you use it to connect to a target.
|
|
1. Click **Save**.
|
|
|
|
</Tab>
|
|
<Tab heading="CLI" group="cli">
|
|
|
|
1. Log in to Boundary.
|
|
1. Use the following command to create an alias:
|
|
|
|
```shell-session
|
|
$ boundary aliases update target \
|
|
-destination-id tcp_1234567890 \
|
|
-id alt_1234567890 \
|
|
-authorize-session-host-id hst_1234567890
|
|
```
|
|
|
|
You can use any of the following [attributes](/boundary/docs/concepts/domain-model/aliases) when you update an alias:
|
|
|
|
- `-description=<string>` - Specifies the optional description you want to use for identification purposes.
|
|
- `-destination-id=<string>` - Specifies the ID of the target that the alias references.
|
|
- `id=<string>` - Specifies the ID of the alias you want to update.
|
|
- `-name=<string>` - Specifies the optional name you want to use to describe the alias for identification purposes.
|
|
- `-scope-id=<string>` - Scope in which to create the alias. The default is `global`.
|
|
You can also specify the scope using the BOUNDARY_SCOPE_ID environment variable.
|
|
At this time, aliases are only supported for the global scope.
|
|
- `-value=<string>` - Specifies the string that you want to use as the alias to represent the target.
|
|
The alias `value` must comply with DNS naming rules.
|
|
- `-authorize-session-host-id=<string>` - Optionally indicates the host ID to use when you use the alias to authorize a session.
|
|
|
|
</Tab>
|
|
</Tabs>
|