package cli

import (

"bytes"

"context"

"encoding/json"

"errors"

"fmt"

"io"

"log"

"net"

"net/http"

"net/url"

"os"

"os/exec"

"path/filepath"

"regexp"

"slices"

"strings"

"sync"

"time"

"github.com/gen2brain/beeep"

"github.com/gofrs/flock"

"github.com/google/uuid"

"github.com/mattn/go-isatty"

"github.com/spf13/afero"

gossh "golang.org/x/crypto/ssh"

gosshagent "golang.org/x/crypto/ssh/agent"

"golang.org/x/term"

"golang.org/x/xerrors"

"gvisor.dev/gvisor/pkg/tcpip/adapters/gonet"

"tailscale.com/types/netlogtype"

"cdr.dev/slog/v3"

"cdr.dev/slog/v3/sloggers/sloghuman"

"github.com/coder/coder/v2/agent/agentssh"

"github.com/coder/coder/v2/cli/cliui"

"github.com/coder/coder/v2/cli/cliutil"

"github.com/coder/coder/v2/coderd/autobuild/notify"

"github.com/coder/coder/v2/coderd/util/maps"

"github.com/coder/coder/v2/coderd/util/ptr"

"github.com/coder/coder/v2/codersdk"

"github.com/coder/coder/v2/codersdk/workspacesdk"

"github.com/coder/coder/v2/cryptorand"

"github.com/coder/coder/v2/pty"

"github.com/coder/coder/v2/tailnet"

"github.com/coder/quartz"

"github.com/coder/retry"

"github.com/coder/serpent"

)

const (

disableUsageApp = "disable"

// Retry transient errors during SSH connection establishment.

sshRetryInterval = 2 * time.Second

sshMaxAttempts = 10 // initial + retries per step

)

var (

workspacePollInterval = time.Minute

autostopNotifyCountdown = []time.Duration{30 * time.Minute}

// gracefulShutdownTimeout is the timeout, per item in the stack of things to close

gracefulShutdownTimeout = 2 * time.Second

workspaceNameRe = regexp.MustCompile(`[/.]+|--`)

)

// isRetryableError checks for transient connection errors worth

// retrying: DNS failures, connection refused, and server 5xx.

func isRetryableError(err error) bool {

if err == nil || xerrors.Is(err, context.Canceled) {

return false

}

// Check connection errors before context.DeadlineExceeded because

// net.Dialer.Timeout produces *net.OpError that matches both.

if codersdk.IsConnectionError(err) {

return true

}

if xerrors.Is(err, context.DeadlineExceeded) {

return false

}

var sdkErr *codersdk.Error

if xerrors.As(err, &sdkErr) {

return sdkErr.StatusCode() >= 500

}

return false

}

// retryWithInterval calls fn up to maxAttempts times, waiting

// interval between attempts. Stops on success, non-retryable

// error, or context cancellation.

func retryWithInterval(ctx context.Context, logger slog.Logger, interval time.Duration, maxAttempts int, fn func() error) error {

var lastErr error

attempt := 0

for r := retry.New(interval, interval); r.Wait(ctx); {

lastErr = fn()

if lastErr == nil || !isRetryableError(lastErr) {

return lastErr

}

attempt++

if attempt >= maxAttempts {

break

}

logger.Warn(ctx, "transient error, retrying",

slog.Error(lastErr),

slog.F("attempt", attempt),

)

}

if lastErr != nil {

return lastErr

}

return ctx.Err()

}

