added tigervnc role

3 files changed, 75 insertions, 0 deletions

diff --git a/README.md b/README.md
index 8f5e60a..11fcb6b 100644
--- a/README.md
+++ b/README.md
@@ -51,6 +51,13 @@ This repository contains a collection of Ansible roles and playbooks designed to
 - Configures sshd Match blocks to enforce restrictions for the user.
 - Prevents execution of arbitrary commands or shell escapes.
 
+### `roles/tigervnc/` - Lightweight VNC server setup with TigerVNC
+- Installs TigerVNC server and related utilities (tigervnc-standalone-server, tigervnc-common, autocutsel).
+- Deploys a system-wide helper script /usr/local/bin/vnc-server for easy management of VNC sessions (start, stop, list).
+- Configures TigerVNC server to run securely on localhost only, preventing external direct connections.
+- Leaves VNC server startup manual, allowing users to launch their own VNC sessions as needed.
+- Does not open any VNC ports on firewall by default; users should tunnel over SSH or configure firewall manually for remote access.
+
 ### `roles/tor/` - Tor installation and configuration
 - Installs and configures the Tor service.
 - Ensures Tor is routing traffic correctly.
diff --git a/roles/tigervnc/files/vnc-server-wrapper b/roles/tigervnc/files/vnc-server-wrapper
new file mode 100644
index 0000000..ee25926
--- /dev/null
+++ b/roles/tigervnc/files/vnc-server-wrapper
@@ -0,0 +1,51 @@
+#!/bin/bash
+set -euo pipefail
+
+VNC_PORT=5901
+DISP_NUM=1
+LOGFILE="/tmp/vnc-${USER}.log"
+
+usage() {
+    printf "%s\n" \
+        "wrapper script to manage tigervnc server sessions" \
+        "usage: $(basename $0) <start | stop | list>" \
+        "" \
+        "start      start tigervnc on port ${VNC_PORT}" \
+        "stop       loop 1 through 10 and kill any tigervnc server displays" \
+        "list       list running tigervnc servers"
+    exit 1
+}
+
+case "${1:-}" in
+    start)
+        printf "%s\n" \
+            "linux connection options:" \
+            "  ssh -fL ${VNC_PORT}:localhost:${VNC_PORT} user@server sleep 10; vncviewer localhost:${VNC_PORT}" \
+            "  vncviewer -via user@server localhost::${VNC_PORT}" \
+            "" \
+            "windows connection options:" \
+            "  PLINK.EXE -no-antispoof -N -L ${VNC_PORT}:localhost:${VNC_PORT} user@server" \
+            "  \"C:\\Program Files (x86)\\TigerVNC\\vncviewer.exe\" localhost:${VNC_PORT}"
+
+        printf "%s\n" "[inf] starting tigervnc on :${DISP_NUM}, localhost-only"
+        vncserver :${DISP_NUM}      \
+            -localhost yes          \
+            -rfbport ${VNC_PORT}    \
+            -securitytypes none     \
+            -geometry 1280x800      \
+            -cleanstale &> "${LOGFILE}"
+        printf "%s\n" "[inf] vnc started, log: ${LOGFILE}"
+        ;;
+    stop)
+        printf "%s\n" "[inf] stopping all running tigervnc sessions"
+        for i in $(seq 1 10); do
+            vncserver -kill :$i -clean 2>/dev/null || true
+        done
+        ;;
+    list)
+        vncserver -list
+        ;;
+    *)
+        usage
+        ;;
+esac
diff --git a/roles/tigervnc/tasks/main.yaml b/roles/tigervnc/tasks/main.yaml
new file mode 100644
index 0000000..a6c930d
--- /dev/null
+++ b/roles/tigervnc/tasks/main.yaml
@@ -0,0 +1,17 @@
+- name: install tigervnc server and dependencies
+  apt:
+    name:
+      - tigervnc-standalone-server
+      - tigervnc-common
+      - autocutsel
+    state: present
+    update_cache: true
+
+- name: deploy vnc-server script to /usr/local/bin
+  copy:
+    src: vnc-server-wrapper
+    dest: /usr/local/bin/vnc-server-wrapper
+    owner: root
+    group: root
+    mode: '0755'
+