nstvncadmin

Name

nstvncadmin — NST script to administer virtual desktops.

Synopsis

nstvncadmin [ -m TEXT | --mode TEXT ] [ -d INTEGER | --display INTEGER ] [ -w INTEGER | --width INTEGER ] [ -t INTEGER | --height INTEGER ] [ --depth INTEGER ] [ --dpi INTEGER ] [ -l [true]|false | --localhost [true]|false ] [ --desktop TEXT ] [ --shared TEXT ] [ --dontdisconnect [true]|false ] [ --clientwaittimemillis INTEGER ] [ --idletimeout INTEGER ] [ --viewonly [true]|false ] [ --all [true]|false ] [ --host HOST|IP ] [ --port PORT ] [ -u TEXT | --user TEXT ] [ -p TEXT | --passwd TEXT ] [ --rhost HOST|IP ] [ --rport PORT ] [ --ruser TEXT ] [ --rshared [true]|false ] [ --applet-dir TEXT ] [ --rpath TEXT ] [ --fluxboxstartupcmd TEXT ] [ --loglevel INTEGER ] [ --nolistentcp [true]|false ] [ --su [true]|false ] [ -h [true]|false | --help [true]|false ] [ -H [true]|false | --help-long [true]|false ] [ -v [true]|false | --verbose [true]|false ] [ --version [true]|false ]

Description

The nstvncadmin command is used in a NST distribution to manage virtual desktops provided by the VNC server included in the distribution. This script has several modes of operation. The mode is controlled by the --mode MODE command line option.

Try not to be intimidated by the number of available command line options, you rarely need to use many of them. They are provided mainly to make this script more "configurable" when invoked from other scripts.

To give you an idea of the power of this script, take a look at the following commands:


[root@probe ~]# nstvncadmin -m setup
[root@probe ~]# nstvncadmin -m setup -d 90 --user hsimpson
Password for new user (hsimpson):
Retype new password:
[root@probe ~]# nstvncadmin
7785    root    :6      http://192.168.0.6:5806/
7983    hsimpson        :90     http://192.168.0.6:5890/
[root@probe ~]# nstvncadmin -m connect --all
[root@probe ~]#

Here's the result of the above commands:

  • The first invocation uses the setup mode to allocate a VNC display for the root user as display :6 (the default).

  • The second invocation specifies a specific VNC display (:90) and user account (hsimpson). Since the Unix user account hsimpson doesn't yet exist, we are prompted to set the initial password for the account and connecting to the VNC session.

  • The third invocation (without any options) simply lists what VNC sessions are currently available on the system.

  • Finally, the fourth invocation forwards ALL active VNC sessions to the VNC viewer running in listen mode at 192.168.0.7.

Note

The minimal amount of output has been shown. If we would have included the -v option, the output produced by each command would have been more verbose.

List Mode

If you specify --mode list or -m list on the command line (or if you omit the --mode option entirely), this script will display the list of active VNC desktops with the following columns of information:

PID

The process ID of the VNC desktop.

USER

The user ID of the owner of the VNC desktop.

DISPLAY

The display ID of the VNC desktop.

URL

The URL which one may connect to to view the virtual desktop.

Here is a example of using nstvncadmin in "list mode":

[root@probe ~]# nstvncadmin -v
PID     USER    DISPLAY URL
7785    root    :6      http://192.168.0.6:5806/
7983    hsimpson        :90     http://192.168.0.6:5890/
[root@probe ~]#

Note

The columns are tab delimited and the header line is omitted (unless one includes the -v option). This makes the output easier to parse/process by other scripts.

Setup Mode

If you specify --mode setup or -m setup on the command line, this script will attempt to start a new virtual desktop. There are several things to consider in this mode of operation:

  • The display ID must be a integer value in the range of [1,99]. It defaults to 6 if omitted.

  • The display ID must not conflict with a existing virtual desktop (it is illegal to try and start more than one virtual desktop with the same display ID).

  • If the X font server is not yet running, we will attempt to start it, but only if you run the script as root (non-root users are not able to start system services like the X font server).

  • We will start the virtual desktop even if the X font server isn't running. There may be some issues, but from our experience, the virtual desktop still seems to work sans the X font server.

Here is a example of using nstvncadmin to setup a virtual desktop that fits nicely on a 1600x1200 laptop screen:

[root@probe ~]# nstvncadmin -m setup --display 2 --width 1500 --height 1000
[root@probe ~]#

