Fix interactive unban

README.md

@@ -2,80 +2,96 @@
 
 ## First-time login
 
-1. Ensure an admin has enabled your user account and provided a username.
-2. Login via [`ssh`](#clients): `ssh username@hartmanlab.genetics.uab.edu` (the default password is your username)
-3. You will be prompted to create a new password and automatically logged out
-4. Login again using new password: `ssh username@hartmanlab.genetics.uab.edu`
-5. Change `samba` password (default password is also your *username*): `smbpasswd`
-6. To change your password again in the future: `passwd`
-7. *Optional*: Generate a public-private keypair on your client and copy it to the server for faster and more secure logins.
+1. Ensure an admin has enabled your user account and provided you a username.
+2. Login via [`ssh`](#ssh-remote-login): **`ssh username@hartmanlab.genetics.uab.edu`** (default password is your *username*)
+3. You will be prompted to create a new password and then logged out.
+4. Login again using your new password: **`ssh username@hartmanlab.genetics.uab.edu`**
+5. Change the default `samba` password (default password is also your *username*): `smbpasswd`
+6. *Optional*: Generate a public-private keypair on your client and copy it to the server for faster and more secure logins.
 
     ```bash
     ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rsa_4096
     ssh-copy-id -i ~/.ssh/id_rsa_4096.pub username@hartmanlab.genetics.uab.edu
     ```
 
-    Users may need to add their keypair to PuTTy/Filezilla/WinSCP manually.
+## Notes
 
-## `ssh`
+* Read the `ssh` login message for ongoing server status updates.
+* See [Troubleshooting](#troubleshooting) and [Resources](#github-resources) for help.
+* Change your user password: `passwd`
+* Change your samba password: `smbpasswd`
+
+## `ssh` remote login
 
 Connect to the server remotely using the command line.
 
 * Linux/OSX
-  * `ssh username@hartmanlab.genetics.uab.edu`
+  * **`ssh username@hartmanlab.genetics.uab.edu`**
 * Windows
   * [PuTTY](http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html)
 * Android
-  * JuiceSSH
-  * Termux
+  * [JuiceSSH](https://juicessh.com/)
+  * [Termux](https://termux.dev/)
 
-### X forwarding
+### `ssh` X forwarding
 
-Launch graphical server programs locally on a client that run on the server.
+Launch graphical programs locally on a client that execute on the server.
+
+![x_forwarding](docs/imgs/x_forwarding.png)
 
 * Linux/OSX
   * Enable X forwarding during ssh login: `ssh -X username@hartmanlab.genetics.uab.edu`
 * Windows
   * Install [Xming](http://www.straightrunning.com/XmingNotes/) and enable X11 forwarding in the [PuTTY](http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html) options.
 
-## `sftp`
+## `sftp` remote filesharing
 
 Browse and manage files stored on the server.
 
-* Native access to sftp shares using client file manager (`sftp://username@hartmanlab.genetics.uab.edu:/home/username`):
+* File manager
+  * Enter the `sftp://` address into your file manager's url bar, such as: `sftp://username@hartmanlab.genetics.uab.edu/home/username`
+
   ![sftp](docs/imgs/sftp.png)
-* Linux/OSX/Windows
-  * [Filezilla](https://filezilla-project.org/download.php?type=client)
+* [Filezilla](https://filezilla-project.org/download.php?type=client) (Linux/OSX/Windows)
 
-    ![Filezilla](docs/imgs/filezilla.gif)
-  * [sshfs](https://www.digitalocean.com/community/tutorials/how-to-use-sshfs-to-mount-remote-file-systems-over-ssh)
-* Windows
-  * [WinSCP](https://winscp.net/eng/index.php)
+  ![Filezilla](docs/imgs/filezilla.png)
+* [sshfs](https://www.digitalocean.com/community/tutorials/how-to-use-sshfs-to-mount-remote-file-systems-over-ssh) (Linux/OSX/Windows)
+* [WinSCP](https://winscp.net/eng/index.php) (Windows)
 
-## `samba`
+## `samba` remote filesharing
 
-Samba file shares can be mounted cross-platform as if th server data existed locally. The server provides two shares:
+Another method to browse and manage files stored on the server.
+
+The server provides two `samba` shares:
 
 1. Shared data array (`/mnt/data`): `\\username\\data`
-2. User's `$HOME` directory: `\\username\\username`
+2. User home directory (`/home/username`): `\\username\\username`
 
-The default `samba` credentials are the same as your server username and password. Users can change their `samba` password using `smbpasswd`.
+The default `samba` credentials are the same as your server username and password (unless modified with `smbpasswd`).
 
-## `x2goclient`
+**Note:** Samba share are only available on-campus unless also using ssh tunneling: `ssh -L 1445:localhost:445 user@remote-server`
 
-Users can access an X2Go remote desktop session using `x2goclient` from a client. `x2goclient` is available for Linux/OSX/Windows from the [X2Go website](http://wiki.x2go.org/doku.php) or by installing the `x2goclient` package.
+![samba](docs/imgs/samba.png)
+
+## `x2goclient` remote desktop
+
+Launch a persistent remote desktop session for graphical applications using [`x2goclient`](https://wiki.x2go.org/doku.php/download:start) (Linux/Windows/OSX).
+
+![x2go_desktop](docs/imgs/x2go_desktop.png)
 
 X2Go sessions can be paused or suspended from the X2Go client window. Multiple sessions can be created on the client, making it possible to select alternate quality settings based on location and bandwidth.
 
-**Note:** Some programs do not continue to run at full speed when an X2Go session is paused. In these cases, the program should be run via `ssh` in a [`tmux`](https://en.wikipedia.org/wiki/Tmux) or [`screen`](https://www.gnu.org/software/screen/) session.
+### `x2goclient` configuration
 
 * Session tab
   * Session name: Hartman Lab Server
   * Host: `hartmanlab.genetics.uab.edu`
   * Login: *`username`*
   * SSH port: `22`
-  * Session type: **MATE** (MATE provides the best experience with X2Go)
-    ![x2go_server](docs/imgs/x2go_server.png)
+  * Session type: **[MATE](https://mate-desktop.org/)** (provides the best experience with X2Go)
+
+![x2go_server](docs/imgs/x2go_server.png)
+
 * Connection tab
   * Set the connection speed to LAN when connecting from within the UAB network and WAN when outside of the UAB network
   * Compression settings should be left unchanged or set to *adaptive*.
@@ -87,36 +103,84 @@ X2Go sessions can be paused or suspended from the X2Go client window. Multiple s
 * Shared folders tab
   * Select folders on the client to be shared with the server during a session. Browse to the chosen folder, add it to the share, and select *automount*.
   * These folders will then appear on the server under `/media/disk/<share_name>`.
-  * Shared folder permissions can be modified by admin for multi-user access.
     ![x2go_server](docs/imgs/x2go_automount.png)
 
-## Robot computer remote desktop access
+## ~~Robot computer remote desktop access~~
 
-In an X2Go session, go to *Applications>Internet>Remote Viewer>Connection>New* and enter `vnc://192.168.16.101:5900`
+* *Currently unavailable* (TODO network cable unplugged?)
+
+* In an X2Go session go to *Applications>Internet>Remote Viewer>Connection Address* and enter [`vnc://192.168.16.101`](vnc://192.168.16.101).
+
+  ![remote_viewer](docs/imgs/remote_viewer.png)
 
 ## Webcam robot monitoring
 
 * In an X2Go session, via a web browser at [`http://localhost:9999`](http://localhost:9999)
 * Locally via a web browser via an SSH tunnel: `ssh -f username@hartmanlab.genetics.uab.edu -L 9999:localhost:9999 -N`
 
+![robot_camera](docs/imgs/robot_camera.png)
+
 ## RStudio Server
 
 * In an X2Go session, via a web browser at [`http://localhost:8787`](http://localhost:8787)
 * Locally via a web browser via an SSH tunnel: `ssh -f username@hartmanlab.genetics.uab.edu -L 8787:localhost:8787 -N`
 
-## JupyterLab (Python) IDE
+![rstudio_server](docs/imgs/rstudio_server.png)
+![rstudio_server2](docs/imgs/rstudio_server2.png)
 
-* In an X2Go session, via a web browser at [`http://localhost:8888`](http://localhost:8888)
-* Locally via a web browser via an SSH tunnel: `ssh -f username@hartmanlab.genetics.uab.edu -L 8888:localhost:8888 -N`
+## Other available software
 
-## Data backup
+* [VSCode](https://code.visualstudio.com/)
+* [MATLAB](https://www.mathworks.com/help/matlab/index.html)
+* [Jupyter Notebook](https://jupyter.org/)
+* [`qhtcp-workflow`](https://github.com/UAB-Hartman-Lab/qhtcp)
+* [`podman`](https://podman.io/) for containers
+* [`toolbox`](https://docs.fedoraproject.org/en-US/fedora-silverblue/toolbox/) for custom software
+* [`distrobox`](https://github.com/89luca89/distrobox) for custom environments
+* ...and much more (see `dnf list --installed` for installed packages). [Open an issue](https://github.com/UAB-Hartman-Lab/server/issues) for missing or out-of-date software.
 
-[`rsync`](https://linux.die.net/man/1/rsync) is recommended for users that would just like to periodically backup their $HOME directory to a local machine.
+## Backing up your data
 
-* Copy a user's `$HOME`' directory locally to `/home-backup`: `rsync -azH --delete username@hartmanlab.genetics.uab.edu:/home/username/ home-backup/`
-* Copy a shared directory locally `rsync -azh username@hartmanlab.genetics.uab.edu:/mnt/data/scans/20250723_roessler_project .`
+`/mnt/data` is snapshotted daily to `/mnt/backup/data-backup` and rolling backups are retained for six months.
 
-## Resources
+[`rsync`](https://linux.die.net/man/1/rsync) is recommended for periodically backing up user files to a local client.
+
+* Copy a user's `$HOME` directory locally to `/home-backup` from a client: `rsync -azH --delete username@hartmanlab.genetics.uab.edu:/home/username/ home-backup/`
+* Copy a shared directory locally to the current directory from a client: `rsync -azh username@hartmanlab.genetics.uab.edu:/mnt/data/scans/20250723_roessler_project .`
+
+Backups can also be initiated *from* the server using a variety of pre-installed backup tools (`rsnapshot`, `borgbackup`, ...).
+
+## Troubleshooting
+
+Read the `ssh` login message (`cat /etc/motd`) for server status and updates. [Open an issue](https://github.com/UAB-Hartman-Lab/server/issues) if there is one.
+
+* Can't login via `ssh`
+  * Make sure that you are using the correct username and caps lock is off.
+  * Three consecutive failed logins from an off-campus computer will ban the IP for one hour.
+  * Request an administrator to run: `sudo script-user-unban <ip_address>` to unban your IP address
+  * Request an administrator to run: `sudo script-user-reset-password <username>` to reset your login password
+* Can't login via X2Go
+  * Login via `ssh` and reset corrupt X2Go sessions: `script-user-reset-x2go`
+* X2Go desktop is corrupted (desktop not similar to [screenshot](#x2goclient-remote-desktop))
+  * Login via ssh and reset your desktop: `script-user-reset-desktop`
+* File permissions issues
+  * Use `ls -al` or add permissions columns to your file manager to double-check the file permissions.
+  * `/mnt/data` uses shared group permissions, usually:
+    * Group: `smbgrp`
+    * User: *username* that created/owns the file (or `smbgrp`)
+    * Permissions: `2775`
+  * To change: `chown -R username:smbgrp <dir> && chmod 2775 <dir>`
+  * If you do not have sufficient privileges to alter shared file permissions, ask an admin to fix or make a copy.
+* Program runs slowly in paused X2Go session
+  * Run program via `ssh` in a [`tmux`](https://en.wikipedia.org/wiki/Tmux) or [`screen`](https://www.gnu.org/software/screen/) session instead.
+
+## GitHub Resources
+
+* [Issues](https://github.com/UAB-Hartman-Lab/server/issues)
+* [Wiki](https://github.com/UAB-Hartman-Lab/server/wiki)
+* [Chat](https://github.com/UAB-Hartman-Lab/server/discussions)
+
+## External Resources
 
 * [RHEL documentation](https://access.redhat.com/documentation/en/red-hat-enterprise-linux/)
 * [Navigating the Linux CLI](https://www.digitalocean.com/community/tutorials/basic-linux-navigation-and-file-management)
@@ -126,12 +190,12 @@ In an X2Go session, go to *Applications>Internet>Remote Viewer>Connection>New* a
 ## Platform
 
 * AlmaLinux 9.6 w/ Linux 6.1 LTS Hyperscale SIG kernel
-* Intel Xeon X99 E5-2650v4 CPU
-* 96GB RAM
-* 4TB PCIE3 NVMe SSD: `/`, `/home`
-* 20TB btrfs raid1 array: `/mnt/data`
-* 20TB btrfs raid1 backup array: `/mnt/backup`
+* Intel Xeon X99 E5-2650v4 12-core CPU
+* 96GB DDR4 RAM
+* 4TB PCIe 3.0 NVMe SSD: `/`, `/home`
+* 20TB `btrfs` raid1 array: `/mnt/data`
+* 20TB `btrfs` raid1 backup array: `/mnt/backup`
 
 ## Administrators
 
-See additional documentation in [`docs/README.md`](docs/README.md)
+See additional documentation in [`docs/README.md`](docs/README.md).

config/etc/skel/Desktop/manual.desktop

@@ -0,0 +1,6 @@
+[Desktop Entry]
+Encoding=UTF-8
+Name=Hartman Lab Server Manual
+Type=Link
+URL=https://github.com/UAB-Hartman-Lab/server
+Icon=help-browser

docs/README.md

@@ -4,10 +4,10 @@
 
 Type `sudo script-` and use tab completion to access the following helper programs.  
 
-* `sudo script-user-add <username> <password>`
+* `sudo script-user-add <username>`
 * `sudo script-user-remove <username>`
   * Optionally backup the user home directory to the array before removal.
-* `sudo script-user-reset-password <username> <password>`
+* `sudo script-user-reset-password <username>`
   * Reset a user's password if forgotten.
 * `sudo script-user-reset-x2go <username>`
   * Completely reset the X2Go state for the user (destroys active/paused sessions).
@@ -19,12 +19,15 @@ Type `sudo script-` and use tab completion to access the following helper progra
   * Reset permissions on `/mnt/data` if no path is provided.
   * Use as a last resort to reset original permissions for shared data.
 * `sudo script-system-scheduled-restart <OnCalendar>`
-  * If not provided, defaults to `*-*-* 01:30:00` (1:30 AM).
+  * If `<OnCalendar>` not provided, defaults to `*-*-* 01:30:00` (1:30 AM).
   * See [Calendar Events](https://www.freedesktop.org/software/systemd/man/systemd.time.html) for formatting.
   * Alerts users via `notify-send` (X2Go), `wall` (SSH), and adds a reminder to the MOTD.
 * `sudo script-user-reset-desktop <username>`
   * Reset a user’s desktop (MATE configuration) to default.
   * Can also be run in user mode (without `sudo`) for personal accounts.
+* `sudo script-system-update`
+  * Update the server using the system package manager.
+  * Best to run prior to scheduled reboot.
 
 ## Cockpit Server Administration
 
@@ -32,9 +35,9 @@ Graphical system settings tool for monitoring and performing common tasks.
 
 In an X2Go session, via a web browser at [`http://localhost:9090`](http://localhost:9090)
 
-## Deploying `stow` server configuration packages
+## Deploying `stow` server packages
 
-Server scripts and configs are organized using [GNU Stow](https://www.gnu.org/software/stow/manual/stow.html) packages and can be deployed directly from this directory.
+Server scripts and configs are organized using [GNU Stow](https://www.gnu.org/software/stow/manual/stow.html) packages and can be deployed from [the root directory](../).
 
 * Deploy system-wide MATE layout and themes: `sudo stow --adopt -R -t / theme`
 * Deploy system-wide scripts: `sudo stow --adopt -R -t / scripts`
@@ -68,7 +71,7 @@ Login via `ssh` or `cat /etc/motd` to view current service statuses.
 
 * Add the UAB DNS servers (`138.26.5.2`, `138.26.5.66`) to the Windows network config to access UAB resources.
 
-#### Allow Access to Samba Share (Windows Bug Workaround)
+#### Enable Access to Samba Share (Windows Bug Workaround)
 
 1. Open `C:\Windows\system32\drivers\etc\hosts` and copy its contents.
 2. Paste into a new text document and add the appropriate `blazerid` and server IP lines.
@@ -87,3 +90,8 @@ Login via `ssh` or `cat /etc/motd` to view current service statuses.
 * Add 20 GB to the Windows VM: `sudo qemu-img resize /var/lib/libvirt/images/win11-5900.qcow2 +20G`
 * Add GParted ISO as boot device and expand the working partition.
 
+## Fixing no local display
+
+Periodically the GPU hardware resets and crashes the local display manager.
+
+To fix, login via ssh and run: `sudo systemctl restart lightdm`

scripts/usr/local/bin/script-deploy-manual

@@ -1,41 +1,24 @@
 #!/usr/bin/env bash
 # This script installs the Hartman Lab Server Manual to each user's desktop
-# Usage: script-deploy-manual USERNAME|--all
 # Copyright 2021-2025 Bryan C. Roessler
 # Licensed under the Apache License, Version 2.0
+p="${BASH_SOURCE[0]%/*}"; [[ -r $p/script-functions ]] && . "$p"/script-functions || exit 1
 
-script-deploy-manual() {
-  local user_arg="$1"
-  local manual_url="https://docs.google.com/document/d/1K_KwAlv8Zljmy-enwmhT6gMTFutlAFglixvpLGBx0VY"
-  local remove=("manual.pdf" "manual.odt" "Notes.pdf" "Notes.odt" \
+manual_url="https://github.com/UAB-Hartman-Lab/server"
+remove=("manual.pdf" "manual.odt" "Notes.pdf" "Notes.odt" \
     "README.html" "Link to Manual.desktop" "manual-images" \
     "manual.html" "Manual.desktop" "manual.desktop")
-  local users=()
 
-  if [[ -z "$user_arg" || "$user_arg" == "--help" ]]; then
-    cat <<-EOF
-			Usage: script-deploy-manual USERNAME|--all
+is_root
 
-			USERNAME:   Specify a single user's name.
-			--all:     Deploy the manual to all users with a Desktop directory.
-		EOF
-    return 1
-  fi
-
-  if [[ "$user_arg" == "--all" ]]; then
-    for d in /home/*; do [[ -d $d ]] && users+=("${d##*/}"); done
-  else
-    users+=("$user_arg")
-  fi
-
-  for user in "${users[@]}"; do
-    desktop="/home/$user/Desktop"
+for desktop in /home/*/Desktop; do
   [[ -d $desktop ]] || continue
-    echo "Scanning $desktop for old manuals"
+  echo "Removing old manuals from $desktop"
   for f in "${remove[@]}"; do
+    [[ -z $f ]] && continue
     if [[ -e $desktop/$f || -L $desktop/$f ]]; then
       echo "Removing $desktop/$f"
-        rm -f "${desktop:?}/$f"
+      rm -f -- "${desktop:?}/$f"
     fi
   done
   echo "Installing manual to $desktop/manual.desktop"
@@ -45,13 +28,7 @@ script-deploy-manual() {
 		Name=Hartman Lab Server Manual
 		Type=Link
 		URL=$manual_url
-		Icon=text-html
+		Icon=help-browser
 	EOF
-  done
-}
-
-# Allow script to be safely sourced
-if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
-  script-deploy-manual "$@"
-  exit
-fi
+  chmod 644 "$desktop/manual.desktop"
+done

scripts/usr/local/bin/script-install-motd

@@ -136,7 +136,7 @@ print_motd() {
   cat <<-EOF
 
 		Links (ctrl+click to follow)
-		  Server Manual.........: https://tinyurl.com/jjz9h6fr
+		  Server Manual.........: https://github.com/UAB-Hartman-Lab/server
 		  Cockpit (for admins)..: http://localhost:9090
 		  Robot Camera..........: http://localhost:9999
 		  JupyterLab............: http://localhost:8888

scripts/usr/local/bin/script-user-add

@@ -4,14 +4,13 @@
 # Licensed under the Apache License, Version 2.0
 p="${BASH_SOURCE[0]%/*}"; [[ -r $p/script-functions ]] && . "$p"/script-functions || exit 1
 
-echo "Usage: sudo $0 [username] [password]"
+echo "Usage: sudo $0 <username>"
 
 is_root
 
 case $# in
-  0) user=$(prompt user); password=$(prompt password) ;;
-  1) user="$1"; password=$(prompt password) ;;
-  2) user="$1"; password="$2" ;;
+  0) user=$(prompt user) ;;
+  1) user="$1" ;;
   *) echo "Too many arguments provided"; exit 1 ;;
 esac
 
@@ -19,9 +18,12 @@ useradd_cmd=(useradd -m -U)
 
 if id -u "$user" &>/dev/null; then
   ask_ok "User $user exists. Run script-user-remove first?" || exit $?
-  "$p/script-user-remove" "$user" || exit $?
+  script-user-remove "$user" || exit $?
 fi
 
+# Generate random temporary password to provide to user
+password=$(tr -dc 'A-HJ-NP-Za-km-z2-9' </dev/urandom | head -c12)
+
 ask_ok "Create user $user with password $password?" || exit $?
 
 restore=0
@@ -61,9 +63,8 @@ ask_ok "Prompt user to reset password on next login?" &&
   passwd --expire "$user" &&
   echo "NOTE: The file sharing (smbpasswd) will not be changed"
 
-# Copy manual to user desktop
-desktop="/home/$user/Desktop"
-mkdir -p "$desktop"
-"$p/script-deploy-manual" "$user"
+echo "User successfully created, provide them with the following for first login"
+echo "Username: $user"
+echo "Password: $password"
 
 exit 0

scripts/usr/local/bin/script-user-reset-password

@@ -4,27 +4,14 @@
 # Licensed under the Apache License, Version 2.0
 p="${BASH_SOURCE[0]%/*}"; [[ -r $p/script-functions ]] && . "$p"/script-functions || exit 1
 
+echo "Usage: sudo $0 <username>"
+
 is_root
 
-echo "Usage: $0 [username] [password]"
-
 case $# in
-  0)
-    prompt user
-    prompt password
-    ;;
-  1)
-    user="$1"
-    prompt password
-    ;;
-  2)
-    user="$1"
-    password="$2"
-    ;;
-  *)
-    echo "Too many arguments provided"
-    exit 1
-    ;;
+  0) user=$(prompt user) ;;
+  1) user="$1" ;;
+  *) echo "Too many arguments provided"; exit 1 ;;
 esac
 
 if ! id -u "$user" &>/dev/null; then
@@ -32,13 +19,19 @@ if ! id -u "$user" &>/dev/null; then
   exit 1
 fi
 
-if ask_ok "Change user $user's password to $password?"; then
+# Generate random temporary password to provide to user
+password=$(tr -dc 'A-HJ-NP-Za-km-z2-9' </dev/urandom | head -c12)
+
+if ask_ok "Reset $user's password"; then
   echo "$user:$password" | chpasswd
   (echo "$password"; echo "$password") | smbpasswd -a -s "$user"
 fi
 
 ask_ok "Prompt user to reset password on next login?" &&
-  passwd --expire "$user" &&
-  echo "NOTE: The file sharing (smbpasswd) will not be changed"
+  passwd --expire "$user"
+
+echo "Password successfully reset for user $user, provide them with the following for login"
+echo "Username: $user"
+echo "Password: $password"
 
 exit 0

scripts/usr/local/bin/script-user-unban

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# Unbans a fail2ban IP
+# Unban a fail2ban IP
 # Copyright 2021-2025 Bryan C. Roessler
 # Licensed under the Apache License, Version 2.0
 p="${BASH_SOURCE[0]%/*}"; [[ -r $p/script-functions ]] && . "$p"/script-functions || exit 1
@@ -11,7 +11,7 @@ is_root
 if [[ $# -eq 1 ]]; then
   ip_address="$1"
 else
-    prompt ip_address
+  ip_address=$(prompt ip_address)
 fi
 
 if fail2ban-client set sshd unbanip "$ip_address"; then