diff --git a/src/pages/how-to/cli.mdx b/src/pages/how-to/cli.mdx
index ec3ce4d3..a5b67561 100644
--- a/src/pages/how-to/cli.mdx
+++ b/src/pages/how-to/cli.mdx
@@ -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:
@@ -393,36 +400,81 @@ Peers count: 2/3 Connected
### 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.
+
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).
-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 `, 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.
+
+Port forwarding must be enabled on the SSH server using `--enable-ssh-local-port-forwarding` and/or `--enable-ssh-remote-port-forwarding` flags.
+
+
+
+For SFTP and SCP, use native clients (`sftp` and `scp` commands) which work with NetBird SSH automatically.
+
+
+#### 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
+ ```
diff --git a/src/pages/how-to/ssh.mdx b/src/pages/how-to/ssh.mdx
index 849d851f..a11679c2 100644
--- a/src/pages/how-to/ssh.mdx
+++ b/src/pages/how-to/ssh.mdx
@@ -1,69 +1,552 @@
import {Note} from "@/components/mdx";
-# SSH
+# SSH Access
-NetBird provides secure SSH access to your peers through its built-in SSH server, allowing you to connect to remote machines without exposing SSH ports to the internet.
+NetBird provides SSH access to peers through its built-in SSH server. Unlike traditional SSH setups that require exposing port 22 to the internet, NetBird SSH operates entirely over your private network. You can connect using either the `netbird ssh` command or native OpenSSH clients.
- SSH Access is disabled by default and must be enabled both on the target peer and in the NetBird Dashboard.
+ SSH Access is disabled by default and must be enabled both on the target
+ peer and in the NetBird Dashboard.
+## Concepts
+
+### SSH Server
+Each NetBird peer can run an SSH server by enabling `--allow-server-ssh`. The server listens on TCP port 22022 internally but automatically redirects traffic from port 22 (from NetBird network only) for seamless integration with standard SSH workflows.
+
+### Authentication Methods
+- **JWT Authentication (default)**: Connects SSH sessions to user identities via your configured Identity Provider. Requires OIDC flow on first connection.
+- **Machine Identity (`--disable-ssh-auth`)**: Allows SSH access based on network-level ACL policies without user authentication.
+
+### OpenSSH Integration
+For OpenSSH clients, NetBird installs a configuration file (`/etc/ssh/ssh_config.d/99-netbird.conf`) that automatically detects NetBird SSH servers and handles JWT authentication transparently.
+
+### Port 22 Redirection
+When the SSH server is enabled, NetBird redirects inbound TCP port 22 traffic (from the NetBird network only) to port 22022. This allows standard SSH clients to connect to port 22 without configuration changes while keeping your system's existing SSH server (if any) accessible from outside the NetBird network.
## Requirements
-To use SSH access through NetBird, you need to enable SSH in two places:
+To use SSH access through NetBird, you need:
-1. **NetBird Client Settings** - Enable SSH on the target peer
-2. **NetBird Dashboard** - Allow SSH access for the peer
+1. **NetBird v0.60.0 or later** installed on both client and server
+2. **SSH enabled on target peer** - The peer must run with `--allow-server-ssh`
+3. **SSH enabled in Dashboard** - SSH access must be enabled for the peer
+4. **Access Control Policy** - An ACL rule allowing TCP port 22022 access
+5. **(Optional)** For JWT authentication: An Identity Provider configured in NetBird
## Enabling SSH
### Step 1: Enable SSH Server on Target Peer
-On the machine you want to access via SSH:
+On the machine you want to access via SSH, enable the NetBird SSH server.
+
+**Using the GUI:**
1. Click on the NetBird tray icon
2. Navigate to Settings
3. Click on **Allow SSH** to enable the SSH server
-If you are using the CLI, you can enable SSH by running:
+**Using the CLI:**
```bash
-netbird down # if NetBird is already running
+netbird down # if NetBird is already running
netbird up --allow-server-ssh
```
+For additional SSH server features, use these flags:
+
+```bash
+netbird up --allow-server-ssh \
+ --enable-ssh-local-port-forwarding \
+ --enable-ssh-remote-port-forwarding \
+ --enable-ssh-sftp \
+ --enable-ssh-root
+```
+
+**Flag Reference:**
+
+- `--allow-server-ssh`: Enable the SSH server
+- `--enable-ssh-local-port-forwarding`: Allow clients to forward local ports through the server
+- `--enable-ssh-remote-port-forwarding`: Allow clients to request remote port forwarding
+- `--enable-ssh-sftp`: Enable SFTP subsystem for file transfers
+- `--enable-ssh-root`: Allow root user login (use with caution)
+- `--disable-ssh-auth`: Disable JWT authentication (allows any peer with network access)
+- `--ssh-jwt-cache-ttl `: Enable JWT token caching with specified TTL in seconds (default: 0, disabled)
+
-
+
-### Step 2: Enable SSH in Dashboard
+### Step 2: Create Access Control Policy
+
+Create an ACL policy to allow SSH access:
1. Log in to your NetBird Dashboard
-2. Navigate to the target peer details page
-3. Enable SSH access for the peer
-4. Save the changes
+2. Navigate to **Access Control**
+3. Create a new policy:
+- **Source**: Select the peers or groups that will connect via SSH
+- **Destination**: Select the peers or groups running the SSH server
+- **Protocol**: TCP
+- **Ports**: 22022
+- **Action**: Accept
+4. Save the policy
+
+### Step 3: Enable SSH in Dashboard
+
+Enable SSH on individual peers:
+
+1. Navigate to the target peer details page
+2. Enable SSH access for the peer
+3. Save the changes
-
+
-## Using SSH
+## Using NetBird SSH
+
+### NetBird CLI Client
+
+The simplest way to connect is using the `netbird ssh` command:
+
+```bash
+netbird ssh user@100.119.230.104
+```
+
+**Execute a single command:**
-### CLI
+```bash
+netbird ssh user@100.119.230.104 "uptime"
+```
-For SSH access through the command line interface (CLI), refer to the [CLI documentation](/how-to/cli#ssh) for detailed instructions on establishing SSH connections using the NetBird CLI.
+**Port forwarding:**
+
+```bash
+# Local port forwarding: forward local port 8080 to remote port 80
+netbird ssh -L 8080:localhost:80 user@100.119.230.104
+
+# Remote port forwarding: forward remote port 8080 to local port 3000
+netbird ssh -R 8080:localhost:3000 user@100.119.230.104
+```
+
+For detailed CLI usage, see the [CLI documentation](/how-to/cli#ssh).
+
+### Native SSH Clients (OpenSSH)
+
+NetBird automatically configures OpenSSH through a drop-in configuration file.
+
+
+ Currently, only OpenSSH clients are supported. Other SSH clients (PuTTY,
+ etc.) are not compatible.
+
+
+**Prerequisites:**
+
+NetBird creates `/etc/ssh/ssh_config.d/99-netbird.conf` (or equivalent on your OS) which automatically:
+1. Detects if the target is a NetBird SSH server
+2. Handles JWT authentication transparently
+3. Handles server host key verification
+
+**Using OpenSSH:**
+
+```bash
+# Connect using standard SSH
+ssh user@100.119.230.104
+
+# Port forwarding
+ssh -L 8080:localhost:80 user@100.119.230.104
+
+# SFTP
+sftp user@100.119.230.104
+
+# SCP
+scp file.txt user@100.119.230.104:/path/to/destination
+```
+
+**How it works:**
+
+When you run `ssh user@`:
+
+1. OpenSSH reads the NetBird configuration from `99-netbird.conf`
+2. NetBird detects if the target is a NetBird SSH server
+3. If detected, NetBird handles JWT authentication automatically (OIDC flow if needed)
+4. The SSH connection is established with your user identity
### Browser Client
-For SSH access through the Browser Client, refer to the [Browser Client documentation](/how-to/browser-client#ssh-connection) for detailed instructions on establishing SSH connections directly from your web browser.
+For SSH access directly from your web browser without installing any software, refer to the [Browser Client documentation](/how-to/browser-client#ssh-connection).
+
+## Authentication
+
+### JWT Authentication (Default)
+
+By default, NetBird SSH uses JWT-based authentication with the configured Identity Provider. This provides user identity verification instead of machine identity.
+
+
+ Currently, SSH access is controlled by ACL policies and the
+ `--enable-ssh-root` flag. Users connect as either root (if enabled) or
+ admin-equivalent users on Windows. In the future, NetBird will support more
+ granular user mapping, allowing OIDC user X to connect to specific local
+ users (PAM/local) on the target system.
+
+
+
+ **Time synchronization required**: The SSH server's system clock must be
+ synchronized with the IdP for JWT validation. Clock skew can cause
+ authentication failures.
+
+
+**How it works:**
+
+1. When you connect via SSH, the NetBird client requests a JWT token
+2. If no cached token exists or the token is expired:
+- NetBird initiates an OIDC flow
+- A URL is displayed that you must open in your browser to authenticate with the IdP
+- After successful login, NetBird receives and caches the JWT token
+3. The client sends the JWT to the SSH server
+4. The server validates the JWT using the JWKS endpoint configured in the management server
+5. If valid, the SSH session is established with the user identity from the JWT
+
+**Benefits:**
+
+- **User identity**: SSH sessions are associated with actual users, not machines
+- **Centralized auth**: Leverage the configured IdP (Okta, Google, Microsoft, etc.)
+- **Audit trail**: Know exactly which user accessed which machine
+- **Token expiration**: Automatic re-authentication when tokens expire
+
+**Token caching:**
+
+By default, JWT tokens are **not cached**, meaning you'll need to authenticate for each new SSH connection. To enable token caching and reduce authentication prompts on the **SSH client machine**, use the `--ssh-jwt-cache-ttl` flag:
+
+```bash
+# On the SSH client: enable caching with 1-hour TTL
+netbird up --ssh-jwt-cache-ttl 3600
+
+# On the SSH client: disable caching (default)
+netbird up --ssh-jwt-cache-ttl 0
+```
+
+**When caching is disabled (default):**
+- You'll authenticate via OIDC for each new SSH connection
+- More secure but less convenient
+- Recommended for high-security environments
+
+**When caching is enabled:**
+- JWT tokens are cached on the client for the specified TTL in seconds
+- Reduces repeated authentication prompts
+- Cached tokens expire after the configured TTL or when the NetBird daemon is restarted
+
+### Machine Identity (--disable-ssh-auth)
+
+If you prefer to allow SSH access from any peer with network access (similar to pre-0.60 behavior), you can disable JWT authentication:
+
+```bash
+netbird up --allow-server-ssh --disable-ssh-auth
+```
+
+**Important considerations:**
+
+- **Less secure**: Any peer with network access (ACL policy) can connect
+- **Machine identity**: Connections are identified by peer/machine, not by user
+- **No audit trail**: You cannot track which user accessed the system
+- **Use cases**: Automated scripts, service accounts, environments without IdP
+
+
+ When JWT authentication is disabled, SSH access is controlled solely by
+ network-level ACL policies. Ensure your policies are appropriately
+ restrictive.
+
+
+## Advanced Features
+
+### Port Forwarding
+
+NetBird SSH supports both local and remote port forwarding, allowing you to create secure tunnels through the SSH connection.
+
+**Local Port Forwarding:**
+
+Forward a local port on your machine to a remote address through the SSH server:
+
+```bash
+# Forward local port 8080 to remote localhost:80
+netbird ssh -L 8080:localhost:80 user@100.119.230.104
+
+# Forward local port 5432 to a database accessible from the remote peer
+netbird ssh -L 5432:database.internal:5432 user@100.119.230.104
+```
+
+Use case: Access a web service or database running on the remote peer or in its network.
+
+**Remote Port Forwarding:**
+
+Forward a port on the remote SSH server to your local machine:
+
+```bash
+# Forward remote port 8080 to local port 3000
+netbird ssh -R 8080:localhost:3000 user@100.119.230.104
+```
+
+Use case: Allow the remote peer to access a service running on your local machine.
+
+
+ Port forwarding must be enabled on the SSH server using
+ `--enable-ssh-local-port-forwarding` and
+ `--enable-ssh-remote-port-forwarding` flags.
+
+
+### SFTP and SCP
+
+Transfer files securely using native SFTP or SCP clients:
+
+**SFTP:**
+
+```bash
+sftp user@100.119.230.104
+```
+
+**SCP:**
+
+```bash
+# Upload file
+scp file.txt user@100.119.230.104:/path/to/destination
+
+# Download file
+scp user@100.119.230.104:/path/to/file.txt .
+
+# Copy directory
+scp -r directory/ user@100.119.230.104:/path/to/destination
+```
+
+
+ SFTP must be enabled on the SSH server using the `--enable-ssh-sftp` flag.
+ SFTP and SCP require native OpenSSH clients.
+
+
+### Non-interactive Command Execution
+
+Execute commands on remote peers without an interactive shell:
+
+```bash
+netbird ssh user@100.119.230.104 "uptime"
+```
+
+## Platform Support & Limitations
+
+### Supported Platforms
+
+NetBird SSH is supported on the following platforms:
+
+- **Linux**: Full support (all features)
+- **macOS**: Full support (all features)
+- **Windows**: Full support with platform-specific considerations (see below)
+- **FreeBSD**: Full support (all features)
+- **Android**: Server-only support (SSH client not available)
+
+### Platform-Specific Considerations
+
+#### Windows
+
+- **Port forwarding not supported**: SSH servers on Windows cannot accept port forwarding requests
+- **Other features supported**: SFTP, non-interactive commands fully functional
+
+#### Linux/Unix
+
+- **User Switching**: Available when running as root
+- The SSH server can switch to any user when running with root privileges
+- Non-root NetBird (e.g., rootless containers) will run sessions under the given account
+- **All features supported**: Full feature parity across these platforms
+
+#### Android
+
+- **Server-only**: SSH client functionality not available
+- **Server features**: Can run NetBird SSH server (configured via GUI)
+
+## Known Limitations
+
+### Port Forwarding
+
+Port forwarding has the following limitations:
+
+- **Not supported with native SSH clients**: Port forwarding (both local `-L` and remote `-R`) is **only available** when using the `netbird ssh` command directly
+- Native OpenSSH clients **cannot** use port forwarding
+- This is a current implementation limitation
+- Use `netbird ssh -L` or `netbird ssh -R` instead of `ssh -L` or `ssh -R`
+- **Not supported on Windows servers**: SSH servers running on Windows cannot accept port forwarding requests
+- **No user switching with port forwarding**: Port forwarding only works when connecting as the user running the NetBird process
+
+### User Mapping
+
+- **Current behavior**: SSH sessions connect as either:
+- The `root` user on Linux/Unix (if `--enable-ssh-root` is enabled)
+- Administrator-equivalent users on Windows
+- The SSH server's service account (if user switching is unavailable)
+- **Future enhancement**: Planned support for granular user mapping (OIDC user → specific local user)
+- **PAM integration**: Linux/Unix PAM integration is planned for more flexible authentication
+
+### Feature Availability
+
+Some features require specific flags to be enabled on the SSH server:
+
+- **SFTP**: Requires `--enable-ssh-sftp`
+- **Local port forwarding**: Requires `--enable-ssh-local-port-forwarding`
+- **Remote port forwarding**: Requires `--enable-ssh-remote-port-forwarding`
+- **Root login**: Requires `--enable-ssh-root` (use with caution)
+
+## Security Considerations
+
+### Access Control
+
+SSH access is controlled by multiple layers:
+
+1. **Network ACL policies**: Control which peers can access port 22022
+2. **SSH enabled in dashboard**: Per-peer SSH access toggle
+3. **JWT authentication** (if enabled): User identity verification via IdP
+
+## Troubleshooting
+
+### Connection Issues
+
+**"SSH server not detected"** or **"Permission denied (publickey)"** or **"No more authentication methods available"**
+
+- Ensure the target peer is running with `--allow-server-ssh`
+- Verify SSH is enabled in the dashboard for the target peer
+- Check that the target peer is online and connected
+
+**"Authentication failed"** (JWT authentication)
+
+- Complete the OIDC flow when prompted
+- Verify the IdP is properly configured
+- Check if your JWT token is expired (NetBird will request a new one)
+- Ensure the SSH server's system clock is synchronized (time skew causes JWT validation failures)
+- For `--disable-ssh-auth`: Ensure ACL policy allows access
+
+**"Connection timeout"**
+
+- Verify ACL policy allows TCP port 22022
+- Check if peers are connected to each other: `netbird status -d`
+- Test basic connectivity: `ping `
+
+### Port Forwarding Issues
+
+**"Port forwarding not available"**
+
+- Ensure the SSH server was started with appropriate flags:
+- `--enable-ssh-local-port-forwarding` for local forwarding
+- `--enable-ssh-remote-port-forwarding` for remote forwarding
+
+**"Cannot bind to port"**
+
+- For local forwarding: Ensure the local port is not already in use
+- For remote forwarding: Ensure the remote port is available
+
+### SFTP Issues
+
+**"SFTP subsystem not available"**
+
+- Ensure the SSH server was started with `--enable-ssh-sftp`
+
+**"Permission denied"**
+
+- Check file system permissions on the target peer
+- Verify you're connecting with the correct user
+
+## CLI Reference
+
+For complete CLI command reference, including all SSH-related commands and flags, see the [CLI documentation](/how-to/cli#ssh).
+
+## Migrating from v0.59.x and Earlier
+
+
+ This section is only relevant if you're upgrading from NetBird v0.59.x or
+ earlier. New installations can skip this section.
+
+
+### What Changed in v0.60.0
+
+Version 0.60.0 is a complete rewrite with breaking changes:
+
+**New capabilities:**
+- OpenSSH client support via automatic proxy configuration
+- Windows client and server support
+- SFTP subsystem for file transfers
+- Local and remote port forwarding (`netbird ssh` only)
+- Non-interactive command execution
+- Configurable JWT token caching
+
+**Breaking changes:**
+- Server port changed from 44338 to 22022
+- Authentication changed from machine public keys to JWT tokens (user identity)
+- Port 22 automatically redirects to 22022 for NetBird traffic
+- Old implicit firewall rule removed - explicit ACL policy required for port 22022
+- Client no longer requires `sudo` for authentication
+- **Not backward compatible**: v0.60.0+ clients cannot connect to older servers and vice versa
+
+### Upgrade Steps
+
+
+ **Self-hosted deployments:** Update order is important:
+ 1. Management server
+ 2. Dashboard (optional - only if you use browser-based SSH)
+ 3. **SSH servers first** (peers running `--allow-server-ssh`)
+ 4. SSH clients last (peers using `netbird ssh`)
+
+ New clients cannot connect to old servers, so update servers before clients.
+
+
+#### For Self-Hosted Deployments
+
+1. **Update management server** to v0.60.0 or later
+- Verify server is running correctly
+- Confirm JWKS endpoint is accessible
+
+2. **Update dashboard** (optional)
+- Only needed if you use the browser-based SSH client
+- Maintains browser SSH access during peer migration
+
+3. **Create ACL policy** for port 22022:
+```
+Source: [SSH Client Group/Peers]
+Destination: [SSH Server Group/Peers]
+Protocol: TCP
+Port: 22022
+Action: Accept
+ ```
+
+4. **Update SSH servers FIRST** (peers running `--allow-server-ssh`)
+- Start with non-critical peers for testing
+- Old clients can still connect to updated servers
+
+5. **Update SSH clients LAST** (peers using `netbird ssh`)
+- Updated clients cannot connect to old servers
+- This is why servers must be updated first
+
+#### Optional Configuration
+
+Disable JWT authentication on SSH servers (allows network-level access without user auth):
+```bash
+netbird up --allow-server-ssh --disable-ssh-auth
+```
+
+Enable JWT token caching on SSH clients (reduces auth prompts):
+```bash
+netbird up --ssh-jwt-cache-ttl 3600 # 1 hour
+```
+
+
+ The browser-based SSH client in the dashboard remains compatible with both
+ old and new peer versions.
+
## Get started
-
-
+
+
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird)
- Follow us [on X](https://x.com/netbird)
- Join our [Slack Channel](/slack-url)
-- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub
+- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub
\ No newline at end of file
diff --git a/src/pages/how-to/ssh.mdx b/src/pages/how-to/ssh.mdx
index 849d851f..a11679c2 100644
--- a/src/pages/how-to/ssh.mdx
+++ b/src/pages/how-to/ssh.mdx
@@ -1,69 +1,552 @@
import {Note} from "@/components/mdx";
-# SSH
+# SSH Access
-NetBird provides secure SSH access to your peers through its built-in SSH server, allowing you to connect to remote machines without exposing SSH ports to the internet.
+NetBird provides SSH access to peers through its built-in SSH server. Unlike traditional SSH setups that require exposing port 22 to the internet, NetBird SSH operates entirely over your private network. You can connect using either the `netbird ssh` command or native OpenSSH clients.
+