Though not required, you are free to use the following options with setup mode: --display, --width, --height, --depth, --dpi, --localhost, --shared, --dontdisconnect, --viewonly, --user, --passwd, and --applet-dir.

While many of the options are obvious, I'd like to call your attention to a couple of interesting options. The --user option allows one to setup a VNC session for a different user (if you are logged in as root). In addition, if the user account doesn't yet exist on the system, it will be added. This makes setting up VNC access for a new user trivial. The --localhost option is useful when you don't want other machines to be able to connect to the VNC session directly. When enabled, a remote machine will only be able to gain access to a VNC session if they either establish a ssh tunnel first, or if the client system puts its VNC viewer into listen mode and the vncconnect command is run on the server. For the best security, the ssh tunnel method is recommended.

Kill Mode

If you specify --mode kill or -m kill on the command line, this script will attempt to kill one or all running VNC desktop(s). There are several things to consider in this mode of operation:

  • The display ID must be a legal value (its default value of 6 is legal), or --all must be specified.

  • The display ID must match a display that is actually running on the system.

  • You can only kill virtual desktops owned by other users if you run this script as root.

Here is a example of using nstvncadmin to kill a VNC session on display :2.

[root@probe ~]# nstvncadmin -m kill --display 2
Killing Xvnc process ID 8180
[root@probe ~]#

You can use the --display, --all and --verbose options in combination with the kill mode.

Connect Mode

If you specify --mode connect or -m connect on the command line, this script will attempt forward one (or all) VNC desktop(s) to the specified --host. There are several things to consider in this mode of operation:

  • A VNC viewer operating in "listen" mode must be running on the system specified by the --host HOST option. Most VNC viewers are capable of operating in "listen" mode.

  • The display ID must be a legal value (its default value of 6 is legal), or --all must be specified.

  • The display ID must match a display that is actually running on the system.

  • You can only connect virtual desktops owned by other users if you run this script as root.

Here is a example of using nstvncadmin to connect a VNC session on display :6 to host 192.168.0.7.

[root@probe ~]# nstvncadmin -m connect -d 6 --host 192.168.0.7
[root@probe ~]#

The --host option must always be included when using the connect mode of operation. In addition, you can use --display, --all, --port and --verbose options.

Note

For secure connections, it is recommended that one uses the tunnel mode of operation instead of the connect mode (or direct client access mode) as the VNC protocol is not encrypted.

Tunnel Mode

The tunnel mode of operation is to support those skilled with the use of ssh, ssh-agent, and ssh-add. Assuming that the nstvncadmin is installed and functional on two systems, the tunnel mode allows one to securely access one or more VNC desktops on the remote system. There are several things to consider in this mode of operation:

  • This is the most secure way to access a VNC desktop as the network traffic will be encrypted.

  • If system "A" brings up a tunnel to system "B" and system "A" wants to share its tunnel with other systems on its LAN, the --rshared option must be specified.

  • You must have access to the remote system. And its highly recommended to make use of ssh-agent and ssh-add.

  • The display ID must be a legal value (its default value of 6 is legal), or --all must be specified. If --all is specified, we will make an initial connection to the remote system to see what VNC processes it has running and then create the necessary tunnel(s) for ALL of the VNC desktops.

  • The display ID must match a display that is actually running on the system.

  • Just because you are able to tunnel a VNC desktop, doesn't mean that you will be able to access it. You will still be prompted for the VNC password when you connect to the desktop.

Here is a example of securely tunneling ALL of the VNC desktops running on 192.168.0.6 to the local system and then accessing desktop :6 using 127.0.0.1:6 as its address:


[root@probe ~]# nstvncadmin -m tunnel --all -v --rhost 192.168.0.6 &
Setting up the ssh tunnels via:
/usr/bin/ssh -p 22 -a -N -n -T -x -L 5806:127.0.0.1:5806 -L 5906:127.0.0.1:5906
-L 5890:127.0.0.1:5890 -L 5990:127.0.0.1:5990 root@192.168.0.6
[root@probe ~]# vncviewer 127.0.0.1:6 &
[root@probe ~]#

The --rhost option must always be included when using the connect mode of operation. In addition, you can use the --display, --rshared, --all and --verbose options.

Install Mode