func (r *RootCmd) ssh() *serpent.Command {

var (

stdio bool

tty bool

hostPrefix string

hostnameSuffix string

forceNewTunnel bool

forwardAgent bool

forwardGPG bool

identityAgent string

wsPollInterval time.Duration

waitEnum string

noWait bool

logDirPath string

remoteForwards []string

env []string

usageApp string

disableAutostart bool

networkInfoDir string

networkInfoInterval time.Duration

containerName string

containerUser string

)

cmd := &serpent.Command{

Annotations: workspaceCommand,

Use: "ssh <workspace> [command]",

Short: "Start a shell into a workspace or run a command",

Long: "This command does not have full parity with the standard SSH command. For users who need the full functionality of SSH, create an ssh configuration with `coder config-ssh`.\n\n" +

FormatExamples(

Example{

Description: "Use `--` to separate and pass flags directly to the command executed via SSH.",

Command: "coder ssh <workspace> -- ls -la",

},

),

Middleware: serpent.Chain(

// Require at least one arg for the workspace name

func(next serpent.HandlerFunc) serpent.HandlerFunc {

return func(i *serpent.Invocation) error {

got := len(i.Args)

if got < 1 {

return xerrors.New("expected the name of a workspace")

}

return next(i)

}

},

),

CompletionHandler: func(inv *serpent.Invocation) []string {

client, err := r.InitClient(inv)

if err != nil {

return []string{}

}

res, err := client.Workspaces(inv.Context(), codersdk.WorkspaceFilter{

Owner: codersdk.Me,

})

if err != nil {

return []string{}

}

var mu sync.Mutex

var completions []string

var wg sync.WaitGroup

for _, ws := range res.Workspaces {

wg.Add(1)

go func() {

defer wg.Done()

resources, err := client.TemplateVersionResources(inv.Context(), ws.LatestBuild.TemplateVersionID)

if err != nil {

return

}

var agents []codersdk.WorkspaceAgent

for _, resource := range resources {

agents = append(agents, resource.Agents...)

}

mu.Lock()

defer mu.Unlock()

if len(agents) == 1 {

completions = append(completions, ws.Name)

} else {

for _, agent := range agents {

completions = append(completions, fmt.Sprintf("%s.%s", ws.Name, agent.Name))

}

}

}()

}

wg.Wait()

slices.Sort(completions)

return completions

},

Handler: func(inv *serpent.Invocation) (retErr error) {

client, err := r.InitClient(inv)

if err != nil {

return err

}

appearanceConfig := initAppearance(inv.Context(), client)

wsClient := workspacesdk.New(client)

command := strings.Join(inv.Args[1:], " ")

// Before dialing the SSH server over TCP, capture Interrupt signals

// so that if we are interrupted, we have a chance to tear down the

// TCP session cleanly before exiting. If we don't, then the TCP

// session can persist for up to 72 hours, since we set a long

// timeout on the Agent side of the connection. In particular,

// OpenSSH sends SIGHUP to terminate a proxy command.

ctx, stop := inv.SignalNotifyContext(inv.Context(), StopSignals...)

defer stop()

ctx, cancel := context.WithCancel(ctx)

defer cancel()

// Prevent unnecessary logs from the stdlib from messing up the TTY.

// See: https://github.com/coder/coder/issues/13144

log.SetOutput(io.Discard)

logger := inv.Logger

defer func() {

if retErr != nil {

// catch and log all returned errors so we see them in the

// log file (if there is one)

logger.Error(ctx, "command exit", slog.Error(retErr))

}

}()

// In stdio mode, we can't allow any writes to stdin or stdout

// because they are used by the SSH protocol.

stdioReader, stdioWriter := inv.Stdin, inv.Stdout

if stdio {

inv.Stdin = stdioErrLogReader{inv.Logger}

inv.Stdout = inv.Stderr

}

// This WaitGroup solves for a race condition where we were logging

// while closing the log file in a defer. It probably solves

// others too.

var wg sync.WaitGroup

wg.Add(1)

defer wg.Done()

if logDirPath != "" {

nonce, err := cryptorand.StringCharset(cryptorand.Lower, 5)

if err != nil {

return xerrors.Errorf("generate nonce: %w", err)

}

logFileBaseName := fmt.Sprintf(

"coder-ssh-%s-%s",

// The time portion makes it easier to find the right

// log file.

time.Now().Format("20060102-150405"),

// The nonce prevents collisions, as SSH invocations

// frequently happen in parallel.

nonce,

)

if stdio {

// The VS Code extension obtains the PID of the SSH process to

// find the log file associated with a SSH session.

//

// We get the parent PID because it's assumed `ssh` is calling this

// command via the ProxyCommand SSH option.

logFileBaseName += fmt.Sprintf("-%d", os.Getppid())

}

logFileBaseName += ".log"

logFilePath := filepath.Join(logDirPath, logFileBaseName)

logFile, err := os.OpenFile(

logFilePath,

os.O_CREATE|os.O_APPEND|os.O_WRONLY|os.O_EXCL,

0o600,

)

if err != nil {

return xerrors.Errorf("error opening %s for logging: %w", logDirPath, err)

}

dc := cliutil.DiscardAfterClose(logFile)

go func() {

wg.Wait()

_ = dc.Close()

}()

logger = logger.AppendSinks(sloghuman.Sink(dc))

if r.verbose {

logger = logger.Leveled(slog.LevelDebug)

}

// log HTTP requests

client.SetLogger(logger)

}

stack := newCloserStack(ctx, logger, quartz.NewReal())

defer stack.close(nil)

for _, remoteForward := range remoteForwards {

isValid := validateRemoteForward(remoteForward)

if !isValid {

return xerrors.Errorf(`invalid format of remote-forward, expected: remote_port:local_address:local_port`)

}

if isValid && stdio {

return xerrors.Errorf(`remote-forward can't be enabled in the stdio mode`)

}

}

var parsedEnv [][2]string

for _, e := range env {

k, v, ok := strings.Cut(e, "=")

if !ok {

return xerrors.Errorf("invalid environment variable setting %q", e)

}

parsedEnv = append(parsedEnv, [2]string{k, v})

}

cliConfig := codersdk.SSHConfigResponse{

HostnamePrefix: hostPrefix,

HostnameSuffix: hostnameSuffix,

}

// Populated by the closure below.

var workspace codersdk.Workspace

var workspaceAgent codersdk.WorkspaceAgent

resolveWorkspace := func() error {

var err error

workspace, workspaceAgent, err = findWorkspaceAndAgentByHostname(

ctx, inv, client,

inv.Args[0], cliConfig, disableAutostart)

return err

}

if err := retryWithInterval(ctx, logger, sshRetryInterval, sshMaxAttempts, resolveWorkspace); err != nil {

return err

}

// Select the startup script behavior based on template configuration or flags.

var wait bool

switch waitEnum {

case "yes":

wait = true

case "no":

wait = false

case "auto":

for _, script := range workspaceAgent.Scripts {

if script.StartBlocksLogin {

wait = true

break

}

}

default:

return xerrors.Errorf("unknown wait value %q", waitEnum)

}

// The `--no-wait` flag is deprecated, but for now, check it.

if noWait {

wait = false

}

var templateVersion codersdk.TemplateVersion

fetchVersion := func() error {

var err error

templateVersion, err = client.TemplateVersion(ctx, workspace.LatestBuild.TemplateVersionID)

return err

}

if err := retryWithInterval(ctx, logger, sshRetryInterval, sshMaxAttempts, fetchVersion); err != nil {

return err

}

var unsupportedWorkspace bool

for _, warning := range templateVersion.Warnings {

if warning == codersdk.TemplateVersionWarningUnsupportedWorkspaces {

unsupportedWorkspace = true

break

}

}

if unsupportedWorkspace && isTTYErr(inv) {

_, _ = fmt.Fprintln(inv.Stderr, "👋 Your workspace uses legacy parameters which are not supported anymore. Contact your administrator for assistance.")

}

updateWorkspaceBanner, outdated := verifyWorkspaceOutdated(client, workspace)

if outdated && isTTYErr(inv) {

_, _ = fmt.Fprintln(inv.Stderr, updateWorkspaceBanner)

}

// OpenSSH passes stderr directly to the calling TTY.

// This is required in "stdio" mode so a connecting indicator can be displayed.

err = cliui.Agent(ctx, inv.Stderr, workspaceAgent.ID, cliui.AgentOptions{

FetchInterval: 0,

Fetch: client.WorkspaceAgent,

FetchLogs: client.WorkspaceAgentLogsAfter,

Wait: wait,

DocsURL: appearanceConfig.DocsURL,

})

if err != nil {

if xerrors.Is(err, context.Canceled) {

return cliui.ErrCanceled

}

return err

}

// If we're in stdio mode, check to see if we can use Coder Connect.

// We don't support Coder Connect over non-stdio coder ssh yet.

if stdio && !forceNewTunnel {

var connInfo workspacesdk.AgentConnectionInfo

if err := retryWithInterval(ctx, logger, sshRetryInterval, sshMaxAttempts, func() error {

var err error

connInfo, err = wsClient.AgentConnectionInfoGeneric(ctx)

return err

}); err != nil {

return xerrors.Errorf("get agent connection info: %w", err)

}

coderConnectHost := fmt.Sprintf("%s.%s.%s.%s",

workspaceAgent.Name, workspace.Name, workspace.OwnerName, connInfo.HostnameSuffix)

// Use trailing dot to indicate FQDN and prevent DNS

// search domain expansion, which can add 20-30s of

// delay on corporate networks with search domains

// configured.

exists, ccErr := workspacesdk.ExistsViaCoderConnect(ctx, coderConnectHost+".")

if ccErr != nil {

logger.Debug(ctx, "failed to check coder connect",

slog.F("hostname", coderConnectHost),

slog.Error(ccErr),

)

}

if exists {

defer cancel()

if networkInfoDir != "" {

if err := writeCoderConnectNetInfo(ctx, networkInfoDir); err != nil {

logger.Error(ctx, "failed to write coder connect net info file", slog.Error(err))

}

}

stopPolling := tryPollWorkspaceAutostop(ctx, client, workspace)

defer stopPolling()

usageAppName := getUsageAppName(usageApp)

if usageAppName != "" {

closeUsage := client.UpdateWorkspaceUsageWithBodyContext(ctx, workspace.ID, codersdk.PostWorkspaceUsageRequest{

AgentID: workspaceAgent.ID,

AppName: usageAppName,

})

defer closeUsage()

}

return runCoderConnectStdio(ctx, fmt.Sprintf("%s:22", coderConnectHost), stdioReader, stdioWriter, stack, logger)

}

}

if r.disableDirect {

_, _ = fmt.Fprintln(inv.Stderr, "Direct connections disabled.")

}

var conn workspacesdk.AgentConn

if err := retryWithInterval(ctx, logger, sshRetryInterval, sshMaxAttempts, func() error {

var err error

conn, err = wsClient.DialAgent(ctx, workspaceAgent.ID, &workspacesdk.DialAgentOptions{

Logger: logger,

BlockEndpoints: r.disableDirect,

EnableTelemetry: !r.disableNetworkTelemetry,

})

return err

}); err != nil {

return xerrors.Errorf("dial agent: %w", err)

}

if err = stack.push("agent conn", conn); err != nil {

_ = conn.Close()

return err

}

conn.AwaitReachable(ctx)

if containerName != "" {

cts, err := client.WorkspaceAgentListContainers(ctx, workspaceAgent.ID, nil)

if err != nil {

return xerrors.Errorf("list containers: %w", err)

}

if len(cts.Containers) == 0 {

cliui.Info(inv.Stderr, "No containers found!")

return nil

}

var found bool

for _, c := range cts.Containers {

if c.FriendlyName == containerName || c.ID == containerName {

found = true

break

}

}

if !found {

availableContainers := make([]string, len(cts.Containers))

for i, c := range cts.Containers {

availableContainers[i] = c.FriendlyName

}

cliui.Errorf(inv.Stderr, "Container not found: %q\nAvailable containers: %v", containerName, availableContainers)

return nil

}

}

stopPolling := tryPollWorkspaceAutostop(ctx, client, workspace)

defer stopPolling()

usageAppName := getUsageAppName(usageApp)

if usageAppName != "" {

closeUsage := client.UpdateWorkspaceUsageWithBodyContext(ctx, workspace.ID, codersdk.PostWorkspaceUsageRequest{

AgentID: workspaceAgent.ID,

AppName: usageAppName,

})

defer closeUsage()

}

if stdio {

rawSSH, err := conn.SSH(ctx)

if err != nil {

return xerrors.Errorf("connect SSH: %w", err)

}

copier := newRawSSHCopier(logger, rawSSH, stdioReader, stdioWriter)

if err = stack.push("rawSSHCopier", copier); err != nil {

return err

}

var errCh <-chan error

if networkInfoDir != "" {

errCh, err = setStatsCallback(ctx, conn, logger, networkInfoDir, networkInfoInterval)

if err != nil {

return err

}

}

wg.Add(1)

go func() {

defer wg.Done()

watchAndClose(ctx, func() error {

stack.close(xerrors.New("watchAndClose"))

return nil

}, logger, client, workspace, errCh)

}()

copier.copy(&wg)

return nil

}

sshClient, err := conn.SSHClient(ctx)

if err != nil {

return xerrors.Errorf("ssh client: %w", err)

}

if err = stack.push("ssh client", sshClient); err != nil {

return err

}

sshSession, err := sshClient.NewSession()

if err != nil {

return xerrors.Errorf("ssh session: %w", err)

}

if err = stack.push("sshSession", sshSession); err != nil {

return err

}

var errCh <-chan error

if networkInfoDir != "" {

errCh, err = setStatsCallback(ctx, conn, logger, networkInfoDir, networkInfoInterval)

if err != nil {

return err

}

}

wg.Add(1)

go func() {

defer wg.Done()

watchAndClose(

ctx,

func() error {

stack.close(xerrors.New("watchAndClose"))

return nil

},

logger,

client,

workspace,

errCh,

)

}()

if identityAgent == "" {

identityAgent = os.Getenv("SSH_AUTH_SOCK")

}

if forwardAgent && identityAgent != "" {

err = gosshagent.ForwardToRemote(sshClient, identityAgent)

if err != nil {

return xerrors.Errorf("forward agent: %w", err)

}

err = gosshagent.RequestAgentForwarding(sshSession)

if err != nil {

return xerrors.Errorf("request agent forwarding failed: %w", err)

}

}

if forwardGPG {

if workspaceAgent.OperatingSystem == "windows" {

return xerrors.New("GPG forwarding is not supported for Windows workspaces")

}

err = uploadGPGKeys(ctx, sshClient)

if err != nil {

return xerrors.Errorf("upload GPG public keys and ownertrust to workspace: %w", err)

}

closer, err := forwardGPGAgent(ctx, inv.Stderr, sshClient)

if err != nil {

return xerrors.Errorf("forward GPG socket: %w", err)

}

if err = stack.push("forwardGPGAgent", closer); err != nil {

return err

}

}

if len(remoteForwards) > 0 {

for _, remoteForward := range remoteForwards {

localAddr, remoteAddr, err := parseRemoteForward(remoteForward)

if err != nil {

return err

}

closer, err := sshRemoteForward(ctx, inv.Stderr, sshClient, localAddr, remoteAddr)

if err != nil {

return xerrors.Errorf("ssh remote forward: %w", err)

}

if err = stack.push("sshRemoteForward", closer); err != nil {

return err

}

}

}

// Command mode must not request a PTY by default. A PTY

// interposes line discipline on the remote stdin which would

// prevent EOF from propagating to commands that read until

// EOF (e.g. `cat`, `wc`, `tar`). Interactive shell sessions

// always need a PTY, and command mode can opt in via --tty.

requestPTY := command == "" || tty

stdinFile, validIn := inv.Stdin.(*os.File)

stdoutFile, validOut := inv.Stdout.(*os.File)

if requestPTY && validIn && validOut && isatty.IsTerminal(stdinFile.Fd()) && isatty.IsTerminal(stdoutFile.Fd()) {

inState, err := pty.MakeInputRaw(stdinFile.Fd())

if err != nil {

return err

}

defer func() {

_ = pty.RestoreTerminal(stdinFile.Fd(), inState)

}()

outState, err := pty.MakeOutputRaw(stdoutFile.Fd())

if err != nil {

return err

}

defer func() {

_ = pty.RestoreTerminal(stdoutFile.Fd(), outState)

}()

windowChange := listenWindowSize(ctx)

go func() {

for {

select {

case <-ctx.Done():

return

case <-windowChange:

}

width, height, err := term.GetSize(int(stdoutFile.Fd()))

if err != nil {

continue

}

_ = sshSession.WindowChange(height, width)

}

}()

}

for _, kv := range parsedEnv {

if err := sshSession.Setenv(kv[0], kv[1]); err != nil {

return xerrors.Errorf("setenv: %w", err)

}

}

if containerName != "" {

for k, v := range map[string]string{

agentssh.ContainerEnvironmentVariable: containerName,

agentssh.ContainerUserEnvironmentVariable: containerUser,

} {

if err := sshSession.Setenv(k, v); err != nil {

return xerrors.Errorf("setenv: %w", err)

}

}

}

sshSession.Stdin = inv.Stdin

sshSession.Stdout = inv.Stdout

sshSession.Stderr = inv.Stderr

if requestPTY {

err = sshSession.RequestPty("xterm-256color", 128, 128, gossh.TerminalModes{})

if err != nil {

return xerrors.Errorf("request pty: %w", err)

}

}

if command != "" {

err := sshSession.Run(command)

if err != nil {

if exitErr := (&gossh.ExitError{}); errors.As(err, &exitErr) {

// Preserve the remote command's exit status as the CLI

// exit code, but clear the error since it's not useful

// beyond reporting status.

return ExitError(exitErr.ExitStatus(), nil)

}

if missingErr := (&gossh.ExitMissingError{}); errors.As(err, &missingErr) {

return ExitError(255, xerrors.New("SSH connection ended unexpectedly"))

}

return xerrors.Errorf("run command: %w", err)

}

} else {

err = sshSession.Shell()

if err != nil {

return xerrors.Errorf("start shell: %w", err)

}

// Put cancel at the top of the defer stack to initiate

// shutdown of services.

defer cancel()

if validOut {

// Set initial window size.

width, height, err := term.GetSize(int(stdoutFile.Fd()))

if err == nil {

_ = sshSession.WindowChange(height, width)

}

}

err = sshSession.Wait()

conn.TailnetConn().SendDisconnectedTelemetry()

if err != nil {

if exitErr := (&gossh.ExitError{}); errors.As(err, &exitErr) {

// Clear the error since it's not useful beyond

// reporting status.

return ExitError(exitErr.ExitStatus(), nil)

}

// If the connection drops unexpectedly, we get an

// ExitMissingError but no other error details, so try to at

// least give the user a better message

if missingErr := (&gossh.ExitMissingError{}); errors.As(err, &missingErr) {

return ExitError(255, xerrors.New("SSH connection ended unexpectedly"))

}

return xerrors.Errorf("session ended: %w", err)

}

}

return nil

},

}

waitOption := serpent.Option{

Flag: "wait",

Env: "CODER_SSH_WAIT",

Description: "Specifies whether or not to wait for the startup script to finish executing. Auto means that the agent startup script behavior configured in the workspace template is used.",

Default: "auto",

Value: serpent.EnumOf(&waitEnum, "yes", "no", "auto"),

}

cmd.Options = serpent.OptionSet{

{

Flag: "stdio",

Env: "CODER_SSH_STDIO",

Description: "Specifies whether to emit SSH output over stdin/stdout.",

Value: serpent.BoolOf(&stdio),

},

{

Flag: "tty",

FlagShorthand: "t",

Env: "CODER_SSH_TTY",

Description: "Request a pseudo-terminal for the SSH session. Interactive shell sessions request one by default; command sessions do not unless this flag is set.",

Value: serpent.BoolOf(&tty),

},

{

Flag: "ssh-host-prefix",

Env: "CODER_SSH_SSH_HOST_PREFIX",

Description: "Strip this prefix from the provided hostname to determine the workspace name. This is useful when used as part of an OpenSSH proxy command.",

Value: serpent.StringOf(&hostPrefix),

},

{

Flag: "hostname-suffix",

Env: "CODER_SSH_HOSTNAME_SUFFIX",

Description: "Strip this suffix from the provided hostname to determine the workspace name. This is useful when used as part of an OpenSSH proxy command. The suffix must be specified without a leading . character.",

Value: serpent.StringOf(&hostnameSuffix),

},

{

Flag: "forward-agent",

FlagShorthand: "A",

Env: "CODER_SSH_FORWARD_AGENT",

Description: "Specifies whether to forward the SSH agent specified in $SSH_AUTH_SOCK.",

Value: serpent.BoolOf(&forwardAgent),

},

{

Flag: "forward-gpg",

FlagShorthand: "G",

Env: "CODER_SSH_FORWARD_GPG",

Description: "Specifies whether to forward the GPG agent. Unsupported on Windows workspaces, but supports all clients. Requires gnupg (gpg, gpgconf) on both the client and workspace. The GPG agent must already be running locally and will not be started for you. If a GPG agent is already running in the workspace, it will be attempted to be killed.",

Value: serpent.BoolOf(&forwardGPG),

},

{

Flag: "identity-agent",

Env: "CODER_SSH_IDENTITY_AGENT",

Description: "Specifies which identity agent to use (overrides $SSH_AUTH_SOCK), forward agent must also be enabled.",

Value: serpent.StringOf(&identityAgent),

},

{

Flag: "workspace-poll-interval",

Env: "CODER_WORKSPACE_POLL_INTERVAL",

Description: "Specifies how often to poll for workspace automated shutdown.",

Default: "1m",

Value: serpent.DurationOf(&wsPollInterval),

},

waitOption,

{

Flag: "no-wait",

Env: "CODER_SSH_NO_WAIT",

Description: "Enter workspace immediately after the agent has connected. This is the default if the template has configured the agent startup script behavior as non-blocking.",

Value: serpent.BoolOf(&noWait),

UseInstead: []serpent.Option{waitOption},

},

{

Flag: "log-dir",

Description: "Specify the directory containing SSH diagnostic log files.",

Env: "CODER_SSH_LOG_DIR",

FlagShorthand: "l",

Value: serpent.StringOf(&logDirPath),

},

{

Flag: "remote-forward",

Description: "Enable remote port forwarding (remote_port:local_address:local_port).",

Env: "CODER_SSH_REMOTE_FORWARD",

FlagShorthand: "R",

Value: serpent.StringArrayOf(&remoteForwards),

},

{

Flag: "env",

Description: "Set environment variable(s) for session (key1=value1,key2=value2,...).",

Env: "CODER_SSH_ENV",

FlagShorthand: "e",

Value: serpent.StringArrayOf(&env),

},

{

Flag: "usage-app",

Description: "Specifies the usage app to use for workspace activity tracking.",

Env: "CODER_SSH_USAGE_APP",

Value: serpent.StringOf(&usageApp),

Hidden: true,

},

{

Flag: "network-info-dir",

Description: "Specifies a directory to write network information periodically.",

Value: serpent.StringOf(&networkInfoDir),

},

{

Flag: "network-info-interval",

Description: "Specifies the interval to update network information.",

Default: "5s",

Value: serpent.DurationOf(&networkInfoInterval),

},

{

Flag: "container",

FlagShorthand: "c",

Description: "Specifies a container inside the workspace to connect to.",

Value: serpent.StringOf(&containerName),

Hidden: true, // Hidden until this features is at least in beta.

},

{

Flag: "container-user",

Description: "When connecting to a container, specifies the user to connect as.",

Value: serpent.StringOf(&containerUser),

Hidden: true, // Hidden until this features is at least in beta.

},

{

Flag: "force-new-tunnel",

Description: "Force the creation of a new tunnel to the workspace, even if the Coder Connect tunnel is available.",

Value: serpent.BoolOf(&forceNewTunnel),

Hidden: true,

},

sshDisableAutostartOption(serpent.BoolOf(&disableAutostart)),

}

return cmd

}

