Update doc

startvnc

 #!/bin/bash
 #
-# Copyright 2017
-#
-# Mathis Rosenhauer
-# Deutsches Klimarechenzentrum GmbH
-# Bundesstr. 45a
-# 20146 Hamburg
-# Germany
+# Copyright 2017 Deutsches Klimarechenzentrum GmbH
 #
 # All rights reserved.
 #
@@ -37,50 +31,80 @@
 #
 # startvnc
 #
-# Starts vncserver on a GPU node by submitting a generated job script.
-# A local vncviewer client is used to connect to the server over an
-# encypted ssh tunnel. After the client shuts down, the server job is
-# terminated.
+# This script is intended to be used on your local workstation running
+# Ubuntu or Fedora Linux or macOS (tested). Other Unix flavors may
+# work as well. It allows you to connect to one of DKRZ's
+# visualization nodes to work remotely on your visualizations.
+#
+# Technically, it starts a VNC server on one of the GPU nodes by
+# submitting a generated job script. A local vncviewer client is used
+# to connect to the server over an encypted ssh tunnel. After the
+# client shuts down, the server job is terminated.
 #
-# Interrupting the script with Ctrl-C should clean up and kill a
-# running or queued job. That may take a couple of seconds so be
-# patient.
+# Your local vncviewer client has to support the -via
+# option. TigerVNC, TightVNC, and TurboVNC  are known to work.
 #
-# The vncviewer client has to support the -via option. TurboVNC,
-# TigerVNC and TightVNC are known to work.
+# In case of problems contact Mathis Rosenhauer <rosenhauer@dkrz.de>.
 #
 
 set -eu
 
 # Default settings
-
-# LDAP username
-SVNC_USERNAME=""
+#
+# You can change the settings here or override them with command line
+# options. SVNC_ACCTCODE is the only parameter you have to provide if
+# your local username matches your username on the frontend and if
+# vncviewer is installed in the standard location (tight/tigervnc on
+# Linux for example).
 
 # Project account code
 SVNC_ACCTCODE=""
 
-# Session run time in minutes
-SVNC_RUNTIME=240
+# LDAP username
+#
+# Specify your username on the login node if it is not your local
+# username.
+SVNC_USERNAME=$(id -un)
 
-# Quality of service
-SVNC_QOS="normal"
+# Path to local vncviewer
+#
+# On Linux and other Unix systems chances are that vncviewer is
+# installed in /usr/bin. If this is not the case, e.g. if you use
+# TurboVNC or if you are on macOS, then change this parameter.
+SVNC_VNCVIEWER="/usr/bin/vncviewer"
 
 # Resolution of remote desktop window
+#
+# This is just the initial resolution. Resizing the vncviewer window
+# later should also work.
 SVNC_GEOMETRY="1920x1200"
 
-# Path to local vncviewer
-SVNC_VNCVIEWER="/usr/bin/vncviewer"
+# Session run time in minutes
+SVNC_RUNTIME=240
 
-# Uncomment this if you use TurboVNC as vncviewer
-#readonly SVNC_VNC_OPTIONS="-extssh"
+# Quality of service
+SVNC_QOS="normal"
 
-# Frontend host. Must be directly accessible from client. The frontend
-# and the node where vncserver is running need a shared home file
-# system.
+# Uncomment this if you use TurboVNC as vncviewer.
+#
+# TurboVNC will work without this option but then it will use its own
+# implementation of ssh which dosen't support public key auth among other
+# things.
+#
+# readonly SVNC_VNC_OPTIONS="-extssh"
+
+# Frontend host
+#
+# Must be directly accessible from client. The frontend and the node
+# where vncserver is running need a shared home file system. You will
+# have to change this for other sites than DKRZ (along with many other
+# things).
 readonly SVNC_FRONTEND_HOST="mistral.dkrz.de"
 
 # Copy vncpassword temporarily to the local workstation
+#
+# If your vncviewer client has trouble with TurboVNC's password format
+# then disable this option (set to "false" or comment).
 readonly SVNC_PASSWORD="true"
 
 
@@ -88,13 +112,14 @@ clean_up () {
     trap - ERR EXIT
     set +e
 
-    if [[ -n ${vnc_host} ]]; then
+    if [[ -n ${vnc_host:-} ]]; then
+    echo "Killing vncserver :${vnc_display} on ${vnc_host}."
         ssh_frontend "ssh ${vnc_host} \"/opt/TurboVNC/bin/vncserver \
                      -kill :${vnc_display}\""
     fi
 
-    echo "Removing job."
-    if [[ -n ${job_id} ]]; then
+    if [[ -n ${job_id:-} ]]; then
+    echo "Removing job ${job_id}."
         ssh_frontend "scancel -Q ${job_id}; sleep 1; \
                      cd .startvnc && rm -f out.${job_id}"
     else
@@ -158,8 +183,8 @@ parse_options () {
     readonly SVNC_VNCVIEWER
     readonly SVNC_VNC_OPTIONS
 
-    if [[ -z ${SVNC_ACCTCODE} ]] || [[ -z ${SVNC_USERNAME} ]]; then
-        printf "ERROR: Please specify at least username and acctcode.\n\n" >&2
+    if [[ -z ${SVNC_ACCTCODE} ]]; then
+        printf "ERROR: Please specify an acctcode.\n\n" >&2
         usage
         exit 1
     fi
@@ -179,7 +204,7 @@ submit_vnc_job () {
     ssh_frontend "cd .startvnc && sbatch" <<EOF
 #!/bin/bash -l
 #SBATCH --partition=gpu
-#SBATCH --ntasks=12
+#SBATCH --ntasks=24
 #SBATCH --qos=${SVNC_QOS}
 #SBATCH --time=${SVNC_RUNTIME}
 #SBATCH --account=${SVNC_ACCTCODE}
@@ -221,14 +246,17 @@ main () {
     local host_and_display=$(get_vnc_host_and_display "$job_id")
     vnc_host=${host_and_display%:*}
     vnc_display=${host_and_display#*:}
+    echo "Vncserver started on node ${vnc_host}.dkrz.de display \
+:${vnc_display}."
 
     local vnc_options="${SVNC_VNC_OPTIONS:-} \
                        -via ${SVNC_USERNAME}@${vnc_host}.dkrz.de"
     if [[ ${SVNC_PASSWORD} = "true" ]]; then
+    echo "Fetching password from frontend."
         ssh_frontend "cat .vnc/passwd" > ${HOME}/vnc_passwd
         vnc_options+=" -passwd ${HOME}/vnc_passwd"
     fi
-
+    echo "Connecting vncviewer to ${vnc_host}.dkrz.de"
     "${SVNC_VNCVIEWER}" ${vnc_options} :${vnc_display}
 }