The install mode of operation is used to install nstvncadmin, vncpasswd-stdin, and nstvncadmin.man.html onto another computer to facilitate remote administration. When successful, this enables the remote adminstration capability on the remote system. There are several things to consider in this mode of operation:

  • root access to the remote system is required, it is highly recommended to make use of ssh-agent and ssh-add.

  • The /usr/local/bin directory must be writable, and it must be possible to create and write to the /usr/local/share/doc/nstvncadmin directory on the remote system.

  • Make sure that the hardware architecture is the same for both the local and remote system. Note: x86_64 binaries will not run on x86 hardware platforms.

Here is a example of installing nstvncadmin onto host 192.168.0.2 and then using the list mode remotely to see what VNC sessions are running on 192.168.0.2:


[root@probe ~]# nstvncadmin -m install -v --rhost 192.168.0.2
nstvncadmin                                   100%   60KB   8.4MB/s   00:00
vncpasswd-stdin                               100% 8364    14.8MB/s   00:00
[root@probe ~]# nstvncadmin -v --rhost 192.168.0.2
Invoking the following remote command...
/usr/bin/ssh -p 22 192.168.0.2 'PATH=/usr/local/bin:/usr/bin:/bin:/sbin:/usr/sbin:/usr/local/sbin:/usr/X11R6/bin:${PATH}; nstvncadmin --mode list --verbose true'
PID     USER    DISPLAY URL
3651    megan   :2      http://192.168.0.2:5802/
[root@probe ~]#

The --rhost option must always be included when using the install mode of operation. In addition, you can use the --verbose option.

Note

In order to install nstvncadmin onto another system. The other system should have the VNC package installed and be based on a Fedora Core 2 or above distribution. It may work with other Linux or Unix distributions, but there are no guarantees.

Remote Administration

The nstvncadmin can be used to administer remote systems as well as local systems. In order to turn a local command into a remote command, the --rhost HOST option must be supplied. All remote commands are done securely via ssh and scp. There are several things to consider when using nstvncadmin for remote administration:

  • You must have ssh access to the remote system (typically involving a connection to port 22).

  • You must have a user account on the remote system, and you will want root access if you are responsible for the entire system.

  • The nstvncadmin script must be installed and functional on the remote system (the install mode is useful here).

  • The tunnel and install modes of operation only work in "remote" mode (if you fail to provide a --rhost HOST option, they will report an error and exit).

If the above conditions can be satisfied, you can do many interesting things. As an example, review the sample script below which is built on top of nstvncadmin:

#!/bin/bash
#
# vadmin HOST   - Securely bring up root desktop from remote host.
#
# NOTE: This is only a rough script to give one an idea of what
#       can be done.

HOST="${1}";
DISP=57;
RARGS="-v --rhost ${HOST} --ruser root"

# First setup/start display on remote host

SETUP_ARGS="--localhost --depth 16 --dpi 96 --width 1000 --height 800"

if ! nstvncadmin -m setup -d ${DISP} ${RARGS} ${SETUP_ARGS}; then
  echo "***ERROR*** failed to setup VNC display ${DISP} on ${HOST}";
  exit 1;
fi

# Second, bring up a ssh tunnel

nstvncadmin -m tunnel -d ${DISP} ${RARGS} &
TUNNEL_PID="${!}";

echo "Allowing 3 seconds for ssh tunnel establishment";
sleep 3

# Now bring up the desktop over ssh tunnel

vncviewer 127.0.0.1:${DISP};

# Shutdown tunnel and kill VNC server

kill ${TUNNEL_PID};
nstvncadmin -m kill -d ${DISP} ${RARGS};

Here is a example of using the above script to securely administer the 192.168.0.2 system:


[pkb@salsa ~]$ vadmin 192.168.0.2

... Lots of verbose output as VNC is started on remote system,
    ssh tunnel is created and vncviewer finally comes up ...

[pkb@salsa ~]$

The --rhost option must always be included when using the install mode of operation. In addition, you can use the --verbose options.

Note

In order to install nstvncadmin onto another system. The other system should have the VNC package installed and be based on a Fedora Core 2 or Fedora Core 3 distribution. It may work with other Linux or Unix distributions, but there are no guarantees.

Show xstartup Mode

When one uses the setup mode, the nstvncadmin script will create the file: "$HOME/.vnc/xstartup" if it does not exist. If you specify --mode xstartup or -m xstartup on the command line, this script will simply show the: "$HOME/.vnc/xstartup" which would have been generated by the script. This mode is really designed to support other scripts (such as found in the NST WUI or during the build process of the initial ISO image).

No other command line options are required when this mode is used.


[pkb@salsa ~]$ nstvncadmin -m xstartup > xstartup
[pkb@salsa ~]$

Options

The following command line options are available:

