A Go tool that monitors file existence on a remote SSH server and manages SSH port forwarding with low power mode support.

Linux-only: This tool uses Intel P-State driver for CPU power management and is designed specifically for Linux systems.

• File Monitoring: Checks for file existence on remote SSH server every 15 minutes (configurable)
• Remote SSH Port Forwarding: Forwards remote port 2022 to local SSH server port 22, allowing users to connect to this local server through the remote server
• CPU Power Management: Uses Intel P-State driver to switch between performance and powersave modes
• Low Power Mode: Reduces resource usage and CPU power when trigger file is not present
• User Session Protection: Automatically prevents CPU power changes when users are logged in
• Configurable: All settings can be configured via configuration file
• Graceful Shutdown: Handles SIGINT and SIGTERM signals properly
• Linux Only: Designed for Linux systems with Intel P-State support

Download the latest release from GitHub Releases:

# Linux (amd64)
curl -L https://github.com/worthies/bridge/releases/latest/download/bridge-linux-amd64.tar.gz -o bridge.tar.gz
tar -xzf bridge.tar.gz
sudo mv bridge-linux-amd64 /usr/local/bin/bridge
sudo chmod +x /usr/local/bin/bridge

# Verify installation
bridge -version

Or download the latest nightly build.

Install as a systemd service on Debian/Ubuntu systems:

# Download Debian package
curl -L https://github.com/worthies/bridge/releases/latest/download/bridge_VERSION_amd64.deb -o bridge.deb

# Install the package
sudo dpkg -i bridge.deb

# Configure
sudo nano /etc/bridge/bridge.conf

# Start the service
sudo systemctl start bridge

See DEBIAN-PACKAGE.md for detailed instructions.

# Clone the repository
git clone https://github.com/worthies/bridge.git
cd bridge

# Initialize the module and install dependencies
go mod tidy

# Build the application
go build -o bridge .

The tool uses a configuration file by default. Configuration files are searched in this order:

1. /etc/bridge/bridge.conf (system-wide, for installed package)
2. ./bridge.conf (current directory)
3. ~/.bridge.conf (user home directory)

You can also specify a custom config file with the -config flag.

The configuration file uses KEY=VALUE format:

# SSH Server Configuration
SSH_HOST=localhost
SSH_PORT=22
SSH_USER=root

# Authentication (use either password or key)
SSH_KEY_PATH=/path/to/private/key
# SSH_PASSWORD=your_password

# File to monitor on remote server
REMOTE_FILE_PATH=bridge

# Remote port forwarding (remote:2022 -> local:22)
# This allows users on the remote server to connect to this local server
LOCAL_PORT=22
REMOTE_PORT=2022

# Check interval (supports: s, m, h)
CHECK_INTERVAL=15m

# Low power mode (disabled by default)
# Set to true to enable CPU governor changes when the trigger file is absent
LOW_POWER_MODE=false

Note: Environment variables override configuration file values.

# Run with default config file location
./bridge

# Run with custom config file
./bridge -config /path/to/my/bridge.conf

# Override config with environment variables
SSH_HOST=myserver.com ./bridge

# Copy the example configuration
cp bridge.conf my-bridge.conf

# Edit the configuration
nano my-bridge.conf

# Run with your config
./bridge -config my-bridge.conf

Edit your configuration file:

SSH_HOST=myserver.com
SSH_USER=myuser
SSH_KEY_PATH=/home/user/.ssh/id_rsa

Environment variables can override config file values:

# Override SSH host and user
SSH_HOST=myserver.com SSH_USER=myuser ./bridge -config bridge.conf

# Override check interval
CHECK_INTERVAL=5m ./bridge

1. Connection: The tool connects to the specified SSH server using either key or password authentication

2. File Monitoring: Every 15 minutes (configurable), it checks if the specified file exists on the remote server

3. Remote Port Forwarding: When the file exists:

   • Starts SSH remote port forwarding from remote port to local SSH server
   • Users can connect to remote_server:2022 which forwards to localhost:22
   • This allows remote access to the local machine through the SSH server
   • Maintains the connection until file is removed

