From e3dc846f09ef17f50893f4f8ee8ff76ac079c4f0 Mon Sep 17 00:00:00 2001 From: myarmolinsky Date: Thu, 26 Sep 2024 12:38:51 -0400 Subject: [PATCH] Deprecate `tunnel` command in favor of `device tunnel` Change-type: patch --- TROUBLESHOOTING.md | 2 +- automation/capitanodoc/capitanodoc.ts | 1 - completion/_balena | 4 +- completion/balena-completion.bash | 4 +- docs/balena-cli.md | 109 +++++++++--------- src/commands/device/tunnel.ts | 16 +-- src/help.ts | 1 - tests/commands/help.spec.ts | 2 +- .../pkg/expected-warnings-darwin-arm64.txt | 2 +- .../pkg/expected-warnings-darwin-x64.txt | 2 +- .../pkg/expected-warnings-linux-arm64.txt | 2 +- .../pkg/expected-warnings-linux-x64.txt | 2 +- .../pkg/expected-warnings-win32-x64.txt | 2 +- 13 files changed, 71 insertions(+), 78 deletions(-) diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md index 75a52eb445..c26b7cd28a 100644 --- a/TROUBLESHOOTING.md +++ b/TROUBLESHOOTING.md @@ -31,7 +31,7 @@ command again. Check whether the SD card is locked (a physical switch on the side of the card). -## I get `connect ETIMEDOUT` with `balena tunnel` +## I get `connect ETIMEDOUT` with `balena device tunnel` Please update the CLI to the latest version. This issue was fixed in v12.38.5. For more details, see: https://github.com/balena-io/balena-cli/issues/2172 diff --git a/automation/capitanodoc/capitanodoc.ts b/automation/capitanodoc/capitanodoc.ts index 9ce749dd37..92f95fb4ad 100644 --- a/automation/capitanodoc/capitanodoc.ts +++ b/automation/capitanodoc/capitanodoc.ts @@ -61,7 +61,6 @@ const commandHeadings: { [key: string]: string } = { organization: 'Organizations', os: 'OS', util: 'Utilities', - tunnel: 'Network', build: 'Deploy', join: 'Platform', leave: 'Platform', diff --git a/completion/_balena b/completion/_balena index 3e8620ad67..eb23b8c391 100644 --- a/completion/_balena +++ b/completion/_balena @@ -8,13 +8,13 @@ _balena() { local context state line curcontext="$curcontext" # Valid top-level completions - 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 ) + 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 util version whoami ) # Sub-completions api_key_cmds=( generate list revoke ) app_cmds=( create ) block_cmds=( create ) config_cmds=( generate inject read reconfigure write ) - 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 ) + 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 tunnel ) devices_cmds=( supported ) env_cmds=( list rename rm set ) fleet_cmds=( create list pin purge rename restart rm track-latest ) diff --git a/completion/balena-completion.bash b/completion/balena-completion.bash index e9774f06b7..c8a02e99e5 100644 --- a/completion/balena-completion.bash +++ b/completion/balena-completion.bash @@ -7,13 +7,13 @@ _balena_complete() local cur prev # Valid top-level completions - 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" + 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 util version whoami" # Sub-completions api_key_cmds="generate list revoke" app_cmds="create" block_cmds="create" config_cmds="generate inject read reconfigure write" - 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" + 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 tunnel" devices_cmds="supported" env_cmds="list rename rm set" fleet_cmds="create list pin purge rename restart rm track-latest" diff --git a/docs/balena-cli.md b/docs/balena-cli.md index 73eb4cdc8e..d7d0a1eb86 100644 --- a/docs/balena-cli.md +++ b/docs/balena-cli.md @@ -218,6 +218,7 @@ are encouraged to regularly update the balena CLI to the latest version. - [device start-service <uuid>](#device-start-service-uuid) - [device stop-service <uuid>](#device-stop-service-uuid) - [device track-fleet <uuid>](#device-track-fleet-uuid) + - [device tunnel <deviceorfleet>](#device-tunnel-deviceorfleet) - [devices supported](#devices-supported) - Environment Variables @@ -244,10 +245,6 @@ are encouraged to regularly update the balena CLI to the latest version. - [local configure <target>](#local-configure-target) - [local flash <image>](#local-flash-image) -- Network - - - [tunnel <deviceorfleet>](#tunnel-deviceorfleet) - - Notes - [note <|note>](#note-note) @@ -1936,6 +1933,57 @@ the uuid of the device to make track the fleet's release ### Options +## device tunnel <deviceOrFleet> + +Use this command to open local TCP ports that tunnel to listening sockets in a +balenaOS device. + +For example, this command could be used to expose the ssh server of a balenaOS +device (port number 22222) on the local machine, or to expose a web server +running on the device. The port numbers do not have be the same between the +device and the local machine, and multiple ports may be tunneled in a single +command line. + +Port mappings are specified in the format: [:[localIP:]localPort] +localIP defaults to 'localhost', and localPort defaults to the specified +remotePort value. + +Note: the -p (--port) flag must be provided at the end of the command line, +as per examples. + +In the case of openBalena, the tunnel command in CLI v12.38.5 or later requires +openBalena v3.1.2 or later. Older CLI versions work with older openBalena +versions. + +Examples: + + # map remote port 22222 to localhost:22222 + $ balena device tunnel myFleet -p 22222 + + # map remote port 22222 to localhost:222 + $ balena device tunnel 2ead211 -p 22222:222 + + # map remote port 22222 to any address on your host machine, port 22222 + $ balena device tunnel 1546690 -p 22222:0.0.0.0 + + # map remote port 22222 to any address on your host machine, port 222 + $ balena device tunnel myFleet -p 22222:0.0.0.0:222 + + # multiple port tunnels can be specified at any one time + $ balena device tunnel myFleet -p 8080:3000 -p 8081:9000 + +### Arguments + +#### DEVICEORFLEET + +device UUID or fleet name/slug + +### Options + +#### -p, --port PORT + +port mapping in the format [:[localIP:]localPort] + ## devices supported List the supported device types (like 'raspberrypi3' or 'intel-nuc'). @@ -2550,59 +2598,6 @@ Check `balena util available-drives` for available options. answer "yes" to all questions (non interactive use) -# Network - -## tunnel <deviceOrFleet> - -Use this command to open local TCP ports that tunnel to listening sockets in a -balenaOS device. - -For example, this command could be used to expose the ssh server of a balenaOS -device (port number 22222) on the local machine, or to expose a web server -running on the device. The port numbers do not have be the same between the -device and the local machine, and multiple ports may be tunneled in a single -command line. - -Port mappings are specified in the format: [:[localIP:]localPort] -localIP defaults to 'localhost', and localPort defaults to the specified -remotePort value. - -Note: the -p (--port) flag must be provided at the end of the command line, -as per examples. - -In the case of openBalena, the tunnel command in CLI v12.38.5 or later requires -openBalena v3.1.2 or later. Older CLI versions work with older openBalena -versions. - -Examples: - - # map remote port 22222 to localhost:22222 - $ balena tunnel myFleet -p 22222 - - # map remote port 22222 to localhost:222 - $ balena tunnel 2ead211 -p 22222:222 - - # map remote port 22222 to any address on your host machine, port 22222 - $ balena tunnel 1546690 -p 22222:0.0.0.0 - - # map remote port 22222 to any address on your host machine, port 222 - $ balena tunnel myFleet -p 22222:0.0.0.0:222 - - # multiple port tunnels can be specified at any one time - $ balena tunnel myFleet -p 8080:3000 -p 8081:9000 - -### Arguments - -#### DEVICEORFLEET - -device UUID or fleet name/slug - -### Options - -#### -p, --port PORT - -port mapping in the format [:[localIP:]localPort] - # Notes ## note <|note> diff --git a/src/commands/device/tunnel.ts b/src/commands/device/tunnel.ts index 91be2fe603..9a1cb7df1c 100644 --- a/src/commands/device/tunnel.ts +++ b/src/commands/device/tunnel.ts @@ -28,7 +28,7 @@ import { lowercaseIfSlug } from '../../utils/normalization'; import type { Server, Socket } from 'net'; -export default class TunnelCmd extends Command { +export default class DeviceTunnelCmd extends Command { public static description = stripIndent` Tunnel local ports to your balenaOS device. @@ -55,19 +55,19 @@ export default class TunnelCmd extends Command { public static examples = [ '# map remote port 22222 to localhost:22222', - '$ balena tunnel myFleet -p 22222', + '$ balena device tunnel myFleet -p 22222', '', '# map remote port 22222 to localhost:222', - '$ balena tunnel 2ead211 -p 22222:222', + '$ balena device tunnel 2ead211 -p 22222:222', '', '# map remote port 22222 to any address on your host machine, port 22222', - '$ balena tunnel 1546690 -p 22222:0.0.0.0', + '$ balena device tunnel 1546690 -p 22222:0.0.0.0', '', '# map remote port 22222 to any address on your host machine, port 222', - '$ balena tunnel myFleet -p 22222:0.0.0.0:222', + '$ balena device tunnel myFleet -p 22222:0.0.0.0:222', '', '# multiple port tunnels can be specified at any one time', - '$ balena tunnel myFleet -p 8080:3000 -p 8081:9000', + '$ balena device tunnel myFleet -p 8080:3000 -p 8081:9000', ]; public static args = { @@ -78,7 +78,7 @@ export default class TunnelCmd extends Command { }), }; - public static usage = 'tunnel '; + public static usage = 'device tunnel '; public static flags = { port: Flags.string({ @@ -94,7 +94,7 @@ export default class TunnelCmd extends Command { public static authenticated = true; public async run() { - const { args: params, flags: options } = await this.parse(TunnelCmd); + const { args: params, flags: options } = await this.parse(DeviceTunnelCmd); const logger = await Command.getLogger(); const sdk = getBalenaSdk(); diff --git a/src/help.ts b/src/help.ts index 14a18433fb..32e5db6bdb 100644 --- a/src/help.ts +++ b/src/help.ts @@ -225,7 +225,6 @@ See: https://git.io/JRHUW#deprecation-policy`, 'push', 'fleet', 'device', - 'tunnel', 'preload', 'build', 'deploy', diff --git a/tests/commands/help.spec.ts b/tests/commands/help.spec.ts index 3d04102faa..93218cb81c 100644 --- a/tests/commands/help.spec.ts +++ b/tests/commands/help.spec.ts @@ -30,7 +30,6 @@ PRIMARY COMMANDS push start a remote build on the balenaCloud build servers or a local mode device app display information about a single application device show info about a single device - tunnel tunnel local ports to your balenaOS device preload preload an app on a disk image (or Edison zip archive) build [source] build a project locally deploy [image] deploy a single image or a multicontainer project to a balena application @@ -64,6 +63,7 @@ ADDITIONAL COMMANDS device shutdown shutdown a device device ssh [service] SSH into the host or application container of a device devices supported list the supported device types (like 'raspberrypi3' or 'intel-nuc') + device tunnel tunnel local ports to your balenaOS device env set [value] add or update env or config variable to application(s), device(s) or service(s) env list list the environment or config variables of an application, device or service env rename change the value of a config or env var for an app, device or service diff --git a/tests/test-data/pkg/expected-warnings-darwin-arm64.txt b/tests/test-data/pkg/expected-warnings-darwin-arm64.txt index e3a26cedf9..d85e159a2b 100644 --- a/tests/test-data/pkg/expected-warnings-darwin-arm64.txt +++ b/tests/test-data/pkg/expected-warnings-darwin-arm64.txt @@ -228,7 +228,7 @@ %2: build/commands/tag/set.js > Warning Entry 'main' not found in %1 %1: node_modules/@oclif/core/package.json - %2: build/commands/tunnel/index.js + %2: build/commands/device/tunnel.js > Warning Entry 'main' not found in %1 %1: node_modules/@oclif/core/package.json %2: build/commands/version/index.js diff --git a/tests/test-data/pkg/expected-warnings-darwin-x64.txt b/tests/test-data/pkg/expected-warnings-darwin-x64.txt index b02d3adebe..0a0f3262b3 100644 --- a/tests/test-data/pkg/expected-warnings-darwin-x64.txt +++ b/tests/test-data/pkg/expected-warnings-darwin-x64.txt @@ -228,7 +228,7 @@ %2: build/commands/tag/set.js > Warning Entry 'main' not found in %1 %1: node_modules/@oclif/core/package.json - %2: build/commands/tunnel/index.js + %2: build/commands/device/tunnel.js > Warning Entry 'main' not found in %1 %1: node_modules/@oclif/core/package.json %2: build/commands/version/index.js diff --git a/tests/test-data/pkg/expected-warnings-linux-arm64.txt b/tests/test-data/pkg/expected-warnings-linux-arm64.txt index 21d6675c43..ff3717cadf 100644 --- a/tests/test-data/pkg/expected-warnings-linux-arm64.txt +++ b/tests/test-data/pkg/expected-warnings-linux-arm64.txt @@ -228,7 +228,7 @@ %2: build/commands/tag/set.js > Warning Entry 'main' not found in %1 %1: node_modules/@oclif/core/package.json - %2: build/commands/tunnel/index.js + %2: build/commands/device/tunnel.js > Warning Entry 'main' not found in %1 %1: node_modules/@oclif/core/package.json %2: build/commands/version/index.js diff --git a/tests/test-data/pkg/expected-warnings-linux-x64.txt b/tests/test-data/pkg/expected-warnings-linux-x64.txt index cfec54a296..458db620a7 100644 --- a/tests/test-data/pkg/expected-warnings-linux-x64.txt +++ b/tests/test-data/pkg/expected-warnings-linux-x64.txt @@ -228,7 +228,7 @@ %2: build/commands/tag/set.js > Warning Entry 'main' not found in %1 %1: node_modules/@oclif/core/package.json - %2: build/commands/tunnel/index.js + %2: build/commands/device/tunnel.js > Warning Entry 'main' not found in %1 %1: node_modules/@oclif/core/package.json %2: build/commands/version/index.js diff --git a/tests/test-data/pkg/expected-warnings-win32-x64.txt b/tests/test-data/pkg/expected-warnings-win32-x64.txt index f2987bad57..12d1e6f329 100644 --- a/tests/test-data/pkg/expected-warnings-win32-x64.txt +++ b/tests/test-data/pkg/expected-warnings-win32-x64.txt @@ -228,7 +228,7 @@ %2: build\commands\tag\set.js > Warning Entry 'main' not found in %1 %1: node_modules\@oclif\core\package.json - %2: build\commands\tunnel\index.js + %2: build\commands\device\tunnel.js > Warning Entry 'main' not found in %1 %1: node_modules\@oclif\core\package.json %2: build\commands\version\index.js