Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .nextchanges/cli/sandbox-ssh-setup.md
Original file line number Diff line number Diff line change
@@ -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))
1 change: 1 addition & 0 deletions acceptance/cmd/sandbox/ssh-setup/out.test.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Cloud = false
25 changes: 25 additions & 0 deletions acceptance/cmd/sandbox/ssh-setup/output.txt
Original file line number Diff line number Diff line change
@@ -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
7 changes: 7 additions & 0 deletions acceptance/cmd/sandbox/ssh-setup/script
Original file line number Diff line number Diff line change
@@ -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
9 changes: 9 additions & 0 deletions acceptance/cmd/sandbox/ssh-setup/test.toml
Original file line number Diff line number Diff line change
@@ -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"}}'''
43 changes: 43 additions & 0 deletions cmd/sandbox/README.md
Original file line number Diff line number Diff line change
@@ -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.
1 change: 1 addition & 0 deletions cmd/sandbox/sandbox.go
Original file line number Diff line number Diff line change
Expand Up @@ -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())
Expand Down
98 changes: 98 additions & 0 deletions cmd/sandbox/ssh_setup.go
Original file line number Diff line number Diff line change
@@ -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
}
38 changes: 38 additions & 0 deletions cmd/sandbox/ssh_setup_test.go
Original file line number Diff line number Diff line change
@@ -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")
}
9 changes: 7 additions & 2 deletions experimental/ssh/internal/sshconfig/sshconfig.go
Original file line number Diff line number Diff line change
Expand Up @@ -220,19 +220,24 @@ func PromptRecreateConfig(ctx context.Context, hostName string) (bool, error) {
// `ssh setup --name <alias> --cluster <id>`: 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)
}
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)
}
1 change: 1 addition & 0 deletions experimental/ssh/internal/sshconfig/sshconfig_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
68 changes: 68 additions & 0 deletions experimental/ssh/sandbox/config.go
Original file line number Diff line number Diff line change
@@ -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), "%", "%%")
}
Loading
Loading