Fix interactive unban

README.md

@@ -2,10 +2,10 @@
 
 ## First-time login
 
-1. Ensure an admin has enabled your user account and provided a username.
+1. Ensure an admin has enabled your user account and provided you a username.
-2. Login via [`ssh`](#ssh): `ssh username@hartmanlab.genetics.uab.edu` (default password is your *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
+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`
+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.
 
@@ -14,68 +14,84 @@
     ssh-copy-id -i ~/.ssh/id_rsa_4096.pub username@hartmanlab.genetics.uab.edu
     ```
 
-## `ssh`
+## Notes
+
+* 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](https://juicessh.com/)
   * [Termux](https://termux.dev/)
 
-### X forwarding
+### `ssh` X forwarding
 
-Launch graphical server programs locally on a client that execute 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) (Linux/OSX/Windows)
-  * [Filezilla](https://filezilla-project.org/download.php?type=client)
 
   ![Filezilla](docs/imgs/filezilla.png)
-  * [sshfs](https://www.digitalocean.com/community/tutorials/how-to-use-sshfs-to-mount-remote-file-systems-over-ssh)
+* [sshfs](https://www.digitalocean.com/community/tutorials/how-to-use-sshfs-to-mount-remote-file-systems-over-ssh) (Linux/OSX/Windows)
-* Windows
+* [WinSCP](https://winscp.net/eng/index.php) (Windows)
-  * [WinSCP](https://winscp.net/eng/index.php)
 
-## `samba`
+## `samba` remote filesharing
 
-Mount `samba` file shares on any platform as if the server data was on a local drive.
+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`
+
+![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)
 
-Access an X2Go remote desktop session using the X2Go `x2goclient` available for Linux/OSX/Windows from the [X2Go website](http://wiki.x2go.org/doku.php) or by installing the `x2goclient` package.
-
 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.
 
-![x2go_server](docs/imgs/x2go_server.png)
+### `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)
+  * 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*.
@@ -89,43 +105,82 @@ X2Go sessions can be paused or suspended from the X2Go client window. Multiple s
   * These folders will then appear on the server under `/media/disk/<share_name>`.
     ![x2go_server](docs/imgs/x2go_automount.png)
 
-**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.
+## ~~Robot computer remote desktop access~~
 
-## Robot computer remote desktop access
+* *Currently unavailable* (TODO network cable unplugged?)
 
-In an X2Go session, go to *Applications>Internet>Remote Viewer>Connection>New* and enter [`vnc://192.168.16.101:5900`](vnc://192.168.16.101:5900)
+* 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)
+## Other available software
-* Locally via a web browser via an SSH tunnel: `ssh -f username@hartmanlab.genetics.uab.edu -L 8888:localhost:8888 -N`
 
-## 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.
+
+## Backing up your data
+
+`/mnt/data` is snapshotted daily to `/mnt/backup/data-backup` and rolling backups are retained for six months.
 
 [`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`: `rsync -azH --delete username@hartmanlab.genetics.uab.edu:/home/username/ home-backup/`
+* 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 `rsync -azh username@hartmanlab.genetics.uab.edu:/mnt/data/scans/20250723_roessler_project .`
+* 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
 
-* Reset your X2Go sessions: `script-user-reset-x2go`
+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.
-* Reset your X2Go desktop: `script-user-reset-desktop`
-* Change your user login password: `passwd`
-* Change your samba password: `smbpasswd`
-* Read the `motd` for service statuses and updates: `cat /etc/motd`
 
-## Resources
+* 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)
@@ -138,8 +193,8 @@ In an X2Go session, go to *Applications>Internet>Remote Viewer>Connection>New* a
 * 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 array: `/mnt/data`
-* 20TB btrfs raid1 backup array: `/mnt/backup`
+* 20TB `btrfs` raid1 backup array: `/mnt/backup`
 
 ## Administrators
 

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).

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) ;;
+  0) user=$(prompt user) ;;
-  1) user="$1"; password=$(prompt password) ;;
+  1) user="$1" ;;
-  2) user="$1"; password="$2" ;;
   *) 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
+echo "User successfully created, provide them with the following for first login"
-desktop="/home/$user/Desktop"
+echo "Username: $user"
-mkdir -p "$desktop"
+echo "Password: $password"
-"$p/script-deploy-manual" "$user"
 
 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)
+  0) user=$(prompt user) ;;
-    prompt user
+  1) user="$1" ;;
-    prompt password
+  *) echo "Too many arguments provided"; exit 1 ;;
-    ;;
-  1)
-    user="$1"
-    prompt password
-    ;;
-  2)
-    user="$1"
-    password="$2"
-    ;;
-  *)
-    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" &&
+  passwd --expire "$user"
-  echo "NOTE: The file sharing (smbpasswd) will not be changed"
+
+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