[-m TEXT] | [--mode TEXT]

This option controls what nstvncadmin will do. If you specify list (the default), it will list the active VNC sessions. Specify setup to create setup and start a new VNC server session. Specify kill to remove a VNC server session. Specify connect to forward specify display (or all displays) to a host running a VNC viewer in listen mode. Specify tunnel to bring up ssh tunnels to a remote system for secure VNC access. Specify install to transfer the nstvncadmin onto the remote system. Finally, the xstartup option may be used to show (but not create) the default: "$HOME/.vnc/xstartup" which the script would create during the setup process (this mode is typically used by other scripts).

[-d INTEGER] | [--display INTEGER]

Use this option to control which VNC display is created (or killed). The minimum value permitted is 1. The maximum value permitted is 99.

[-w INTEGER] | [--width INTEGER]

Use this option with the --mode setup option to specify the width (in pixels) for the virtual desktop which is to be created. The minimum value permitted is 1. The maximum value permitted is 32000.

[-t INTEGER] | [--height INTEGER]

Use this option with the --mode setup option to specify the height (in pixels) for the virtual desktop which is to be created. The minimum value permitted is 1. The maximum value permitted is 32000.

[--depth INTEGER]

Use this option to adjust the number of bits used for colors. The default value of 24 provides true color. Common settings are 8, 16 and 24. The minimum value permitted is 8. The maximum value permitted is 32.

[--dpi INTEGER]

By default, VNC sessions typically assume a default pixel density of 75 dots per inch (DPI). If you intend to view the VNC session on a system with a different pixel density, you can use this option to adjust it. For example, a 15 inch LCD running at 1600x1200 would want a DPI value of 134. Windows machines often default to 96 (check the General tab in the Advanced display property settings). The minimum value permitted is 16. The maximum value permitted is 1000.

[-l [true]|false] | [--localhost [true]|false]

This option is used in setup mode. When set to true, access will only be granted to connections coming from the localhost. This means that you won't be able to establish a connection unless you setup a ssh tunnel, or use the connect option to a vncviewer running in listen mode. NOTE: The default value for this option is false.

[--desktop TEXT]

The title name to appear in the window frame of the VNC Viewer.

[--shared TEXT]

This option is used in setup mode. If set to client (the default), the VNC viewer connection will be able to control whether the desktop is shared or not. If set to always, the desktop will always be shared (allow multiple VNC viewer connections). If set to never, the desktop will never be shared (permit only a single connection).

[--dontdisconnect [true]|false]

This option is used in setup mode. If set to true, a VNC viewer will not be able to disconnect other active VNC viewers. For example, if you left a VNC viewer running at the office (in a non-shared mode), you would not be able to access the desktop from home until someone killed the active session at the office.

[--clientwaittimemillis INTEGER]

Time in milliseconds (msec) to wait for a viewer which is blocking Xvnc. This is necessary because Xvnc is single-threaded and sometimes blocks until the viewer has finished sending or receiving a message - note that this does not mean an update will be aborted after this time. The default setting is 20000 (20 seconds). The minimum value permitted is 0. The maximum value permitted is 300000.

[--idletimeout INTEGER]

Set the number of seconds after which an idle VNC connection will be dropped. The default value is zero (0) seconds which means no timeout. The minimum value permitted is 0. The maximum value permitted is 86400.

[--viewonly [true]|false]

This option is used in setup mode. A view only configuration is ideal for setting up a Kiosk display. When set to true, the VNC server will be started such that VNC clients will only be able to view the desktop.

[--all [true]|false]

Typically one performs operations with the nstvncadmin script on a individual display basis (using the --display ID option). If an operation (like kill, connect and tunnel) permits it, you can apply the operation to ALL running VNC servers.

[--host HOST|IP]

This option is used by the connect mode of operation to indicate the remote machine to display the desktop on.

[--port PORT]

The connect mode of operation permits establishing VNC connections to remote systems. By default, we will use port 5500 as this is typical for VNC viewers operating in listen mode. The minimum value permitted is 1. The maximum value permitted is 65535.

[-u TEXT] | [--user TEXT]

This option allows one to administer VNC sessions for other users on the system. If not specified, it defaults to the special value SELF indicating that you are administering your own session. In order to use this option, you must be running nstvncadmin as root.

[-p TEXT] | [--passwd TEXT]

