Skip to content

Commit aae4252

Browse files
lixmallixmal
committed
Add SSH rewrite docs
1 parent ccc2eab commit aae4252

File tree

2 files changed

+607
-50
lines changed

2 files changed

+607
-50
lines changed

‎src/pages/how-to/cli.mdx‎

Lines changed: 102 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -79,17 +79,24 @@ Single command to log in and start the NetBird client. It can send a signal to t
7979
The command will check if the peer is logged in and connect to the management service. If the peer is not logged in, by default, it will attempt to initiate an SSO login flow.
8080
#### Flags
8181
```shell
82-
--allow-server-ssh Allow SSH server on peer. If enabled, the SSH server will be permitted
83-
--disable-auto-connect Disables auto-connect feature. If enabled, then the client won't connect automatically when the service starts.
84-
--dns-resolver-address string Sets a custom address for NetBird's local DNS resolver. If set, the agent won't attempt to discover the best ip and port to listen on. An empty string "" clears the previous configuration. E.g. --dns-resolver-address 127.0.0.1:5053 or --dns-resolver-address ""
85-
--enable-rosenpass [Experimental] Enable Rosenpass feature. If enabled, the connection will be post-quantum secured via Rosenpass.
86-
--external-ip-map strings Sets external IPs maps between local addresses and interfaces.You can specify a comma-separated list with a single IP and IP/IP or IP/Interface Name. An empty string "" clears the previous configuration. E.g. --external-ip-map 12.34.56.78/10.0.0.1 or --external-ip-map 12.34.56.200,12.34.56.78/10.0.0.1,12.34.56.80/eth1 or --external-ip-map ""
87-
--extra-dns-labels strings Sets DNS labels. You can specify a comma-separated list of up to 32 labels. An empty string "" clears the previous configuration. E.g. --extra-dns-labels vpc1 or --extra-dns-labels vpc1,mgmt1 or --extra-dns-labels ""
88-
-F, --foreground-mode start service in foreground
89-
-h, --help help for up
90-
--interface-name string Wireguard interface name (default "utun100")
91-
--rosenpass-permissive [Experimental] Enable Rosenpass in permissive mode to allow this peer to accept WireGuard connections without requiring Rosenpass functionality from peers that do not have Rosenpass enabled.
92-
--wireguard-port uint16 Wireguard interface listening port (default 51820)
82+
83+
--allow-server-ssh Allow SSH server on peer. If enabled, the SSH server will be permitted
84+
--disable-auto-connect Disables auto-connect feature. If enabled, then the client won't connect automatically when the service starts.
85+
--disable-ssh-auth Disable SSH JWT authentication. If enabled, any peer with network access can connect without user authentication
86+
--dns-resolver-address string Sets a custom address for NetBird's local DNS resolver. If set, the agent won't attempt to discover the best ip and port to listen on. An empty string "" clears the previous configuration. E.g. --dns-resolver-address 127.0.0.1:5053 or --dns-resolver-address ""
87+
--ssh-jwt-cache-ttl int SSH JWT token cache TTL in seconds. Set to 0 to disable caching (default). E.g. --ssh-jwt-cache-ttl 3600 for 1-hour cache
88+
--enable-rosenpass [Experimental] Enable Rosenpass feature. If enabled, the connection will be post-quantum secured via Rosenpass.
89+
--enable-ssh-local-port-forwarding Enable local port forwarding on SSH server. Requires --allow-server-ssh
90+
--enable-ssh-remote-port-forwarding Enable remote port forwarding on SSH server. Requires --allow-server-ssh
91+
--enable-ssh-root Enable root user login on SSH server. Requires --allow-server-ssh
92+
--enable-ssh-sftp Enable SFTP subsystem on SSH server. Requires --allow-server-ssh
93+
--external-ip-map strings Sets external IPs maps between local addresses and interfaces.You can specify a comma-separated list with a single IP and IP/IP or IP/Interface Name. An empty string "" clears the previous configuration. E.g. --external-ip-map 12.34.56.78/10.0.0.1 or --external-ip-map 12.34.56.200,12.34.56.78/10.0.0.1,12.34.56.80/eth1 or --external-ip-map ""
94+
--extra-dns-labels strings Sets DNS labels. You can specify a comma-separated list of up to 32 labels. An empty string "" clears the previous configuration. E.g. --extra-dns-labels vpc1 or --extra-dns-labels vpc1,mgmt1 or --extra-dns-labels ""
95+
-F, --foreground-mode start service in foreground
96+
-h, --help help for up
97+
--interface-name string Wireguard interface name (default "utun100")
98+
--rosenpass-permissive [Experimental] Enable Rosenpass in permissive mode to allow this peer to accept WireGuard connections without requiring Rosenpass functionality from peers that do not have Rosenpass enabled.
99+
--wireguard-port uint16 Wireguard interface listening port (default 51820)
93100
```
94101
#### Usage
95102
The minimal form of running the command is:
@@ -393,36 +400,103 @@ Peers count: 2/3 Connected
393400
</Note>
394401

