qssh 0.0.2-alpha

# X11 Forwarding with QSSH

QSSH supports X11 forwarding, allowing you to run GUI applications on a remote server and display them locally.

## Prerequisites

1. X11 server running on your local machine:
   - **macOS**: Install XQuartz from https://www.xquartz.org/
   - **Linux**: X11 is usually pre-installed
   - **Windows**: Install VcXsrv or Xming

2. `DISPLAY` environment variable set on your local machine
3. X11 enabled on the remote server

## Basic Usage

### Enable X11 Forwarding

```bash
# Standard X11 forwarding (untrusted)
qssh -X user@server

# Trusted X11 forwarding (less secure, more compatible)
qssh -Y user@server
```

### Test X11 Forwarding

Once connected, test with a simple X11 application:

```bash
# On the remote server
xclock  # Should display a clock on your local screen
xeyes   # Should display eyes that follow your cursor
```

## Common GUI Applications

### Development Tools
```bash
# Run GUI text editors
qssh -X user@server -c "gedit"
qssh -X user@server -c "code"  # VS Code

# Run IDEs
qssh -Y user@server -c "eclipse"
qssh -Y user@server -c "idea"  # IntelliJ IDEA
```

### Scientific Applications
```bash
# Run plotting tools
qssh -X user@server -c "gnuplot"
qssh -X user@server -c "matlab"

# Run data visualization
qssh -X user@server -c "paraview"
```

### System Tools
```bash
# File managers
qssh -X user@server -c "nautilus"
qssh -X user@server -c "thunar"

# System monitors
qssh -X user@server -c "gnome-system-monitor"
```

## Security Considerations

### Untrusted vs Trusted Forwarding

**Untrusted (-X)**: Default, more secure
- Restricts X11 operations
- Prevents keyboard/mouse grabbing
- Blocks screenshot capabilities
- May break some applications

**Trusted (-Y)**: Less secure, more compatible
- Full X11 access
- Required for some applications
- Use only with trusted servers

### Best Practices

1. **Use untrusted (-X) by default**
   ```bash
   qssh -X user@server
   ```

2. **Only use trusted (-Y) when necessary**
   ```bash
   # Only if application doesn't work with -X
   qssh -Y user@trusted-server
   ```

3. **Limit forwarding to specific applications**
   ```bash
   # Run only the needed application
   qssh -X user@server -c "specific-app"
   ```

4. **Disable X11 forwarding when not needed**
   ```bash
   # Regular SSH without X11
   qssh user@server
   ```

## Troubleshooting

### DISPLAY Not Set
```bash
# Check if DISPLAY is set locally
echo $DISPLAY

# Should output something like:
# :0 or localhost:10.0

# If not set, fix it:
export DISPLAY=:0
```

### X11 Connection Rejected
```bash
# On macOS with XQuartz
# Allow connections from network clients:
defaults write org.xquartz.X11 enable_iglx -bool true
defaults write org.xquartz.X11 nolisten_tcp -bool false

# Restart XQuartz
```

### Slow Performance
```bash
# Use compression for slow connections
qssh -X -C user@server

# Consider using VNC or RDP for heavy GUI apps
```

### Application Won't Start
```bash
# Try trusted forwarding
qssh -Y user@server

# Check X11 libraries on server
ssh user@server "ldd /usr/bin/xclock"

# Install missing libraries
ssh user@server "sudo apt-get install libx11-6"
```

## Advanced Configuration

### Custom Display Number
The X11 forwarder automatically finds an available display (usually :10-:99).

### Single Connection Mode
For enhanced security, X11 can be limited to a single connection:
```rust
// In code
let mut config = X11Config::default();
config.single_connection = true;
```

### Custom Authentication
QSSH uses MIT-MAGIC-COOKIE-1 authentication by default with randomly generated cookies for each session.

## Performance Tips

1. **Use local applications when possible** - X11 forwarding adds latency
2. **Enable compression** for slow networks: `qssh -X -C user@server`
3. **Consider alternatives** for heavy applications:
   - VNC for full desktop
   - RDP for Windows applications
   - Web-based interfaces

## Example Session

```bash
# Connect with X11 forwarding
$ qssh -X alice@quantum-server

# Verify X11 is working
alice@quantum-server:~$ echo $DISPLAY
localhost:10.0

# Run a GUI application
alice@quantum-server:~$ xcalc &
[1] 12345

# The calculator appears on your local screen

# Run multiple applications
alice@quantum-server:~$ xterm &
alice@quantum-server:~$ gedit document.txt &

# When done, close applications and disconnect
alice@quantum-server:~$ exit
```

## Integration with SSH Agent

X11 forwarding works seamlessly with the SSH agent:

```bash
# Add key to agent
qssh-add ~/.qssh/id_qssh

# Connect with X11 and agent forwarding
qssh -X user@server
```

## Security Note

X11 forwarding can be a security risk as it provides the remote server with access to your local X11 display. Only use it with trusted servers and consider the security implications for your environment.