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 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:

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

$ 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

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:

Log in to Boundary.
Select Aliases in the navigation pane.
Click New Alias.
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.
Click Save.

Log in to Boundary.
Use the following command to create an alias:
```
$ 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 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.

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:

Log in to Boundary.
Select Targets in the navigation pane.
Click New Target.
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.
Click Save.

Log in to Boundary.
Use the following command to create a target:
```
$ 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 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. The example command in this section creates an SSH target.

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:

Log in to Boundary.
Select Targets in the navigation pane.
Select the target you want to add an alias to.
Under the Aliases heading in the right sidebar, click Add an alias.
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.
Click Save.

Log in to Boundary.
Use the following command to create an alias:
```
$ 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 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.