4. Low Power Mode: When the file doesn't exist:

   • Stops port forwarding to save resources
   • Closes SSH connection
   • Switches CPU governor to powersave mode (intel_pstate driver) if no users are logged in
   • Continues checking for file existence
   • Automatically exits low power mode when file reappears
   • Restores CPU governor to performance mode

5. User Session Protection: Automatically detects logged-in users and prevents CPU power mode changes during interactive sessions

6. Graceful Shutdown: Responds to SIGINT/SIGTERM by cleanly closing connections

• Remote Access Gateway: Provide SSH access to local servers through a remote gateway
• Service Discovery: Monitor a service readiness file and enable remote access when ready
• Conditional Access: Only allow remote port forwarding when authorized (trigger file present)
• Resource Management: Reduce power consumption when services are not needed
• Automated Reverse Tunneling: Create SSH reverse tunnels based on remote conditions

You have a local server behind NAT that should be accessible through a public SSH server:

1. Deploy this tool on your local server behind NAT
2. Configure it to connect to a public SSH server and monitor a trigger file
3. When the service starts and creates the PID file, port forwarding activates
4. When the service stops and removes the PID file, forwarding stops and system enters low power mode

The bridge tool actively manages CPU power states using the Intel P-State driver:

• Linux system with intel_pstate or cpufreq driver
• Root/sudo privileges to modify CPU governor settings
• Intel CPU with Hardware P-States (HWP) support recommended

When low power mode is enabled (trigger file absent):

• Checks if any users are logged in to the system
• If users are logged in, skips CPU power changes to avoid affecting interactive sessions
• If no users are logged in:
  • Sets CPU energy_performance_preference to power (or scaling_governor to powersave)
  • Reduces CPU frequency and power consumption
  • Suitable for idle/monitoring states

When low power mode is disabled (trigger file present):

• Sets CPU energy_performance_preference to performance (or scaling_governor to performance)
• Maximizes CPU performance for active workloads
• Suitable for active port forwarding and data transfer

The tool automatically detects logged-in users and will not switch to power-saving CPU mode when interactive sessions are active. This prevents performance degradation for users working on the system. Port forwarding and SSH connections are still managed normally.

# Run with sudo to enable CPU governor control
sudo ./bridge -config bridge.conf

# Or install as systemd service (runs as root by default)
sudo systemctl start bridge

Without root privileges, the tool will still function but will log warnings when attempting to change CPU governors.

# Check current governor
cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor

# Check energy performance preference (intel_pstate)
cat /sys/devices/system/cpu/cpu0/cpufreq/energy_performance_preference

# Available options
cat /sys/devices/system/cpu/cpu0/cpufreq/energy_performance_available_preferences

• Use SSH key authentication when possible instead of passwords
• Ensure the remote file path is secure and not writable by unauthorized users
• Consider firewall rules to restrict access to forwarded ports
• Monitor logs for connection attempts and failures
• Run as root/sudo only if CPU power management is required

The tool provides detailed logging including:

• SSH connection status
• File existence check results
• Port forwarding start/stop events
• Low power mode transitions
• Error conditions

# Build for amd64
GOOS=linux GOARCH=amd64 go build -o bridge-linux-amd64 .

# Build for arm64
GOOS=linux GOARCH=arm64 go build -o bridge-linux-arm64 .

# Build for 386
GOOS=linux GOARCH=386 go build -o bridge-linux-386 .

Or use the Makefile:

# Build for current platform
make build

# Build for all Linux platforms
make build-all

# Build Debian package
make deb VERSION=1.0.0

• QUICKSTART.md - Quick start guide
• DEBIAN-PACKAGE.md - Debian package installation and management
• CPU-POWER-MANAGEMENT.md - CPU power management details
• SYSTEMD-REFERENCE.md - Systemd service reference
• WORKFLOWS.md - CI/CD workflows and releases

Contributions are welcome! Please ensure:

1. All tests pass: go test ./...
2. Code is formatted: go fmt ./...
3. No linting errors: go vet ./...
4. Documentation is updated

See WORKFLOWS.md for information about CI/CD pipelines.

See LICENSE file for details.