Before a VNC server can be started, the user must exist on the system and a password file for the VNC server must exist at $HOME/.vnc/passwd. If either of these conditions are not met, a VNC server can not normally be started. If you specify this option, the nstvncadmin script will attempt to add the new user to the system (if necessary), and then create the appropriate $HOME/.vnc/passwd file. It should be noted that this requires that the vncpasswd-stdin program is installed on the system (which can be found in the NST distribution). It is also important to note that if a new user is created on the system, both their normal login password and VNC server passwords will be identical.

[--rhost HOST|IP]

Include this option to invoke your command on a remote system instead of the one you are currently logged into. When this option is set to something other than OMITTED (the default), we will attempt to run nstvncadmin on the host specified via ssh. This allows one to manage many different systems remotely. This option is required for the tunnel and install modes of operation.

[--rport PORT]

This option is only used when the --rhost HOST option has been specified. It allows one to specify a different port for the ssh command. Typically this option is omitted as the default value of 22 is correct. The minimum value permitted is 1. The maximum value permitted is 65535.

[--ruser TEXT]

When running the nstvncadmin command to operate on a remote host, you can use this option to specify the user ID to use on the remote system if necessary. If you omit this option, it defaults to DEFAULT, which tells us to run as your current user ID unless you are attempting something that involve root access (in which case we will automatically switch to root).

[--rshared [true]|false]

By default, any ssh connections set up in tunnel mode are only available to the local host. If you want to share the tunneled connections with others systems on your LAN, include this argument on the command line.

[--applet-dir TEXT]

The VNC server is capable of providing access to Java enabled web browsers. In order to do this, the VNC server needs to know the location of the directory where these Java classes live. Typically, you don't need to worry about this as the default option of SEARCH will most likely find the necessary directory. However, if you need to specify a special directory, you can use this option. In addition, if you want to disable access via a web browser, you can specify --applet-dir DISABLE.

[--rpath TEXT]

The nstvncadmin script allows one to invoke commands on remote systems via the magic of ssh. This option allows one to specify additional directories on the remote system to search for commands. Typically you never need to specify this option as the default values work for normal installations. However, if you've installed the nstvncadmin in a directory other than /usr/local/bin or /usr/bin on the remote system, you may need to use this option to specify the directory to search for on the remote system.

[--fluxboxstartupcmd TEXT]

This option allows one to add a Fluxbox startup command to the VNC session. This option will add the command to the user's ~/.fluxbox/apps file.

[--loglevel INTEGER]

Use this option to control the log verbosity level output from the Xvnc server. The range is between 0 and 100 with 100 meaning the most verbose output. Typically, all log output from the Xvnc server is directed toward the user's log file: ~/.vnc/HOSTNAME:DISPNUM.log. The minimum value permitted is 0. The maximum value permitted is 100.

[--nolistentcp [true]|false]

This option is used to disable the TCP/IP transport associated with the Xvnc - X Window Server. If disabled, Xvnc will not bind a TCP/IP port (Port: 6000 + DISPNUM) to its process, thus not allowing a TCP/IP connection to be established. For example, one would not be able to render the display of an X Application to this Xvnc - X Window Server.

[--su [true]|false]

This option is used primarily used for the NST WUI so that the user's VNC desktop will not be destroyed when reloading the Apache Web Server.

[-h [true]|false] | [--help [true]|false]

When this option is specified, nstvncadmin will display a short one line description of nstvncadmin, followed by a short description of each of the supported command line options. After displaying this information nstvncadmin will terminate.

[-H [true]|false] | [--help-long [true]|false]

This option will attempt to pull up additional nstvncadmin documentation within a text based web browser. You can force which browser we use setting the environment variable TEXTBROWSER, otherwise, we will search for some common ones.

[-v [true]|false] | [--verbose [true]|false]

When you set this option to true, nstvncadmin will produce additional output. This is typically used for diagnostic purposes to help track down when things go wrong.

[--version [true]|false]

If this option is specified, the version number of the script is displayed.

Files

/usr/local/share/doc/nstvncadmin

Directory containing documentation for nstvncadmin.

/usr/local/bin/vncpasswd-stdin

Program used to generate a VNC desktop password (if one doesn't yet exist).

Environment

TEXTBROWSER

This controls what text based browser is used to display help information about the script. If not set, we will search your system for available text-based browsers (Ex: elinks, lynx ...).

Authors

Paul Blankenbaker created initial version.

Ronald W. Henderson added additional functionality.

See Also

ssh(1), ssh-add(1), ssh-agent(1), vncserver(1), vncviewer(1), Xvnc(1), Network Security Toolkit