// findWorkspaceAndAgentByHostname parses the hostname from the commandline and finds the workspace and agent it

// corresponds to, taking into account any name prefixes or suffixes configured (e.g. myworkspace.coder, or

// vscode-coder--myusername--myworkspace).

func findWorkspaceAndAgentByHostname(

ctx context.Context, inv *serpent.Invocation, client *codersdk.Client,

hostname string, config codersdk.SSHConfigResponse, disableAutostart bool,

) (

codersdk.Workspace, codersdk.WorkspaceAgent, error,

) {

// for suffixes, we don't explicitly get the . and must add it. This is to ensure that the suffix is always

// interpreted as a dotted label in DNS names, not just any string suffix. That is, a suffix of 'coder' will

// match a hostname like 'en.coder', but not 'encoder'.

qualifiedSuffix := "." + config.HostnameSuffix

switch {

case config.HostnamePrefix != "" && strings.HasPrefix(hostname, config.HostnamePrefix):

hostname = strings.TrimPrefix(hostname, config.HostnamePrefix)

case config.HostnameSuffix != "" && strings.HasSuffix(hostname, qualifiedSuffix):

hostname = strings.TrimSuffix(hostname, qualifiedSuffix)

}

hostname = normalizeWorkspaceInput(hostname)

ws, agent, otherAgents, err := GetWorkspaceAndAgent(ctx, inv, client, !disableAutostart, hostname)

if err != nil && strings.Contains(err.Error(), "multiple agents found") {

var errorMsg strings.Builder

_, _ = errorMsg.WriteString(fmt.Sprintf("%s\nTry running:\n", err.Error()))

for _, agent := range otherAgents {

switch {

case config.HostnameSuffix != "":

_, _ = errorMsg.WriteString(fmt.Sprintf(" %s\n", cliui.Code(fmt.Sprintf("$ ssh %s.%s.%s.%s", agent.Name, ws.Name, ws.OwnerName, config.HostnameSuffix))))

case config.HostnamePrefix != "":

_, _ = errorMsg.WriteString(fmt.Sprintf(" %s\n", cliui.Code(fmt.Sprintf("$ ssh %s%s.%s.%s", config.HostnamePrefix, agent.Name, ws.Name, ws.OwnerName))))

default:

_, _ = errorMsg.WriteString(fmt.Sprintf(" %s\n", cliui.Code(fmt.Sprintf("$ ssh %s.%s.%s", agent.Name, ws.Name, ws.OwnerName))))

}

}

return ws, agent, xerrors.New(errorMsg.String())

}

return ws, agent, err

}

