SSH System Monitor

A real-time remote system monitoring application with a graphical interface. Monitor Linux and FreeBSD servers via SSH with live metrics for CPU, memory, processes, network, and filesystems.

Features

✨ Key Capabilities

🔒 Secure SSH connection (password or key-based authentication)
📊 Real-time system metrics (CPU, Memory, Network, Processes, Filesystems)
🖥️ Cross-platform support (Linux and FreeBSD auto-detection)
⚙️ Remote process management (view and kill processes)
📈 Network I/O rate calculation (real-time RX/TX speeds)
🎨 Modern dark theme GUI
🔄 Auto-refresh every 3 seconds

Quick Start

Requirements

Java 17+ (JDK for building, JRE for running)
Maven 3.6+ (for building)
SSH access to target servers

Installation & Run

Maven Build (Recommended)

# Build the project
mvn clean package

# Run the application
java -jar target/ssh-monitor-1.0.0-fat.jar

Docker (Alternative)

# Build image
docker build -t ssh-monitor .

# Run with X11 forwarding
xhost +local:docker
docker run -it -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix ssh-monitor

First Connection

Click "Connect" button in the toolbar
Enter SSH credentials:
- Host: IP address or hostname (e.g., 192.168.1.100 or server.example.com)
- Port: SSH port (default: 22)
- User: Your username on the remote server
- Password: Your password (or select key file)
- Use private key file: Check this to use SSH key authentication
- StrictHostKeyChecking: Uncheck for first connection to new hosts
Click OK to connect
Monitor 6 tabs with live data

Application Interface

Tabs Overview

Tab	Description	Refresh Rate
Uptime	System uptime in weeks, days, hours, minutes	3 seconds
CPU	CPU usage percentage with progress bar	3 seconds
Memory	RAM usage (used/total in Mi/Gi)	3 seconds
Processes	Top 20 processes by memory with Kill button	3 seconds
Network	Interface stats with RX/TX rates	3 seconds
Filesystems	Disk usage for all mounted filesystems	3 seconds

Process Management

In the Processes tab:

View top 20 processes sorted by memory usage
Columns: Action, PID, USER, %CPU, %MEM, COMMAND
Click Kill button to terminate a process (executes kill -9 PID)
Confirmation dialog prevents accidental termination

Network Monitoring

Real-time network statistics:

Interface name (e.g., eth0, em0, wlan0)
IPv4 address
RX rate (download speed in B/s, KB/s, or MB/s)
TX rate (upload speed in B/s, KB/s, or MB/s)

Documentation

Comprehensive documentation is included:

USER_GUIDE.md - End-user manual with screenshots
- Connection setup and troubleshooting
- Tab descriptions and metrics explanation
- Process management guide
- Security best practices
DEVELOPER_GUIDE.md - Developer reference
- Architecture and design patterns
- Code organization and structure
- Threading model details
- Adding new OS support
- Testing and debugging
BUILD_DEPLOYMENT.md - Build and deployment
- Build methods (Maven, Docker)
- Package creation and distribution
- Docker and Kubernetes deployment
- CI/CD integration (Jenkins, GitLab, GitHub Actions)
- Performance tuning tips
INSTALLATION.md - Platform-specific installation
- Linux, macOS, Windows setup
- Docker and Kubernetes deployment
QUICK_REFERENCE.md - One-page cheat sheet
- Quick commands and troubleshooting

Project Structure

ssh-monitor/
├── src/
│   └── main/
│       └── java/
│           └── SSHClientMonitor.java  # Main application (single file)
├── target/
│   ├── ssh-monitor-1.0.0.jar          # Standard JAR
│   └── ssh-monitor-1.0.0-fat.jar      # Fat JAR with dependencies
├── docs/                               # Documentation folder
│   ├── USER_GUIDE.md                   # User documentation
│   ├── DEVELOPER_GUIDE.md              # Developer documentation
│   ├── BUILD_DEPLOYMENT.md             # Build & deployment guide
│   ├── INSTALLATION.md                 # Installation guide
│   ├── QUICK_REFERENCE.md              # Quick reference
│   └── README.md                       # Documentation index
├── pom.xml                             # Maven configuration
├── Dockerfile                          # Container image definition
├── Jenkinsfile                         # CI/CD pipeline
├── README.md                           # This file
├── CHANGELOG.md                        # Version history
└── LICENSE                             # Project license

System Support

Remote Systems (Monitored Servers)

✅ Linux - All major distributions (Ubuntu, Debian, CentOS, RHEL, Fedora, Arch, etc.)
✅ FreeBSD - Version 11.0 and newer

The application automatically detects the remote OS and uses appropriate commands.

Client Platforms (Where Monitor Runs)

