Improve tctl user experience

zmb3 commented 4 months ago

There are several aspects of tctl that are confusing to newcomers. tctl doesn't offer any sort of login command. It operates in two different modes:

Remote mode: by picking up existing credentials after a tsh login
Local mode: when run directly on the auth server

The first item confuses people because you have log in with one tool in order to use another tool. This is unintuitive, and the software provides no visibility into what's happening.

The second item is confusing because it only works by default if there's a /etc/teleport.yaml and if that file has the auth service enabled. If your config is stored in a non-standard location, you need to set TELEPORT_CONFIG_FILE or pass the --config flag.

This is compounded by the fact that most people aren't aware that local mode is a thing and they unintentionally trigger that behavior by simply pasting a tctl command from our docs. The software doesn't tell you that it's making an assumption that the auth server is running locally, and it doesn't give you a clear actionable error - you typically see some sort of permissions issue because your user doesn't have permissions to read /var/lib.

Some ideas for things we can do to improve the situation:

Add an explicit tctl login command. It could even be interactive - if we detect that the auth server is running locally we can offer local admin mode as an option, otherwise we can reuse the same prompts from tsh login.
Make sure it's clear when local admin mode is activated, and make sure the error message explains what's wrong (get rid of the unclear filesystem permissions error).
Update tctl status to show information about the current credentials (local admin mode, remote profile, or completely unauthenticated)

strideynet commented 4 months ago

Just for additional context - in "remote mode", we also support credentials being provided with --identity-file when using Machine ID.

webvictim commented 3 months ago

Also, tctl is missing a --proxy-server flag - --auth_server works, but is confusingly named.

gravitational / teleport

Improve tctl user experience #44428