Mosh Deployment and Usage Guide

1. Prerequisites

Build Requirements (Source Installation)

• C++ Compiler: GCC 4.6+ or Clang 3.1+ with C++11 support
• Build Tools: autoconf, automake, pkg-config, make
• Development Libraries:
  • Protocol Buffers (libprotobuf-dev or protobuf-devel)
  • ncurses 5 or 6 (libncurses5-dev/libncursesw5-dev or ncurses-devel)
  • zlib (zlib1g-dev or zlib-devel)
  • OpenSSL/libcrypto (libssl-dev or openssl-devel)
  • utempter (optional, for who support: libutempter-dev)

Runtime Requirements

• Client: mosh-client binary on local machine
• Server: mosh-server binary on remote host (must be in $PATH)
• Network: SSH access (port 22/tcp) for initial handshake
• Firewall: UDP ports 60000-61000 (default range) open between client and server
• Locale: UTF-8 environment required (LANG or LC_ALL set to *.UTF-8)

2. Installation

Option A: Package Installation (Recommended)

Most distributions provide pre-built packages:

# Debian/Ubuntu
sudo apt-get install mosh

# RHEL/CentOS/Fedora
sudo dnf install mosh

# macOS
brew install mosh

# FreeBSD
pkg install mosh

Option B: Build from Source

# Clone repository
git clone https://github.com/mobile-shell/mosh.git
cd mosh

# Generate configure script
./autogen.sh

# Configure with security hardening (recommended for production builds)
./configure --enable-compile-warnings=error

# Alternative: Disable hardening if encountering compiler issues
# ./configure --disable-hardening

# Build and install
make
sudo make install

Security Note: Mosh ships with binary hardening flags (-fstack-protector-all, -D_FORTIFY_SOURCE=2, etc.) enabled by default. The configure script detects supported flags automatically.

3. Configuration

Environment Variables

Ensure UTF-8 locale on both client and server:

export LANG=en_US.UTF-8
# or
export LC_ALL=en_US.UTF-8

Verify with: locale -a | grep utf8

SSH Configuration

Mosh uses SSH for initial authentication. Configure SSH keys to avoid password prompts:

# Generate key (if needed)
ssh-keygen -t ed25519 -C "mosh-client"

# Copy to remote host
ssh-copy-id user@remote-host

Firewall Configuration (Server Side)

Open the UDP port range used by Mosh:

# Using ufw (Ubuntu/Debian)
sudo ufw allow 60000:61000/udp

# Using firewalld (RHEL/CentOS/Fedora)
sudo firewall-cmd --add-port=60000-61000/udp --permanent
sudo firewall-cmd --reload

# Using iptables
sudo iptables -A INPUT -p udp --dport 60000:61000 -j ACCEPT

Cloud Platforms: Configure Security Groups/AWS NACLs to allow inbound UDP 60000-61000 from client IP ranges.

4. Build & Run

Development Build

For development with debug symbols:

./configure CXXFLAGS="-g -O0" --enable-compile-warnings=error
make

Production Build

Optimized build with full hardening:

./configure --enable-compile-warnings=error
make -j$(nproc)
sudo make install

Local Testing

Test client and server on the same machine:

# Terminal 1: Start server manually (for testing)
mosh-server new -p 60001

# Note the MOSH_KEY and port output, then:
MOSH_KEY=<key> mosh-client 127.0.0.1 60001

Standard Usage

# Basic connection
mosh user@hostname

# Specify custom UDP port
mosh -p 60050 user@hostname

# Use alternative binary paths
mosh --client=/usr/local/bin/mosh-client --server=/usr/local/bin/mosh-server user@host

# SSH options (passed to underlying SSH)
mosh --ssh="ssh -i ~/.ssh/custom_key" user@host

5. Deployment

Server Deployment Strategy

Single User/Development Server: Install via package manager and ensure firewall rules allow UDP 60000-61000.

Multi-User/Production Server:

1. Install Server Binary:

   # On Debian/Ubuntu servers
   sudo apt-get install mosh
   
   # Or copy statically-linked binary if no package available
   scp mosh-server root@server:/usr/local/bin/
   

2. Systemd Service (Optional - for persistent sessions): Create /etc/systemd/system/mosh-server@.service:

   [Unit]
   Description=Mosh SSH wrapper
   After=network.target
   
   [Service]
   Type=simple
   ExecStart=/usr/local/bin/mosh-server new -p %i
   StandardInput=socket
   StandardOutput=socket
   

3. SELinux/AppArmor: If enforcing, ensure policies allow UDP binding on high ports:

   # SELinux
   sudo semanage port -a -t mosh_port_t -p udp 60000-61000
   

Client Deployment

Distribute mosh-client binaries or install via package managers. For mobile clients, use Termux (Android) or Blink Shell (iOS).

6. Troubleshooting

Connection Issues

Symptom: mosh: Did not find remote IP address

• Cause: SSH connection failed or mosh-server not in remote $PATH
• Fix:

  # Verify SSH works standalone
  ssh user@host "which mosh-server"
  # If not found, specify path:
  mosh --server=/usr/local/bin/mosh-server user@host
  

Symptom: mosh: Nothing received from server on UDP port 60001

• Cause: Firewall blocking UDP or SELinux restrictions
• Fix:

  # Test UDP connectivity
  nc -u -z -v server_ip 60001
  # Check server firewall rules and cloud security groups
  

Locale Errors

Symptom: mosh requires a UTF-8 locale

• Fix:

  # On server, generate locale if missing
  sudo locale-gen en_US.UTF-8
  # Or use available UTF-8 locale
  export LANG=C.UTF-8
  

Permission Denied

Symptom: mosh-server fails to start on remote host

• Cause: SELinux/AppArmor or missing utempter permissions
• Fix: Install libutempter or run with --no-utempter flag (if supported by build)

Performance Issues

Symptom: High latency despite local echo

• Check: Verify prediction is enabled (default)
• Environment variable:

  export MOSH_PREDICTION_DISPLAY=always  # Force predictions
  # or
  export MOSH_PREDICTION_DISPLAY=never   # Disable if causing issues
  

Security Warnings

Warning: AES session key exposed in environment

• Verification: Ensure /proc/<pid>/environ is not world-readable:

  # Check on target OS
  ls -la /proc/self/environ
  

• Note: Confirmed safe on GNU/Linux, macOS, and FreeBSD. Other OSes may require porting verification.

Build Failures

Error: configure: error: cannot find protobuf

• Fix: Install protobuf compiler and development libraries:

  # Ubuntu/Debian
  sudo apt-get install protobuf-compiler libprotobuf-dev
  
  # macOS
  brew install protobuf
  

Error: warning: -fstack-protector not supported

• Fix: Pass --disable-hardening to ./configure or upgrade compiler.