✅ Linux (all distributions with Java 17+)
✅ macOS (with Java 17+)
✅ Windows (with Java 17+)
✅ Docker container (Linux-based)

Architecture

The application is implemented as a single Java file with modular design:

SSHClientMonitor (Swing GUI)
├── SSH Connection Manager (JSch library)
├── OS Detection & Command Abstraction
│   ├── LinuxCommandProvider
│   │   ├── /proc/uptime, /proc/net/dev
│   │   ├── top, free, ps, df
│   │   └── ip addr, kill
│   └── FreeBSDCommandProvider
│       ├── sysctl, netstat -ibn
│       ├── top, ps, df
│       └── ifconfig, kill
└── Monitoring Engine
    └── ScheduledExecutorService (3-second interval updates)

Key Components

Session Management: Thread-safe SSH session handling
Command Execution: Timeout-protected command execution with stderr capture
OS Abstraction: CommandProvider interface for cross-platform support
Async Updates: Non-blocking UI updates via ScheduledExecutorService
Network Rate Calculation: Delta-based RX/TX rate computation

Build Options

Maven (Recommended)

# Clean and build
mvn clean package

# Skip tests (if any)
mvn clean package -DskipTests

# Build with specific Java version
mvn clean package -Djava.version=17

Output: target/ssh-monitor-1.0.0-fat.jar

Docker

# Build image
docker build -t ssh-monitor:1.0.0 .

# Run container (requires X11)
docker run -it \
  -e DISPLAY=$DISPLAY \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  ssh-monitor:1.0.0

Usage Examples

Local Testing

# Start SSH server (if not running)
sudo systemctl start ssh

# Run monitor
java -jar target/ssh-monitor-1.0.0-fat.jar

# Connect to:
# Host: localhost
# Port: 22
# User: your_username
# Password: your_password

Remote Server Monitoring

# Run on your workstation
java -jar target/ssh-monitor-1.0.0-fat.jar

# Connect to remote server:
# Host: 192.168.1.100
# Port: 22
# User: admin
# Password: ********

SSH Key Authentication

# Generate SSH key (if needed)
ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519

# Copy key to server
ssh-copy-id [email protected]

# In monitor: Check "Use private key file"
# Key path: /home/username/.ssh/id_ed25519

Multiple Servers

To monitor multiple servers simultaneously, launch multiple instances:

# Terminal 1
java -jar target/ssh-monitor-1.0.0-fat.jar &

# Terminal 2
java -jar target/ssh-monitor-1.0.0-fat.jar &

Performance Metrics

Metric	Value	Notes
Startup Time	2-3 seconds	Java runtime initialization
Update Interval	3 seconds	Configurable in source code
Memory Usage	50-100 MB	Typical with one connection
Network Bandwidth	5-10 KB/min	Per monitored server
CPU Impact (Remote)	<1%	Per update cycle
CPU Impact (Local)	1-3%	GUI rendering

Known Limitations

Single Connection: One SSH connection per instance (launch multiple instances for multiple servers)
Process Limit: Top 20 processes displayed (configurable in source code, line 524)
No Passphrase: JSch 0.1.55 doesn't support passphrase-protected keys (use ssh-agent or unprotected keys)
No SFTP: File transfer not implemented (planned feature)
No History: No historical data or graphs (planned feature)

Security

Best Practices

✅ Authentication

Use SSH key authentication instead of passwords when possible
Protect private keys with chmod 600 ~/.ssh/id_rsa
Use strong passwords (12+ characters, mixed case, numbers, symbols)

✅ Connection Security

Enable StrictHostKeyChecking for known servers
Use VPN for remote connections over untrusted networks
Use non-standard SSH ports when possible

✅ Client Security

Run on trusted, secure workstations only
Keep Java runtime updated to latest security patches
Don't store passwords in scripts or configuration files

✅ Server Security

Limit SSH user privileges (use least privilege principle)
Configure SSH server to disable root login
Use fail2ban or similar to prevent brute force attacks
Enable SSH key-only authentication when possible

Security Considerations

⚠️ Credentials: Application does not store credentials (memory-only) ⚠️ Logging: Sensitive data not logged (except connection events) ⚠️ Network: All traffic encrypted via SSH protocol ⚠️ Kill Command: kill -9 requires appropriate user permissions

Troubleshooting

Connection Issues

Problem: "Connection refused"

# Check if SSH server is running
sudo systemctl status ssh

# Start SSH server
sudo systemctl start ssh

# Enable on boot
sudo systemctl enable ssh

Problem: "Authentication failed"

Verify username and password are correct
Check SSH server allows password authentication (PasswordAuthentication yes in /etc/ssh/sshd_config)
Try connecting via terminal: ssh user@host

