System Cluster Sync Lock

A display synchronization tool that keeps your remote display's screen lock state in sync with your local machine. When your local screen locks or unlocks, the remote display follows suit.

Features

• Automatic Sync: Monitors local screen lock/unlock events and syncs them to a remote machine
• Manual Control: Toggle remote display state with a single command or dock button
• SSH-based: Uses SSH for secure remote control
• Systemd Integration: Runs as a systemd service for automatic startup
• Cluster Deskflow Restart: One-click restart of the Deskflow Flatpak on all configured hosts

Architecture

Core Components

1. scripts/sync-lock.sh - Main monitoring script that watches for screen lock/unlock events
2. scripts/display-on.sh - Turns on the remote display(s)
3. scripts/display-off.sh - Turns off the remote display(s)
4. scripts/display-toggle.sh - Manually toggles the remote display state
5. scripts/spotify-shortcut.sh - Sends keyboard shortcut to remote machine(s) (Ctrl+Shift+Space)
6. scripts/deskflow-restart.sh - Restarts the Deskflow Flatpak on all configured hosts in their active graphical session
7. scripts/ssh-config-parser.sh - Parses SSH config file to extract host information

How It Works

1. The sync-lock.sh script monitors D-Bus events for screen lock/unlock changes
2. When a lock/unlock event is detected, it SSH's to all configured remote machines
3. The ssh-config-parser.sh script reads your SSH config to get connection details (hostname, user, identity file, port, etc.)
4. On each remote machine, it uses gnome-screensaver-command to control the display state
5. The systemd service keeps the sync script running continuously
6. All configured hosts are synchronized simultaneously

Installation

1. Copy the example configuration:

   cp config.example config

2. Edit config and set your remote hosts:

   REMOTE_HOSTS="jellyfin server2"

   Make sure these host aliases exist in your ~/.ssh/config file.

3. Run the install script:

   sudo ./install.sh

4. Enable and start the service:

   sudo systemctl enable system-cluster-sync-lock.service
   sudo systemctl start system-cluster-sync-lock.service

Manual Usage

Toggle Remote Display

./scripts/display-toggle.sh

Turn Remote Display On

./scripts/display-on.sh

Turn Remote Display Off

./scripts/display-off.sh

Dock Integration & Desktop Shortcuts

The install.sh script automatically installs .desktop launchers for:

• Toggle cluster displays → scripts/display-toggle.sh
• Restart cluster Deskflow → scripts/deskflow-restart.sh

These launchers are written to:

~/.local/share/applications/system-cluster-sync-lock-toggle.desktop
~/.local/share/applications/system-cluster-deskflow-restart.desktop

On GNOME, the installer also makes a best-effort attempt to pin both launchers to the dash by adding them to org.gnome.shell favorite-apps. If that does not take effect (e.g. non-GNOME desktop or no running session), you can still search for them in your app grid and add them to favorites manually.

Requirements

• Local Machine: Linux with D-Bus and gdbus command
• Remote Machine(s): Linux with GNOME screensaver (gnome-screensaver-command) installed and available in PATH
• SSH: Key-based SSH authentication configured to remote machine
• Systemd: For running as a service (optional, can run manually)
• Deskflow (optional): Flatpak org.deskflow.deskflow installed on each host where you want to use deskflow-restart.sh

Configuration

Edit the config file to customize the remote hosts and connection settings.

The tool supports multiple remote hosts using SSH config file entries:

# Remote hosts: Space or comma-separated list of SSH config host aliases
REMOTE_HOSTS="jellyfin server2 server3"

# Optional: Path to SSH config file (defaults to ~/.ssh/config)
# SSH_CONFIG="$HOME/.ssh/config"

Your ~/.ssh/config should contain entries like:

Host jellyfin
    HostName 192.168.1.60
    User jellyfin
    IdentityFile ~/.ssh/jellyfin
    Port 22

Host server2
    HostName 192.168.1.61
    User admin
    IdentityFile ~/.ssh/server2_key

The tool will automatically extract:

• HostName - The actual hostname/IP
• User - SSH username
• IdentityFile - SSH private key path
• Port - SSH port (if specified)
• ProxyJump - Proxy jump configuration (if specified)

Troubleshooting

Check if service is running

sudo systemctl status system-cluster-sync-lock.service

View service logs

sudo journalctl -u system-cluster-sync-lock.service -f

gnome-screensaver-command: command not found

This error means the remote machine does not have GNOME Screensaver (and its CLI gnome-screensaver-command) installed or available in PATH.

• On Arch/Manjaro:

  sudo pacman -S gnome-screensaver

• On Debian/Ubuntu:

  sudo apt install gnome-screensaver

Make sure this is installed on every host listed in REMOTE_HOSTS (e.g. tower, jellyfin, etc.), and that the GNOME session/screensaver is running on those machines.

Test SSH connection manually

Test SSH connection using the host alias from your SSH config:

ssh jellyfin 'gnome-screensaver-command -q'

Verify SSH config parsing

# Test if a host is found in SSH config
cd ~/repos/system-cluster-sync-lock
source scripts/ssh-config-parser.sh
parse_ssh_config jellyfin

License

MIT