diff --git a/.nextchanges/cli/sandbox-ssh-setup.md b/.nextchanges/cli/sandbox-ssh-setup.md new file mode 100644 index 00000000000..6bf7df4faf0 --- /dev/null +++ b/.nextchanges/cli/sandbox-ssh-setup.md @@ -0,0 +1 @@ +* Add `databricks sandbox ssh-setup` to configure native SSH and SCP through sandbox port forwarding. ([#7590](https://github.com/databricks/cli/pull/7590)) diff --git a/acceptance/cmd/sandbox/ssh-setup/out.test.toml b/acceptance/cmd/sandbox/ssh-setup/out.test.toml new file mode 100644 index 00000000000..18b1a88417e --- /dev/null +++ b/acceptance/cmd/sandbox/ssh-setup/out.test.toml @@ -0,0 +1 @@ +Cloud = false diff --git a/acceptance/cmd/sandbox/ssh-setup/output.txt b/acceptance/cmd/sandbox/ssh-setup/output.txt new file mode 100644 index 00000000000..05a2d723fc5 --- /dev/null +++ b/acceptance/cmd/sandbox/ssh-setup/output.txt @@ -0,0 +1,25 @@ + +>>> [CLI] sandbox ssh-setup test --name my-sandbox --profile sandbox-test --releases-dir [TEST_TMP_DIR]/releases +Created SSH configuration at [TEST_TMP_DIR]/.databricks/ssh-tunnel-configs/my-sandbox. Connect with 'ssh my-sandbox' or 'scp ./file my-sandbox:/tmp/file'. + +>>> [CLI] sandbox ssh-setup test --name my-sandbox --profile sandbox-test --releases-dir [TEST_TMP_DIR]/releases +Created SSH configuration at [TEST_TMP_DIR]/.databricks/ssh-tunnel-configs/my-sandbox. Connect with 'ssh my-sandbox' or 'scp ./file my-sandbox:/tmp/file'. + +>>> cat [TEST_TMP_DIR]/.ssh/config +Include "[TEST_TMP_DIR]/.databricks/ssh-tunnel-configs/*" + +>>> cat [TEST_TMP_DIR]/.databricks/ssh-tunnel-configs/my-sandbox + +Host my-sandbox + User sandbox-agent + ConnectTimeout 900 + ServerAliveInterval 30 + StrictHostKeyChecking yes + UserKnownHostsFile "[TEST_TMP_DIR]/.databricks/ssh-tunnel-known-hosts/[SSH_IDENTITY]" + HostKeyAlias [SSH_IDENTITY] + IdentitiesOnly yes + IdentityFile "[TEST_TMP_DIR]/.databricks/ssh-tunnel-keys/[SSH_IDENTITY]/id_ed25519" + ProxyCommand [CLI] sandbox ssh sandboxes/test --proxy --profile sandbox-test --releases-dir [TEST_TMP_DIR]/releases --ssh-identity [SSH_IDENTITY] --ssh-config-file [TEST_TMP_DIR]/databrickscfg + +>>> musterr [CLI] sandbox ssh-setup test --name ../escape +Error: SSH host alias must contain only letters, numbers, dots, underscores or hyphens diff --git a/acceptance/cmd/sandbox/ssh-setup/script b/acceptance/cmd/sandbox/ssh-setup/script new file mode 100644 index 00000000000..09addb9a52c --- /dev/null +++ b/acceptance/cmd/sandbox/ssh-setup/script @@ -0,0 +1,7 @@ +export DATABRICKS_CONFIG_FILE="$TEST_TMP_DIR/databrickscfg" +printf '[sandbox-test]\nhost = %s\ntoken = %s\n' "$DATABRICKS_HOST" "$DATABRICKS_TOKEN" > "$DATABRICKS_CONFIG_FILE" +trace $CLI sandbox ssh-setup test --name my-sandbox --profile sandbox-test --releases-dir "$TEST_TMP_DIR/releases" +trace $CLI sandbox ssh-setup test --name my-sandbox --profile sandbox-test --releases-dir "$TEST_TMP_DIR/releases" +trace cat "$TEST_TMP_DIR/.ssh/config" +trace cat "$TEST_TMP_DIR/.databricks/ssh-tunnel-configs/my-sandbox" +trace musterr $CLI sandbox ssh-setup test --name ../escape diff --git a/acceptance/cmd/sandbox/ssh-setup/test.toml b/acceptance/cmd/sandbox/ssh-setup/test.toml new file mode 100644 index 00000000000..828d29a4795 --- /dev/null +++ b/acceptance/cmd/sandbox/ssh-setup/test.toml @@ -0,0 +1,9 @@ +Ignore = ["databrickscfg"] + +[[Repls]] +Old = 'sandbox-[0-9a-f]{64}' +New = '[SSH_IDENTITY]' + +[[Server]] +Pattern = "GET /api/2.0/sandboxes/test" +Response.Body = '''{"name":"sandboxes/test","status":{"state":"SANDBOX_STATE_STOPPED"}}''' diff --git a/cmd/sandbox/README.md b/cmd/sandbox/README.md new file mode 100644 index 00000000000..7d5ec717f85 --- /dev/null +++ b/cmd/sandbox/README.md @@ -0,0 +1,43 @@ +# SSH through sandbox port forwarding + +Run `databricks sandbox ssh SANDBOX_ID` for an interactive shell, or pass a +remote command after `--`. This creates a reusable local SSH key automatically +and connects through workspace-authenticated WebSocket port forwarding. +It does not write a persistent SSH Host entry. + +For native SSH tools, configure a local alias once: + +```sh +databricks sandbox ssh-setup SANDBOX_ID --name my-sandbox --profile my-workspace +ssh my-sandbox +scp ./example.txt my-sandbox:/tmp/example.txt +sftp my-sandbox +``` + +Keep the Databricks CLI installed at the path recorded in the generated +`ProxyCommand`, with the saved Databricks profile and its credentials available. +Setup requires a named profile; environment-only credentials do not create a +persistent workspace selection. The proxy prepares the +sandbox and connects through port forwarding for each SSH connection. Run setup +again after relocating the executable or changing the selected workspace. + +The local machine needs OpenSSH. The sandbox needs Python 3, `ssh-keygen`, and +`openssh-server`, with the unprivileged `sandbox-agent` account configured to +accept public-key authentication. The CLI uploads and invokes its server +automatically; no relay needs to be included in the image. +For development builds on macOS or Windows, provide `--releases-dir` containing +Linux release archives built from the same checkout. + +The private client key remains on the local machine. Public-key entries expire +after 24 hours and are renewed during connection setup. The sandbox's persistent +HOME stores its server key and public-key entries, allowing reuse after restart. +Each proxy invocation starts and cleans up its own remote server command. A +server abandoned by its client exits after its idle timeout. A broken forwarding +connection ends the SSH session; reconnect to start another one. +The CLI allows up to ten minutes to prepare the remote server, including sandbox +startup and executable upload. The SSH handshake allows fifteen minutes overall, +including workspace authentication. Neither timeout limits an established session. + +These commands require workspace support for sandbox HTTP/WebSocket port +forwarding. They do not connect to the legacy Gateway SSH endpoint or register +keys with its registry. diff --git a/cmd/sandbox/sandbox.go b/cmd/sandbox/sandbox.go index 8974225af09..0743ec543fa 100644 --- a/cmd/sandbox/sandbox.go +++ b/cmd/sandbox/sandbox.go @@ -36,6 +36,7 @@ Common workflows: cmd.AddCommand(newSSHKeyCommand()) cmd.AddCommand(newSetDefaultCommand()) cmd.AddCommand(newSSHCommand()) + cmd.AddCommand(newSSHSetupCommand()) cmd.AddCommand(newListCommand()) cmd.AddCommand(newCreateCommand()) cmd.AddCommand(newDeleteCommand()) diff --git a/cmd/sandbox/ssh_setup.go b/cmd/sandbox/ssh_setup.go new file mode 100644 index 00000000000..e214918e7f1 --- /dev/null +++ b/cmd/sandbox/ssh_setup.go @@ -0,0 +1,98 @@ +package sandbox + +import ( + "errors" + "fmt" + "os" + "path/filepath" + "strings" + + "github.com/databricks/cli/cmd/root" + sshtunnel "github.com/databricks/cli/experimental/ssh/sandbox" + "github.com/databricks/cli/libs/cmdctx" + "github.com/databricks/cli/libs/cmdio" + "github.com/databricks/databricks-sdk-go/config" + "github.com/spf13/cobra" +) + +func newSSHSetupCommand() *cobra.Command { + var alias, sshConfig, releasesDir string + var overwrite bool + cmd := &cobra.Command{ + Use: "ssh-setup [sandbox-id]", Short: "Configure native SSH tools for a sandbox", + Long: `Create a local SSH Host entry for native ssh, scp, sftp, and tools that use SSH. + +The CLI creates or reuses a local key. On each connection, the generated +ProxyCommand prepares the sandbox and opens authenticated WebSocket port forwarding. +Pass --profile with a named Databricks profile so later connections select the same workspace. +Databricks CLI and that profile's credentials must remain available locally. + +Examples: + databricks sandbox ssh-setup happy-panda-1234 --name my-sandbox --profile my-workspace + ssh my-sandbox + scp ./example.txt my-sandbox:/tmp/example.txt + +Interactive 'databricks sandbox ssh' works without this setup step.`, + Args: cobra.MaximumNArgs(1), + PreRunE: func(cmd *cobra.Command, args []string) error { + cmd.SetContext(root.SkipLoadBundle(cmd.Context())) + return root.MustWorkspaceClient(cmd, args) + }, + ValidArgsFunction: completeSandboxIDs, + RunE: func(cmd *cobra.Command, args []string) error { + if err := sshtunnel.ValidateHostAlias(alias); err != nil { + return err + } + ctx := cmd.Context() + profileFlag := cmd.Flag("profile") + if profileFlag == nil || !profileFlag.Changed || profileFlag.Value.String() == "" { + return errors.New("ssh-setup requires a named Databricks profile; run 'databricks auth login --profile NAME' and rerun with --profile NAME") + } + w := cmdctx.WorkspaceClient(ctx) + requested := "" + if len(args) == 1 { + requested = args[0] + } + name, err := resolveSSHName(ctx, w, requested) + if err != nil { + return err + } + identity, err := prepareSSHIdentity(ctx, w, name) + if err != nil { + return err + } + executable, err := os.Executable() + if err != nil { + return err + } + options := sshProxyOptions{Profile: w.Config.Profile, ReleasesDir: releasesDir, IdentityScope: identity.HostKeyAlias} + if w.Config.ConfigFile != "" { + file, err := config.LoadFile(w.Config.ConfigFile) + if err != nil { + return fmt.Errorf("load SSH profile configuration: %w", err) + } + options.ConfigFile, err = filepath.Abs(file.Path()) + if err != nil { + return fmt.Errorf("resolve SSH profile configuration path: %w", err) + } + options.ConfigFile = filepath.ToSlash(options.ConfigFile) + } + proxy, err := sshProxyCommand(executable, name, options) + if err != nil { + return err + } + location, err := sshtunnel.WriteHostConfig(ctx, alias, sshConfig, proxy, identity, overwrite) + if err != nil { + return err + } + cmdio.LogString(ctx, fmt.Sprintf("Created SSH configuration at %s. Connect with 'ssh %s' or 'scp ./file %s:/tmp/file'.", strings.ReplaceAll(location, `\`, "/"), alias, alias)) + return nil + }, + } + cmd.Flags().StringVar(&alias, "name", "", "Local SSH host alias") + cmd.MarkFlagRequired("name") + cmd.Flags().StringVar(&sshConfig, "ssh-config", "", "Path to SSH config file (default ~/.ssh/config)") + cmd.Flags().StringVar(&releasesDir, "releases-dir", "", "Directory containing version-matched Linux CLI archives") + cmd.Flags().BoolVar(&overwrite, "overwrite", false, "Replace an existing managed SSH host entry") + return cmd +} diff --git a/cmd/sandbox/ssh_setup_test.go b/cmd/sandbox/ssh_setup_test.go new file mode 100644 index 00000000000..6316a4cd14b --- /dev/null +++ b/cmd/sandbox/ssh_setup_test.go @@ -0,0 +1,38 @@ +package sandbox + +import ( + "io" + "net/http" + "net/http/httptest" + "testing" + + "github.com/databricks/cli/libs/cmdctx" + "github.com/databricks/databricks-sdk-go" + "github.com/stretchr/testify/require" +) + +func TestSSHSetupRequiresLiteralAlias(t *testing.T) { + cmd := newSSHSetupCommand() + cmd.PreRunE = nil + cmd.SetArgs([]string{"id", "--name", "../escape"}) + require.ErrorContains(t, cmd.ExecuteContext(t.Context()), "SSH host alias") + cmd = newSSHSetupCommand() + cmd.PreRunE = nil + cmd.SetArgs([]string{"id"}) + require.ErrorContains(t, cmd.ExecuteContext(t.Context()), "required flag") +} + +func TestSSHSetupRequiresPersistentWorkspaceSelection(t *testing.T) { + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + _, _ = io.WriteString(w, `{}`) + })) + defer server.Close() + w, err := databricks.NewWorkspaceClient(&databricks.Config{Host: server.URL, Token: "test-token"}) + require.NoError(t, err) + cmd := newSSHSetupCommand() + cmd.PreRunE = nil + cmd.SetOut(io.Discard) + cmd.SetErr(io.Discard) + cmd.SetArgs([]string{"id", "--name", "test"}) + require.ErrorContains(t, cmd.ExecuteContext(cmdctx.SetWorkspaceClient(t.Context(), w)), "requires a named Databricks profile") +} diff --git a/experimental/ssh/internal/sshconfig/sshconfig.go b/experimental/ssh/internal/sshconfig/sshconfig.go index ff9ad9ad69e..65fbeaeb4c8 100644 --- a/experimental/ssh/internal/sshconfig/sshconfig.go +++ b/experimental/ssh/internal/sshconfig/sshconfig.go @@ -220,6 +220,11 @@ func PromptRecreateConfig(ctx context.Context, hostName string) (bool, error) { // `ssh setup --name --cluster `: without it ssh would look the key up under the // alias, find no matching entry, and fail strict host key checking (DECO-27882). func GenerateHostConfig(hostName, userName, identityFile, knownHostsFile, hostKeyAlias, proxyCommand string) string { + return GenerateHostConfigWithTimeout(hostName, userName, identityFile, knownHostsFile, hostKeyAlias, proxyCommand, 360) +} + +// GenerateHostConfigWithTimeout supports proxies that enforce their own startup timeout. +func GenerateHostConfigWithTimeout(hostName, userName, identityFile, knownHostsFile, hostKeyAlias, proxyCommand string, connectTimeoutSeconds int) string { hostKeyAliasLine := "" if hostKeyAlias != "" { hostKeyAliasLine = fmt.Sprintf(" HostKeyAlias %s\n", hostKeyAlias) @@ -227,12 +232,12 @@ func GenerateHostConfig(hostName, userName, identityFile, knownHostsFile, hostKe return fmt.Sprintf(` Host %s User %s - ConnectTimeout 360 + ConnectTimeout %d ServerAliveInterval %d StrictHostKeyChecking yes UserKnownHostsFile %q %s IdentitiesOnly yes IdentityFile %q ProxyCommand %s -`, hostName, userName, ServerAliveIntervalSeconds, knownHostsFile, hostKeyAliasLine, identityFile, proxyCommand) +`, hostName, userName, connectTimeoutSeconds, ServerAliveIntervalSeconds, knownHostsFile, hostKeyAliasLine, identityFile, proxyCommand) } diff --git a/experimental/ssh/internal/sshconfig/sshconfig_test.go b/experimental/ssh/internal/sshconfig/sshconfig_test.go index 7d7f695b12a..ef66957b61c 100644 --- a/experimental/ssh/internal/sshconfig/sshconfig_test.go +++ b/experimental/ssh/internal/sshconfig/sshconfig_test.go @@ -17,6 +17,7 @@ func TestGenerateHostConfigSetsServerAliveInterval(t *testing.T) { // `ssh setup` and `--ide` reach ssh through this block and nothing else, so the option has to // be in it. assert.Contains(t, config, fmt.Sprintf("\n ServerAliveInterval %d\n", ServerAliveIntervalSeconds)) + assert.Contains(t, config, "\n ConnectTimeout 360\n") // The interval has to fire well inside the ~8 minute reap window, and ServerAliveCountMax // (OpenSSH default 3) intervals have to outlast the longest legitimate pause on a healthy diff --git a/experimental/ssh/sandbox/config.go b/experimental/ssh/sandbox/config.go new file mode 100644 index 00000000000..bd8bfcfe885 --- /dev/null +++ b/experimental/ssh/sandbox/config.go @@ -0,0 +1,68 @@ +package sandbox + +import ( + "context" + "errors" + "fmt" + "io/fs" + "os" + "path/filepath" + "strings" + + "github.com/databricks/cli/experimental/ssh/internal/sshconfig" +) + +// ValidateHostAlias restricts the alias to a literal host and a portable file name. +func ValidateHostAlias(alias string) error { + if alias == "" || alias[0] == '-' || alias == "." || alias == ".." || strings.HasSuffix(alias, ".") { + return fmt.Errorf("invalid SSH host alias %q", alias) + } + for _, character := range alias { + if (character < 'a' || character > 'z') && (character < 'A' || character > 'Z') && (character < '0' || character > '9') && !strings.ContainsRune("._-", character) { + return errors.New("SSH host alias must contain only letters, numbers, dots, underscores or hyphens") + } + } + stem := strings.ToUpper(strings.SplitN(alias, ".", 2)[0]) + switch stem { + case "CON", "PRN", "AUX", "NUL", "COM1", "COM2", "COM3", "COM4", "COM5", "COM6", "COM7", "COM8", "COM9", "LPT1", "LPT2", "LPT3", "LPT4", "LPT5", "LPT6", "LPT7", "LPT8", "LPT9": + return fmt.Errorf("SSH host alias %q is a reserved file name", alias) + } + return nil +} + +// WriteHostConfig reuses compute SSH's Include directory and host-block writer. +// Existing aliases require an explicit overwrite unless the content is unchanged. +func WriteHostConfig(ctx context.Context, alias, mainConfig, proxyCommand string, identity *Identity, overwrite bool) (string, error) { + if err := ValidateHostAlias(alias); err != nil { + return "", err + } + config := sshconfig.GenerateHostConfigWithTimeout(alias, "sandbox-agent", escapeSSHPath(identity.KeyPath), escapeSSHPath(identity.KnownHostsPath), identity.HostKeyAlias, proxyCommand, 900) + destination, err := sshconfig.GetHostConfigPath(ctx, alias) + if err != nil { + return "", err + } + existing, err := os.ReadFile(destination) + if err != nil && !errors.Is(err, fs.ErrNotExist) { + return "", err + } + if err == nil && string(existing) != config && !overwrite { + return "", fmt.Errorf("SSH host alias %q already exists; choose another --name or pass --overwrite", alias) + } + mainConfig, err = sshconfig.GetMainConfigPathOrDefault(ctx, mainConfig) + if err != nil { + return "", err + } + if err := sshconfig.EnsureIncludeDirective(ctx, mainConfig); err != nil { + return "", err + } + if string(existing) != config { + if _, err := sshconfig.CreateOrUpdateHostConfig(ctx, alias, config, true); err != nil { + return "", err + } + } + return destination, nil +} + +func escapeSSHPath(value string) string { + return strings.ReplaceAll(filepath.ToSlash(value), "%", "%%") +} diff --git a/experimental/ssh/sandbox/config_test.go b/experimental/ssh/sandbox/config_test.go new file mode 100644 index 00000000000..834e7e9c23f --- /dev/null +++ b/experimental/ssh/sandbox/config_test.go @@ -0,0 +1,74 @@ +package sandbox_test + +import ( + "os" + "os/exec" + "path/filepath" + "runtime" + "strings" + "testing" + + "github.com/databricks/cli/experimental/ssh/sandbox" + "github.com/databricks/cli/libs/env" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestWriteHostConfigPreservesUnrelatedConfig(t *testing.T) { + home := t.TempDir() + ctx := env.WithUserHomeDir(t.Context(), home) + mainConfig := filepath.Join(home, ".ssh", "config") + require.NoError(t, os.MkdirAll(filepath.Dir(mainConfig), 0o700)) + original := "Host existing\n HostName existing.test\n" + require.NoError(t, os.WriteFile(mainConfig, []byte(original), 0o600)) + identity := &sandbox.Identity{KeyPath: filepath.Join(home, "private key"), KnownHostsPath: filepath.Join(home, "known hosts"), HostKeyAlias: "sandbox-identity"} + filename, err := sandbox.WriteHostConfig(ctx, "my-sandbox", mainConfig, "databricks sandbox ssh sandboxes/test --proxy", identity, false) + require.NoError(t, err) + config, err := os.ReadFile(filename) + require.NoError(t, err) + assert.Contains(t, string(config), "Host my-sandbox") + assert.Contains(t, string(config), "User sandbox-agent") + assert.Contains(t, string(config), "ConnectTimeout 900") + assert.Contains(t, string(config), "HostKeyAlias sandbox-identity") + assert.Contains(t, string(config), "StrictHostKeyChecking yes") + assert.Contains(t, string(config), "ProxyCommand databricks sandbox ssh sandboxes/test --proxy") + _, err = sandbox.WriteHostConfig(ctx, "my-sandbox", mainConfig, "databricks sandbox ssh sandboxes/test --proxy", identity, false) + require.NoError(t, err) + main, err := os.ReadFile(mainConfig) + require.NoError(t, err) + assert.Equal(t, 1, strings.Count(string(main), "Include ")) + assert.Contains(t, string(main), original) + _, err = sandbox.WriteHostConfig(ctx, "my-sandbox", mainConfig, "different proxy", identity, false) + require.ErrorContains(t, err, "already exists") + unchanged, err := os.ReadFile(filename) + require.NoError(t, err) + assert.Equal(t, config, unchanged) + _, err = sandbox.WriteHostConfig(ctx, "my-sandbox", mainConfig, "different proxy", identity, true) + require.NoError(t, err) + changed, err := os.ReadFile(filename) + require.NoError(t, err) + assert.Contains(t, string(changed), "ProxyCommand different proxy") + if ssh, err := exec.LookPath("ssh"); err == nil { + if runtime.GOOS == "windows" { + // Git Bash's ssh does not resolve Windows drive paths in Include directives. + ssh, err = exec.LookPath(filepath.Join(os.Getenv("SystemRoot"), "System32", "OpenSSH", "ssh.exe")) + require.NoError(t, err) + } + output, err := exec.CommandContext(t.Context(), ssh, "-G", "-F", mainConfig, "my-sandbox").CombinedOutput() + require.NoError(t, err, string(output)) + assert.Contains(t, string(output), "user sandbox-agent") + assert.Contains(t, string(output), "proxycommand different proxy") + } +} + +func TestInvalidHostAliasesCannotWriteConfig(t *testing.T) { + home := t.TempDir() + ctx := env.WithUserHomeDir(t.Context(), home) + for _, alias := range []string{"", "../escape", "a/b", "-flag", "host *", "host\nHost *", "CON", "com1.txt", "trailing.", "a%h"} { + _, err := sandbox.WriteHostConfig(ctx, alias, "", "proxy", &sandbox.Identity{}, true) + require.Error(t, err, alias) + } + entries, err := os.ReadDir(home) + require.NoError(t, err) + assert.Empty(t, entries) +}