// watchAndClose ensures closer is called if the context is canceled or

// the workspace reaches the stopped state.

//

// Watching the stopped state is a work-around for cases

// where the agent is not gracefully shut down and the

// connection is left open. If, for instance, the networking

// is stopped before the agent is shut down, the disconnect

// will usually not propagate.

//

// See: https://github.com/coder/coder/issues/6180

func watchAndClose(ctx context.Context, closer func() error, logger slog.Logger, client *codersdk.Client, workspace codersdk.Workspace, errCh <-chan error) {

// Ensure session is ended on both context cancellation

// and workspace stop.

defer func() {

err := closer()

if err != nil {

logger.Error(ctx, "error closing session", slog.Error(err))

}

}()

startWatchLoop:

for {

logger.Debug(ctx, "connecting to the coder server to watch workspace events")

var wsWatch <-chan codersdk.Workspace

var err error

for r := retry.New(time.Second, 15*time.Second); r.Wait(ctx); {

wsWatch, err = client.WatchWorkspace(ctx, workspace.ID)

if err == nil {

break

}

if ctx.Err() != nil {

logger.Debug(ctx, "context expired", slog.Error(ctx.Err()))

return

}

}

for {

select {

case <-ctx.Done():

logger.Debug(ctx, "context expired", slog.Error(ctx.Err()))

return

case w, ok := <-wsWatch:

if !ok {

continue startWatchLoop

}

// Transitioning to stop or delete could mean that

// the agent will still gracefully stop. If a new

// build is starting, there's no reason to wait for

// the agent, it should be long gone.

if workspace.LatestBuild.ID != w.LatestBuild.ID && w.LatestBuild.Transition == codersdk.WorkspaceTransitionStart {

logger.Info(ctx, "new build started")

return

}

// Note, we only react to the stopped state here because we

// want to give the agent a chance to gracefully shut down

// during "stopping".

if w.LatestBuild.Status == codersdk.WorkspaceStatusStopped {

logger.Info(ctx, "workspace stopped")

return

}

case err := <-errCh:

logger.Error(ctx, "failed to collect network stats", slog.Error(err))

return

}

}

}

}

// GetWorkspaceAndAgent returns the workspace and agent selected using either the

// `<workspace>[.<agent>]` syntax via `in`. It will also return any other agents