Problem: "Host key verification failed"

Uncheck "StrictHostKeyChecking" for first connection
Or add host to known_hosts: ssh-keyscan -H hostname >> ~/.ssh/known_hosts

Metrics Not Appearing

Problem: Empty or zero values in tabs

Check remote user has permissions to run commands (ps, df, top)
Review log area (bottom of window) for error messages
Try commands manually: ssh user@host 'ps aux'

Problem: Network rates show 0 B/s

Wait for second update cycle (6 seconds minimum)
Verify network interfaces are active: ip link or ifconfig

Performance Issues

Problem: Slow updates or timeouts

Check network latency: ping hostname
Increase timeout values in source code
Check remote server load: ssh user@host 'uptime'

Problem: High CPU usage on local machine

Reduce update frequency (edit MONITOR_INTERVAL_SECONDS in source)
Close other Java applications
Check for Java runtime issues

Development

Building from Source

# Clone or download source
cd ssh-monitor

# Compile with Maven
mvn clean compile

# Run tests (if any)
mvn test

# Package
mvn package

Code Structure

Lines 1-70: Imports and class declaration
Lines 71-150: UI initialization
Lines 151-250: SSH connection handling
Lines 251-400: Monitoring and update logic
Lines 401-600: Command execution and parsing
Lines 601-750: OS-specific CommandProvider implementations

Adding New OS Support

Create new class implementing CommandProvider interface
Add OS detection in connectSSH() method
Implement all required methods for the new OS
Test with target OS

Example:

private class SolarisCommandProvider implements CommandProvider {
    @Override public String uptimeCommand() { 
        return "uptime | awk '{print $3}'"; 
    }
    // ... implement other methods
}

Contributing

Contributions welcome! Areas for enhancement:

Development Setup

# Requirements
- Java 17+ JDK
- Maven 3.6+
- Git

# Clone and build
git clone <repository>
cd ssh-monitor
mvn clean package

Dependencies

Dependency	Version	License	Purpose
JSch	0.1.55	BSD	SSH protocol implementation
SLF4J API	2.0.7	MIT	Logging facade
SLF4J Simple	2.0.7	MIT	Basic logging implementation

All dependencies are included in the fat JAR.

Version History

Version 1.0.0 (November 2025)

Initial release
Linux and FreeBSD support
Real-time monitoring (CPU, Memory, Processes, Network, Filesystems)
SSH authentication (password and key)
Process management (kill)
Dark theme GUI

License

Author: Cartesian School Siergej Sobolewski Dependencies: MIT

Support

For issues, questions, or contributions:

Check documentation in docs/ directory
Review troubleshooting section above
Examine log output in application

Quick Reference Card

Keyboard Shortcuts

None currently (feature request)

Command Line Options

# Standard launch
java -jar ssh-monitor-1.0.0-fat.jar

# With custom JVM options
java -Xmx512m -jar ssh-monitor-1.0.0-fat.jar

# Debug mode (verbose logging)
java -Dorg.slf4j.simpleLogger.defaultLogLevel=debug -jar ssh-monitor-1.0.0-fat.jar

Connection String Format

Not supported - use GUI connection dialog

Maintained by: Cartesian School Siergej Sobolewski Version: 1.0.0
Release Date: November 2025
Java Target: 17+
Last Updated: November 24, 2025

Quick Links:

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
.idea		.idea
docs		docs
lib		lib
src/main/java		src/main/java
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
ISSUES.md		ISSUES.md
Jenkinsfile		Jenkinsfile
LICENSE		LICENSE
README.md		README.md
dependency-reduced-pom.xml		dependency-reduced-pom.xml
pom.xml		pom.xml

License

Cartesian-School/ssh-system-monitor

Folders and files

Latest commit

History

Repository files navigation

SSH System Monitor

Features

Quick Start

Requirements

Installation & Run

Maven Build (Recommended)

Docker (Alternative)

First Connection

Application Interface

Tabs Overview

Process Management

Network Monitoring

Documentation

Project Structure

System Support

Remote Systems (Monitored Servers)

Client Platforms (Where Monitor Runs)

Architecture

Key Components

Build Options

Maven (Recommended)

Docker

Usage Examples

Local Testing

Remote Server Monitoring

SSH Key Authentication

Multiple Servers

Performance Metrics

Known Limitations

Security

Best Practices

Security Considerations

Troubleshooting

Connection Issues

Metrics Not Appearing

Performance Issues

Development

Building from Source

Code Structure

Adding New OS Support

Contributing

Development Setup

Dependencies

Version History

Version 1.0.0 (November 2025)

License

Support

Quick Reference Card

Keyboard Shortcuts

Command Line Options

Connection String Format

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages