Skip to content

Add SSH rewrite docs #475

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
+585 −50
Draft

Add SSH rewrite docs #475

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
108 changes: 80 additions & 28 deletions src/pages/how-to/cli.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,17 +79,24 @@ Single command to log in and start the NetBird client. It can send a signal to t
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.
#### Flags
```shell
--allow-server-ssh Allow SSH server on peer. If enabled, the SSH server will be permitted
--disable-auto-connect Disables auto-connect feature. If enabled, then the client won't connect automatically when the service starts.
--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 ""
--enable-rosenpass [Experimental] Enable Rosenpass feature. If enabled, the connection will be post-quantum secured via Rosenpass.
--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 ""
--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 ""
-F, --foreground-mode start service in foreground
-h, --help help for up
--interface-name string Wireguard interface name (default "utun100")
--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.
--wireguard-port uint16 Wireguard interface listening port (default 51820)

--allow-server-ssh Allow SSH server on peer. If enabled, the SSH server will be permitted
--disable-auto-connect Disables auto-connect feature. If enabled, then the client won't connect automatically when the service starts.
--disable-ssh-auth Disable SSH JWT authentication. If enabled, any peer with network access can connect without user authentication
--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 ""
--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
--enable-rosenpass [Experimental] Enable Rosenpass feature. If enabled, the connection will be post-quantum secured via Rosenpass.
--enable-ssh-local-port-forwarding Enable local port forwarding on SSH server. Requires --allow-server-ssh
--enable-ssh-remote-port-forwarding Enable remote port forwarding on SSH server. Requires --allow-server-ssh
--enable-ssh-root Enable root user login on SSH server. Requires --allow-server-ssh
--enable-ssh-sftp Enable SFTP subsystem on SSH server. Requires --allow-server-ssh
--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 ""
--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 ""
-F, --foreground-mode start service in foreground
-h, --help help for up
--interface-name string Wireguard interface name (default "utun100")
--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.
--wireguard-port uint16 Wireguard interface listening port (default 51820)
```
#### Usage
The minimal form of running the command is:
Expand Down Expand Up @@ -393,36 +400,81 @@ Peers count: 2/3 Connected
</Note>

### ssh
Command to connect using ssh to a remote peer in your NetBird network.
Command to connect via SSH to a remote peer in your NetBird network. The `ssh` command has several subcommands for different operations.

<Note>
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).
</Note>
You should run the ssh command with elevated permissions.
#### Flags

#### ssh (connect)
Connect to a remote peer via SSH with an interactive shell or execute a command.

**Flags:**
```shell
-p, --port int Sets remote SSH port. Defaults to 44338 (default 44338)
-L, --local-forward string Local port forwarding (e.g., 8080:localhost:80)
-R, --remote-forward string Remote port forwarding (e.g., 8080:localhost:3000)
-p, --port int Remote SSH port (default: 22)
```
#### Arguments
The ssh command accepts one argument, `user@host`; this argument indicates the remote host to connect:
* `user`: indicates the remote user to login
* `host`: indicates the remote peer host IP address
#### Usage
The minimal form of running the command is:

**Arguments:**
* `user@host`: The remote user and NetBird peer IP address
* `[command]`: Optional command to execute on the remote peer

**Usage:**

Interactive shell:
```shell
sudo netbird ssh user@100.119.230.104
netbird ssh user@100.119.230.104
```
If you the remote peer agent is running the ssh service on a different port, you can use the `--port` or `-p` flag:

Execute a single command:
```shell
sudo netbird ssh -p 3434 user@100.119.230.104
netbird ssh user@100.119.230.104 "uptime"
```

#### Troubleshooting
When you try to connect via `netbird ssh <peer>`, errors can occur. Please enable `ssh` support when joining a peer to your account.
Local port forwarding (forward local port 8080 to remote port 80):
```shell
netbird ssh -L 8080:localhost:80 user@100.119.230.104
```

Remote port forwarding (forward remote port 8080 to local port 3000):
```shell
netbird up --allow-server-ssh
netbird ssh -R 8080:localhost:3000 user@100.119.230.104
```

Ensure that the peer you are trying to connect to has `SSH Access` enabled in the dashboard, under Peers > _your_peer_ > SSH Access.
<Note>
Port forwarding must be enabled on the SSH server using `--enable-ssh-local-port-forwarding` and/or `--enable-ssh-remote-port-forwarding` flags.
</Note>

<Note>
For SFTP and SCP, use native clients (`sftp` and `scp` commands) which work with NetBird SSH automatically.
</Note>

#### Troubleshooting

**Connection fails:**

- Ensure SSH is enabled on the target peer:
```shell
netbird up --allow-server-ssh
```
- Verify SSH Access is enabled in the dashboard (Peers > your_peer > SSH Access)
- Check that an ACL policy allows TCP port 22022

**Authentication fails:**

- Complete the OIDC flow when prompted (browser window will open)
- Verify your IdP is properly configured
- To disable JWT authentication: `netbird up --allow-server-ssh --disable-ssh-auth`

**Port forwarding not working:**

- Ensure the server has the appropriate flags:
```shell
netbird up --allow-server-ssh \
--enable-ssh-local-port-forwarding \
--enable-ssh-remote-port-forwarding
```

<p>
<img src="/docs-static/img/ssh/ssh-dashboard.png" alt="netbird ssh dashboard" className="imagewrapper-big" />
Expand Down
Loading