Skip to content

Commit 4c9fc89

Browse files
flowzone-app[bot]flowzone-app[bot]
authored
Merge pull request #2871 from balena-io/ssh-to-device-ssh
Add alias `device ssh` for `ssh` command
2 parents 69d8208 + 9b1eb57 commit 4c9fc89

21 files changed

+183
-176
lines changed

‎INSTALL-ADVANCED.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -145,7 +145,7 @@ container) in order to allow npm scripts like `postinstall` to be executed.
145145

146146
## Additional Dependencies
147147

148-
The `balena ssh`, `device detect`, `build`, `deploy` and `preload` commands may require
148+
The `balena device ssh`, `device detect`, `build`, `deploy` and `preload` commands may require
149149
additional software to be installed. Check the Additional Dependencies sections for each operating
150150
system:
151151

‎INSTALL-LINUX.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -61,13 +61,13 @@ instructions](https://docs.docker.com/install/overview/) to install Docker on th
6161
workstation as the balena CLI. The [advanced installation
6262
options](./INSTALL-ADVANCED.md#additional-dependencies) document describes other possibilities.
6363

64-
### balena ssh
64+
### balena device ssh
6565

66-
The `balena ssh` command requires the `ssh` command-line tool to be available. Most Linux
66+
The `balena device ssh` command requires the `ssh` command-line tool to be available. Most Linux
6767
distributions will already have it installed. Otherwise, `sudo apt-get install openssh-client`
6868
should do the trick on Debian or Ubuntu.
6969

70-
The `balena ssh` command also requires an SSH key to be added to your balena account: see [SSH
70+
The `balena device ssh` command also requires an SSH key to be added to your balena account: see [SSH
7171
Access documentation](https://www.balena.io/docs/learn/manage/ssh-access/). The `balena key*`
7272
command set can also be used to list and manage SSH keys: see `balena help -v`.
7373

‎INSTALL-MAC.md

+4-4
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ Selected operating system: **macOS**
1919
- On the terminal prompt, type `balena version` and hit Enter. It should display
2020
the version of the balena CLI that you have installed.
2121

22-
No further steps are required to run most CLI commands. The `balena ssh`, `build`, `deploy`
22+
No further steps are required to run most CLI commands. The `balena device ssh`, `build`, `deploy`
2323
and `preload` commands may require additional software to be installed, as described
2424
in the next section.
2525

@@ -41,9 +41,9 @@ instructions](https://docs.docker.com/install/overview/) to install Docker on th
4141
workstation as the balena CLI. The [advanced installation
4242
options](./INSTALL-ADVANCED.md#additional-dependencies) document describes other possibilities.
4343

44-
### balena ssh
44+
### balena device ssh
4545

46-
The `balena ssh` command requires the `ssh` command-line tool to be available. To check whether
46+
The `balena device ssh` command requires the `ssh` command-line tool to be available. To check whether
4747
it is already installed, run `ssh` on a Terminal window. If it is not yet installed, the options
4848
include:
4949

@@ -52,7 +52,7 @@ include:
5252
Components → Command Line Tools → Install.
5353
* Or, install [Homebrew](https://brew.sh/), then `brew install openssh`
5454

55-
The `balena ssh` command also requires an SSH key to be added to your balena account: see [SSH
55+
The `balena device ssh` command also requires an SSH key to be added to your balena account: see [SSH
5656
Access documentation](https://www.balena.io/docs/learn/manage/ssh-access/). The `balena key*`
5757
command set can also be used to list and manage SSH keys: see `balena help -v`.
5858

‎INSTALL-WINDOWS.md

+4-4
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ Selected operating system: **Windows**
1919
- On the command prompt, type `balena version` and hit Enter. It should display
2020
the version of the balena CLI that you have installed.
2121

22-
No further steps are required to run most CLI commands. The `balena ssh`, `device detect`, `build`,
22+
No further steps are required to run most CLI commands. The `balena device ssh`, `device detect`, `build`,
2323
`deploy` and `preload` commands may require additional software to be installed, as
2424
described below.
2525

@@ -34,17 +34,17 @@ instructions](https://docs.docker.com/install/overview/) to install Docker on th
3434
workstation as the balena CLI. The [advanced installation
3535
options](./INSTALL-ADVANCED.md#additional-dependencies) document describes other possibilities.
3636

37-
### balena ssh
37+
### balena device ssh
3838

39-
The `balena ssh` command requires the `ssh` command-line tool to be available. Microsoft started
39+
The `balena device ssh` command requires the `ssh` command-line tool to be available. Microsoft started
4040
distributing an SSH client with Windows 10, which is automatically installed through Windows
4141
Update. To check whether it is installed, run `ssh` on a Windows Command Prompt or PowerShell. It
4242
can also be [manually
4343
installed](https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse)
4444
if needed. For older versions of Windows, there are several ssh/OpenSSH clients provided by 3rd
4545
parties.
4646

47-
The `balena ssh` command also requires an SSH key to be added to your balena account: see [SSH
47+
The `balena device ssh` command also requires an SSH key to be added to your balena account: see [SSH
4848
Access documentation](https://www.balena.io/docs/learn/manage/ssh-access/). The `balena key*`
4949
command set can also be used to list and manage SSH keys: see `balena help -v`.
5050

‎README.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -88,9 +88,9 @@ HTTP(S) proxies can be configured through any of the following methods, in prece
8888
* The `HTTPS_PROXY` and/or `HTTP_PROXY` environment variables, in the same URL format as
8989
`BALENARC_PROXY`.
9090

91-
### Proxy setup for balena ssh
91+
### Proxy setup for balena device ssh
9292

93-
In order to work behind a proxy server, the `balena ssh` command requires the
93+
In order to work behind a proxy server, the `balena device ssh` command requires the
9494
[`proxytunnel`](http://proxytunnel.sourceforge.net/) package (command-line tool) to be installed.
9595
`proxytunnel` is available for Linux distributions like Ubuntu/Debian (`apt install proxytunnel`),
9696
and for macOS through [Homebrew](https://brew.sh/). Windows support is limited to the [Windows
@@ -110,7 +110,7 @@ The `BALENARC_NO_PROXY` variable may be used to exclude specified destinations f
110110
> * This feature requires CLI version 11.30.8 or later. In the case of the npm [installation
111111
> option](https://github.com/balena-io/balena-cli/blob/master/INSTALL.md), it also requires
112112
> Node.js version 10.16.0 or later.
113-
> * To exclude a `balena ssh` target from proxying (IP address or `.local` hostname), the
113+
> * To exclude a `balena device ssh` target from proxying (IP address or `.local` hostname), the
114114
> `--noproxy` option should be specified in addition to the `BALENARC_NO_PROXY` variable.
115115

116116
By default (if `BALENARC_NO_PROXY` is not defined), all [private IPv4

‎TROUBLESHOOTING.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -79,10 +79,10 @@ Try resetting the ownership by running:
7979
$ sudo chown -R <user> $HOME/.balena
8080
```
8181

82-
## Broken line wrapping / cursor behavior with `balena ssh`
82+
## Broken line wrapping / cursor behavior with `balena device ssh`
8383

8484
Users sometimes come across broken line wrapping or cursor behavior in text terminals, for example
85-
when long command lines are typed in a `balena ssh` session, or when using text editors like `vim`
85+
when long command lines are typed in a `balena device ssh` session, or when using text editors like `vim`
8686
or `nano`. This is not something specific to the balena CLI, being also a commonly reported issue
8787
with standard remote terminal tools like `ssh` or `telnet`. It is often a remote shell
8888
configuration issue (files like `/etc/profile`, `~/.bash_profile`, `~/.bash_login`, `~/.profile`

‎automation/capitanodoc/capitanodoc.ts

-1
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,6 @@ const commandHeadings: { [key: string]: string } = {
6161
organization: 'Organizations',
6262
os: 'OS',
6363
util: 'Utilities',
64-
ssh: 'Network',
6564
tunnel: 'Network',
6665
build: 'Deploy',
6766
join: 'Platform',

‎completion/_balena

+2-2
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,13 @@ _balena() {
88
local context state line curcontext="$curcontext"
99

1010
# Valid top-level completions
11-
main_commands=( api-key app block build config deploy device devices env fleet internal join leave local login logout notes organization os preload push release settings ssh ssh-key support tag tunnel util version whoami )
11+
main_commands=( api-key app block build config deploy device devices env fleet internal join leave local login logout notes organization os preload push release settings ssh-key support tag tunnel util version whoami )
1212
# Sub-completions
1313
api_key_cmds=( generate list revoke )
1414
app_cmds=( create )
1515
block_cmds=( create )
1616
config_cmds=( generate inject read reconfigure write )
17-
device_cmds=( deactivate detect identify init list local-mode logs move os-update pin public-url purge reboot register rename restart rm shutdown start-service stop-service track-fleet )
17+
device_cmds=( deactivate detect identify init list local-mode logs move os-update pin public-url purge reboot register rename restart rm shutdown ssh start-service stop-service track-fleet )
1818
devices_cmds=( supported )
1919
env_cmds=( add list rename rm )
2020
fleet_cmds=( create list pin purge rename restart rm track-latest )

‎completion/balena-completion.bash

+2-2
Original file line numberDiff line numberDiff line change
@@ -7,13 +7,13 @@ _balena_complete()
77
local cur prev
88

99
# Valid top-level completions
10-
main_commands="api-key app block build config deploy device devices env fleet internal join leave local login logout notes organization os preload push release settings ssh ssh-key support tag tunnel util version whoami"
10+
main_commands="api-key app block build config deploy device devices env fleet internal join leave local login logout notes organization os preload push release settings ssh-key support tag tunnel util version whoami"
1111
# Sub-completions
1212
api_key_cmds="generate list revoke"
1313
app_cmds="create"
1414
block_cmds="create"
1515
config_cmds="generate inject read reconfigure write"
16-
device_cmds="deactivate detect identify init list local-mode logs move os-update pin public-url purge reboot register rename restart rm shutdown start-service stop-service track-fleet"
16+
device_cmds="deactivate detect identify init list local-mode logs move os-update pin public-url purge reboot register rename restart rm shutdown ssh start-service stop-service track-fleet"
1717
devices_cmds="supported"
1818
env_cmds="add list rename rm"
1919
fleet_cmds="create list pin purge rename restart rm track-latest"

‎docs/balena-cli.md

+78-71
Original file line numberDiff line numberDiff line change
@@ -81,9 +81,9 @@ HTTP(S) proxies can be configured through any of the following methods, in prece
8181
* The `HTTPS_PROXY` and/or `HTTP_PROXY` environment variables, in the same URL format as
8282
`BALENARC_PROXY`.
8383

84-
### Proxy setup for balena ssh
84+
### Proxy setup for balena device ssh
8585

86-
In order to work behind a proxy server, the `balena ssh` command requires the
86+
In order to work behind a proxy server, the `balena device ssh` command requires the
8787
[`proxytunnel`](http://proxytunnel.sourceforge.net/) package (command-line tool) to be installed.
8888
`proxytunnel` is available for Linux distributions like Ubuntu/Debian (`apt install proxytunnel`),
8989
and for macOS through [Homebrew](https://brew.sh/). Windows support is limited to the [Windows
@@ -103,7 +103,7 @@ The `BALENARC_NO_PROXY` variable may be used to exclude specified destinations f
103103
> * This feature requires CLI version 11.30.8 or later. In the case of the npm [installation
104104
> option](https://github.com/balena-io/balena-cli/blob/master/INSTALL.md), it also requires
105105
> Node.js version 10.16.0 or later.
106-
> * To exclude a `balena ssh` target from proxying (IP address or `.local` hostname), the
106+
> * To exclude a `balena device ssh` target from proxying (IP address or `.local` hostname), the
107107
> `--noproxy` option should be specified in addition to the `BALENARC_NO_PROXY` variable.
108108

109109
By default (if `BALENARC_NO_PROXY` is not defined), all [private IPv4
@@ -214,6 +214,7 @@ are encouraged to regularly update the balena CLI to the latest version.
214214
- [device restart](#device-restart)
215215
- [device rm](#device-rm)
216216
- [device shutdown](#device-shutdown)
217+
- [device ssh](#device-ssh)
217218
- [device start-service](#device-start-service)
218219
- [device stop-service](#device-stop-service)
219220
- [device track-fleet](#device-track-fleet)
@@ -245,7 +246,6 @@ are encouraged to regularly update the balena CLI to the latest version.
245246

246247
- Network
247248

248-
- [ssh](#ssh)
249249
- [tunnel](#tunnel)
250250

251251
- Notes
@@ -1903,6 +1903,80 @@ the uuid of the device to shutdown
19031903

19041904
force action if the update lock is set
19051905

1906+
## device ssh
1907+
1908+
### Aliases
1909+
1910+
- `ssh`
1911+
1912+
1913+
To use one of the aliases, replace `device ssh` with the alias.
1914+
1915+
### Description
1916+
1917+
Start a shell on a local or remote device. If a service name is not provided,
1918+
a shell will be opened on the host OS.
1919+
1920+
If a fleet is provided, an interactive menu will be presented for the selection
1921+
of an online device. A shell will then be opened for the host OS or service
1922+
container of the chosen device.
1923+
1924+
For local devices, the IP address and .local domain name are supported.
1925+
If the device is referenced by IP or `.local` address, the connection
1926+
is initiated directly to balenaOS on port `22222` via an
1927+
openssh-compatible client. Otherwise, any connection initiated remotely
1928+
traverses the balenaCloud VPN.
1929+
1930+
Commands may be piped to the standard input for remote execution (see examples).
1931+
Note however that remote command execution on service containers (as opposed to
1932+
the host OS) is not currently possible when a device UUID is used (instead of
1933+
an IP address) because of a balenaCloud backend limitation.
1934+
1935+
Note: `balena ssh` requires an openssh-compatible client to be correctly
1936+
installed in your shell environment. For more information (including Windows
1937+
support) please check:
1938+
https://github.com/balena-io/balena-cli/blob/master/INSTALL.md#additional-dependencies,
1939+
1940+
Examples:
1941+
1942+
$ balena device ssh MyFleet
1943+
$ balena device ssh f49cefd
1944+
$ balena device ssh f49cefd my-service
1945+
$ balena device ssh f49cefd --port <port>
1946+
$ balena device ssh 192.168.0.1 --verbose
1947+
$ balena device ssh f49cefd.local my-service
1948+
$ echo "uptime; exit;" | balena device ssh f49cefd
1949+
$ echo "uptime; exit;" | balena device ssh 192.168.0.1 myService
1950+
1951+
### Arguments
1952+
1953+
#### FLEETORDEVICE
1954+
1955+
fleet name/slug, device uuid, or address of local device
1956+
1957+
#### SERVICE
1958+
1959+
service name, if connecting to a container
1960+
1961+
### Options
1962+
1963+
#### -p, --port PORT
1964+
1965+
SSH server port number (default 22222) if the target is an IP address or .local
1966+
hostname. Otherwise, port number for the balenaCloud gateway (default 22).
1967+
1968+
#### -t, --tty
1969+
1970+
force pseudo-terminal allocation (bypass TTY autodetection for stdin)
1971+
1972+
#### -v, --verbose
1973+
1974+
increase verbosity
1975+
1976+
#### --noproxy
1977+
1978+
bypass global proxy configuration for the ssh connection
1979+
19061980
## device start-service
19071981

19081982
### Description
@@ -2635,73 +2709,6 @@ answer "yes" to all questions (non interactive use)
26352709

26362710
# Network
26372711

2638-
## ssh
2639-
2640-
### Description
2641-
2642-
Start a shell on a local or remote device. If a service name is not provided,
2643-
a shell will be opened on the host OS.
2644-
2645-
If a fleet is provided, an interactive menu will be presented for the selection
2646-
of an online device. A shell will then be opened for the host OS or service
2647-
container of the chosen device.
2648-
2649-
For local devices, the IP address and .local domain name are supported.
2650-
If the device is referenced by IP or `.local` address, the connection
2651-
is initiated directly to balenaOS on port `22222` via an
2652-
openssh-compatible client. Otherwise, any connection initiated remotely
2653-
traverses the balenaCloud VPN.
2654-
2655-
Commands may be piped to the standard input for remote execution (see examples).
2656-
Note however that remote command execution on service containers (as opposed to
2657-
the host OS) is not currently possible when a device UUID is used (instead of
2658-
an IP address) because of a balenaCloud backend limitation.
2659-
2660-
Note: `balena ssh` requires an openssh-compatible client to be correctly
2661-
installed in your shell environment. For more information (including Windows
2662-
support) please check:
2663-
https://github.com/balena-io/balena-cli/blob/master/INSTALL.md#additional-dependencies,
2664-
2665-
Examples:
2666-
2667-
$ balena ssh MyFleet
2668-
$ balena ssh f49cefd
2669-
$ balena ssh f49cefd my-service
2670-
$ balena ssh f49cefd --port <port>
2671-
$ balena ssh 192.168.0.1 --verbose
2672-
$ balena ssh f49cefd.local my-service
2673-
$ echo "uptime; exit;" | balena ssh f49cefd
2674-
$ echo "uptime; exit;" | balena ssh 192.168.0.1 myService
2675-
2676-
### Arguments
2677-
2678-
#### FLEETORDEVICE
2679-
2680-
fleet name/slug, device uuid, or address of local device
2681-
2682-
#### SERVICE
2683-
2684-
service name, if connecting to a container
2685-
2686-
### Options
2687-
2688-
#### -p, --port PORT
2689-
2690-
SSH server port number (default 22222) if the target is an IP address or .local
2691-
hostname. Otherwise, port number for the balenaCloud gateway (default 22).
2692-
2693-
#### -t, --tty
2694-
2695-
force pseudo-terminal allocation (bypass TTY autodetection for stdin)
2696-
2697-
#### -v, --verbose
2698-
2699-
increase verbosity
2700-
2701-
#### --noproxy
2702-
2703-
bypass global proxy configuration for the ssh connection
2704-
27052712
## tunnel
27062713

27072714
### Description

‎src/commands/ssh/index.ts ‎src/commands/device/ssh.ts

+12-10
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,9 @@ import {
2323
validateLocalHostnameOrIp,
2424
} from '../../utils/validation';
2525

26-
export default class SshCmd extends Command {
26+
export default class DeviceSSHCmd extends Command {
27+
public static aliases = ['ssh'];
28+
2729
public static description = stripIndent`
2830
Open a SSH prompt on a device's host OS or service container.
2931
@@ -52,14 +54,14 @@ export default class SshCmd extends Command {
5254
`;
5355

5456
public static examples = [
55-
'$ balena ssh MyFleet',
56-
'$ balena ssh f49cefd',
57-
'$ balena ssh f49cefd my-service',
58-
'$ balena ssh f49cefd --port <port>',
59-
'$ balena ssh 192.168.0.1 --verbose',
60-
'$ balena ssh f49cefd.local my-service',
61-
'$ echo "uptime; exit;" | balena ssh f49cefd',
62-
'$ echo "uptime; exit;" | balena ssh 192.168.0.1 myService',
57+
'$ balena device ssh MyFleet',
58+
'$ balena device ssh f49cefd',
59+
'$ balena device ssh f49cefd my-service',
60+
'$ balena device ssh f49cefd --port <port>',
61+
'$ balena device ssh 192.168.0.1 --verbose',
62+
'$ balena device ssh f49cefd.local my-service',
63+
'$ echo "uptime; exit;" | balena device ssh f49cefd',
64+
'$ echo "uptime; exit;" | balena device ssh 192.168.0.1 myService',
6365
];
6466

6567
public static args = {
@@ -104,7 +106,7 @@ export default class SshCmd extends Command {
104106
public static offlineCompatible = true;
105107

106108
public async run() {
107-
const { args: params, flags: options } = await this.parse(SshCmd);
109+
const { args: params, flags: options } = await this.parse(DeviceSSHCmd);
108110

109111
// Local connection
110112
if (validateLocalHostnameOrIp(params.fleetOrDevice)) {

0 commit comments

Comments
 (0)