395402
### ssh
396-
Command to connect using ssh to a remote peer in your NetBird network.
403+
Command to connect via SSH to a remote peer in your NetBird network. The `ssh` command has several subcommands for different operations.
404+
397405
<Note>
398406
Before using this command, make sure that SSH Access is enabled both on the target peer and in the NetBird Dashboard. Learn more about [enabling SSH access](/how-to/ssh).
399407
</Note>
400-
You should run the ssh command with elevated permissions.
401-
#### Flags
408+
409+
#### ssh (connect)
410+
Connect to a remote peer via SSH with an interactive shell or execute a command.
411+
412+
**Flags:**
402413
```shell
403-
-p, --port int Sets remote SSH port. Defaults to 44338 (default 44338)
414+
-L, --local-forward string Local port forwarding (e.g., 8080:localhost:80)
415+
-R, --remote-forward string Remote port forwarding (e.g., 8080:localhost:3000)
416+
-p, --port int Remote SSH port (default: 22)
404417
```
405-
#### Arguments
406-
The ssh command accepts one argument, `user@host`; this argument indicates the remote host to connect:
407-
* `user`: indicates the remote user to login
408-
* `host`: indicates the remote peer host IP address
409-
#### Usage
410-
The minimal form of running the command is:
418+
419+
**Arguments:**
420+
* `user@host`: The remote user and NetBird peer IP address
421+
* `[command]`: Optional command to execute on the remote peer
422+
423+
**Usage:**
424+
425+
Interactive shell:
411426
```shell
412-
sudo netbird ssh user@100.119.230.104
427+
netbird ssh user@100.119.230.104
413428
```
414-
If you the remote peer agent is running the ssh service on a different port, you can use the `--port` or `-p` flag:
429+
430+
Execute a single command:
415431
```shell
416-
sudo netbird ssh -p 3434 user@100.119.230.104
432+
netbird ssh user@100.119.230.104 "uptime"
417433
```
418434

419-
#### Troubleshooting
420-
When you try to connect via `netbird ssh <peer>`, errors can occur. Please enable `ssh` support when joining a peer to your account.
435+
Local port forwarding (forward local port 8080 to remote port 80):
436+
```shell
437+
netbird ssh -L 8080:localhost:80 user@100.119.230.104
438+
```
439+
440+
Remote port forwarding (forward remote port 8080 to local port 3000):
421441
```shell
422-
netbird up --allow-server-ssh
442+
netbird ssh -R 8080:localhost:3000 user@100.119.230.104
423443
```
424444

425-
Ensure that the peer you are trying to connect to has `SSH Access` enabled in the dashboard, under Peers > _your_peer_ > SSH Access.
445+
<Note>
446+
Port forwarding must be enabled on the SSH server using `--enable-ssh-local-port-forwarding` and/or `--enable-ssh-remote-port-forwarding` flags.
447+
</Note>
448+
449+
#### ssh detect
450+
Detect if a remote peer is running the NetBird SSH server. This command is primarily used by native SSH clients through the ProxyCommand configuration.
451+
452+
**Arguments:**
453+
* `host`: The NetBird peer IP address
454+
* `port`: The port to check (typically 22)
455+
456+
**Usage:**
457+
```shell
458+
netbird ssh detect 100.119.230.104 22
459+
```
460+
461+
This command outputs:
462+
- `netbird-ssh` if the peer is running NetBird SSH server
463+
- Nothing if it's not a NetBird SSH server or the connection fails
464+
465+
#### ssh proxy
466+
Internal command used by OpenSSH clients for NetBird SSH integration. This command is automatically invoked by OpenSSH configuration and should not be called directly by users.
467+
468+
#### ssh detect
469+
Internal command used by OpenSSH clients to detect NetBird SSH servers. This command is automatically invoked by OpenSSH configuration and should not be called directly by users.
470+
471+
<Note>
472+
For SFTP and SCP, use native clients (`sftp` and `scp` commands) which work with NetBird SSH automatically.
473+
</Note>
474+
475+
#### Troubleshooting
476+
477+
**Connection fails:**
478+
479+
- Ensure SSH is enabled on the target peer:
480+
```shell
481+
netbird up --allow-server-ssh
482+
```
483+
- Verify SSH Access is enabled in the dashboard (Peers > your_peer > SSH Access)
484+
- Check that an ACL policy allows TCP port 22022
485+
486+
**Authentication fails:**
487+
488+
- Complete the OIDC flow when prompted (browser window will open)
489+
- Verify your IdP is properly configured
490+
- To disable JWT authentication: `netbird up --allow-server-ssh --disable-ssh-auth`
491+
492+
**Port forwarding not working:**
493+
494+
- Ensure the server has the appropriate flags:
495+
```shell
496+
netbird up --allow-server-ssh \
497+
--enable-ssh-local-port-forwarding \
498+
--enable-ssh-remote-port-forwarding
499+
```
426500
427501
<p>
428502
<img src="/docs-static/img/ssh/ssh-dashboard.png" alt="netbird ssh dashboard" className="imagewrapper-big" />

0 commit comments

Comments
 (0)