#
#  File: README.txt
#
#  Copyright 2024-2025 Penguin Computing Inc.  All Rights Reserved.
#


Overview
--------

ssh-irw.sh allows for secure, passwordless logins into a ICE RemoteWare server. Due to increased security concerns by corporations, secure logins into remote desktops that don't require for credentials to be passed over public and private networks are becoming increasingly important.

ssh-irw.sh uses public/private key pairs to allow for scenarios described above.

In addition, this directory contains a script (test-nested-xserver.sh) test the setup of multiple nested x servers to run multiple irw user sessions on a single server. This works on a system with or without GPUs and is compatible with the usage of VirtualGL, which allows multiple X-servers to run on a single GPU.


Details
-------

What sshirw.sh does when launched by user:
- Establish ssh tunnel to ICE RemoteWare server
- Start X-server as a user process without a greeter
- Launch ICE RemoteWare server 
- Wait for termination (after user is done with the remote session) by entering enter or ctrl-c

Now user can open a browser and connect to the ICE RemoteWare started by ssh-irw.sh


How to use it
-------------

Remote setup:

Usage: ssh-irw.sh  [-h]  -se <ip address>  -u <user name>   [-s <port number>]  [-si <ip address>]  [-ci <ip address>]
                               [-p <port number>]  [-sp <port number>]  [-x <executable>]  [-G <display id>]  [-H <display id>]
                               [-v <level>]  [-d]  [-gs]  [-o <options>]  [-n]


Local testing:

Usage: test-nested-xserver.sh  [-h]  [-x <executable>]  [-G <display id>]  [-H <display id>]
                                     [-p <irw port>] [-verbose <level>] [-gs] [-o <options>] [-n]


Files:
------

ssh-irw.sh: Creates ssh tunnel, starts x-server, gdm session and irw

  Usage:  ssh-irw.sh -se 10.1.0.22  -u userA  -x Xephyr  -p 8423  -sp 8443  -H :1  -G :12
          ssh-irw.sh -se 10.1.0.22  -u userB  -x Xvfb  -p 8423  -sp 8443  -H :1  -G :12  -v 2

test-nested-xserver.sh: Launches x-server, gdm session and irw

  Usage: test-nested-xserver.sh -x Xephyr  -G :18  -H :1  -p 8400
         test-nested-xserver.sh -x Xvfb  -G :18  -v 2  -p 8400

linux-clone-user.sh: Creates new user and copies source users profile to new one
  Usage: linux-clone-user <src_user_name> <new_user_name>


Requirements
------------

- Installation of x-server, gnome and ICE RemoteWare on local machine

   X-server (RedHat/Rocky/Fedora-based):

     sudo dnf install xorg-x11-server-Xvfb -y
     sudo dnf install xorg-x11-server-Xephyr -y

   X-server (Ubuntu/Debian-based):

     sudo apt install xvfb -y
     sudo apt install xserver-xephyr -y

- Xephyr opens the new window display at creation time. To close the
  window automatically, we use xdotool to close it. To install use:

    xdotool (RedHat/Rocky/Fedora-based):

     sudo dnf install xdotool -y

    xdotool (Ubuntu/Debian-based):

     sudo apt install xdotool -y

- Installation of gnome and ICE RemoteWare on server
- ssh installed on server and client
- User has account on ICE RemoteWare server and client (account names do not need to be identical)
- User's private key on user's client (typically ~/.ssh)
- User's public key on the ICE RemoteWare server in ~/.ssh/uthorized_keys

- When running Xephyr as a different user, x11 access control has to be disabled on the
  host for this user

    DISPLAY=<host display id> xhost +local:host

  The display size can be modified by:

    DISPLAY=<host display id> xrandr -s 1920x1080


Multiple X-Servers on Single GPU Server (Ubuntu)
------------------------------------------------

Installation of required tools

- Download location VirtualGL: https://sourceforge.net/projects/virtualgl/files/3.1/

     wget https://sourceforge.net/projects/virtualgl/files/3.1/virtualgl_3.1_amd64.deb

     sudo apt install virtualgl_3.1_amd64.deb
     sudo apt install mesa-utils

- Run graphics apps with VirtualGL, where ":1" is the guest display id

    vglrun -d :1 glxgears


TODO:
-----

Lots of error handling (i.e. handling of ssh timeout)
