Beam

Beam me up Ferris!

What is Beam?

Beam is an interface on top of the Teleport CLI. It uses skim, a fuzzy finder written in Rust, to provide a nice interface for searching and filtering.

Table of contents

• Beam
  • What is Beam?
  • Table of Contents
  • Installation
    • Through Brew
    • Through Cargo
  • Configuration
    • Pattern matching
    • Caching
    • Port forwarding
  • Usage
    • Search Syntax
  • Adding completions to your shell

Installation

Through Brew

For installing Beam through Homebrew, run the following commands:

brew tap MichaelMandel26/beamcli
brew install beam

This will also automatically install the Teleport CLI, as it is a dependency of Beam.

Through Cargo

Make sure that you have the Teleport CLI installed, before using Beam through cargo.

For installing Beam through cargo you will have to install Rust. Rustup is the recommended way to do that.
You can then install it through running:

cargo install beamcli

Configuration

Before using Beam you will have to configure a default profile.

$ beam configure
✔ Profile name · myProfile
✔ Do you want to auto-select this profile, using a regex pattern on the hostname? · no
✔ Proxy · teleport.example.com
✔ Username · dzefo
✔ Authentication Method · default
✔ Cache TTL · 86400
✔ Do you want to only show specific labels? · no

If you want to use SSO as your authentication method, you will have to set sso for Authentication Method

For only showing specific labels, you can set yes for Do you want to only show specific labels?

$ beam configure
...
✔ Do you want to only show specific labels? · yes
✔ Label · env
✔ Add another label? · yes
✔ Label · application
✔ Add another label? · no

Pattern matching

If you want to select a specific profile, for a set of hostnames, that match a specific pattern, you can specify yes for Do you want to auto-select this profile, using a regex pattern on the hostname?

$ beam configure
Configuring profile dev-profile:
✔ Do you want to auto-select this profile, using a regex pattern on the hostname? · yes
✔ Regex Pattern for auto-selecting profile · \b(quality|staging)\b.*
...

Beam will then match any of the following hostnames:

• quality.app.example.com
• staging.app.example.com

In case there are be multiple profiles that have a matching pattern, Beam will select the profile with the lowest priority number. You can configure the priority number for each profile by adding a priority property to the profile in your profiles.toml file.
Profiles without a priority number will only be selected, if there is no other matching profile, having a priority defined.

If the hostname doesnt match any profile pattern, Beam will use the default profile.

Important: Beam will only use the proxy from the default profile, when running the beam command, as it does not know the hostname, before selecting it. When using the beam connect <hostname> command, Beam will use the hostname from the command line and is able to use the proxy from the profile.

Caching

By default Beam caches the list of nodes it receives from Teleport for 24 hours. To avoid using cache you can use the --clear-cache or -c flag:

$ beam -c

You can change the cache duration using the Cache TTL option. The following example will cache the list of nodes for 1 hour:

$ beam configure
...
✔ Cache TTL · 3600

Port forwarding

If you want to forward a specifc port to your localhost, you can add the following attributes to one of your profiles.

[profile.mysql]
...
enable_port_forwarding = true
listen_port = 3306
remote_host = "127.0.0.1"
remote_port = 3306

using this feature you could for example forward the port 3306 every time you connect to a node containing the word mysql. This would enable you to inspect a database running on the node using a database management desktop application

[profile.mysql]
default = false
proxy = "teleport.example.com"
username = "firstname.lastname"
auth = "sso"
cache_ttl = 86400
enable_port_forwarding = true
host_pattern = "(._mysql._)"
listen_port = 3306
remote_host = "127.0.0.1"
remote_port = 3306

Usage

A few useful Beam commands:

1. Opening a fuzzy finder view for selecting a host:

$ beam

2. Listing the names of all available nodes

$ beam list --format names
host1.example.com
host2.example.com

3. Directly connect to a host via its hostname

$ beam connect server.example.com

4. Manually selecting a profile to use

$ beam --profile myProfile

Search Syntax

Beam uses skim under the hood for its fuzzy search. The syntax for searching is the same as for skim. See skim for more information.

skim also supports the combination of tokens.

• Whitespace has the meaning of AND. With the term src main, skim will search for items that match both src and main.
• | means OR (note the spaces around |). With the term .md$ | .markdown$, skim will search for items ends with either .md or .markdown.
• OR has higher precedence. So readme .md$ | .markdown$ is grouped into readme AND (.md$ OR .markdown$).

Adding completions to your shell

In order to add completions to your shell, you can use one of the following commands:

$ beam completions zsh > ~/.zfunc/_beam

$ sudo apt install bash-completions
$ mkdir -p ~/.local/share/bash-completion/completions
$ beam completions bash > ~/.local/share/bash-completion/completions/beam

$ mkdir -p ~/.config/fish/completions
$ beam completions fish > ~/.config/fish/completions/beam.fish