These are text from the primary Help sections of the SSVNC gui.
Run the ssvnc GUI for additional information.
============================================================================
Help Main:
SSVNC version: 1.0.26
Hosts and Displays:
Enter the VNC host and display in the 'VNC Host:Display' entry box.
It is of the form "host:number", where "host" is the hostname of the
machine running the VNC Server and "number" is the VNC display number;
it is often "0". Some Examples:
snoopy:0
far-away.east:0
sunray-srv1.west:17
24.67.132.27:0
Then click on "Connect". When you do the STUNNEL program will be started
locally to provide you with an outgoing SSL tunnel.
Once the STUNNEL is running, the TightVNC Viewer (Or perhaps Chicken of
the VNC on Mac OS X, or one you set under Options) will be automatically
started and directed to the local port of the SSL tunnel which, in turn,
encrypts and redirects the connection to the remote VNC server.
The remote VNC server **MUST** support an initial SSL/TLS handshake before
using the VNC protocol (i.e. VNC is tunnelled through the SSL channel
after it is established). "x11vnc -ssl ..." does this, and any VNC server
can be made to do this by using, e.g., STUNNEL or socat on the remote side.
SSVNC also supports VeNCrypt and ANONTLS SSL/TLS VNC servers (see below.)
* Automatic SSH Tunnels are described below.
* The 'No Encryption' / 'None' option provides a direct connection without
encryption (disable the button with the -enc option, or Options menu.)
More info in Tip 5.
Port numbers:
If you are using a port less than the default VNC port 5900 (usually
the VNC display = port - 5900), use the full port number itself, e.g.:
24.67.132.27:443
Note, however, if the number n after the colon is < 200, then a
port number 5900 + n is assumed; i.e. n is the VNC display number.
If you must use a TCP port less than 200, specify a negative value,
e.g.: 24.67.132.27:-80
For Reverse VNC connections (listening viewer, See Tip 2 and
Options -> Help), the port mapping is similar, except "listening
display :0" corresponds to port 5500, :1 to 5501, etc.
Zeroconf/Bonjour:
On Unix or Mac OS X, if the 'avahi-browse' or 'dns-sd' command is
available on the system and in your PATH, a 'Find' button is placed by
'VNC Host:Display'. Clicking on Find will try to find VNC Servers on
your Local Network that advertize via the Zeroconf protocol. A menu of
found hosts is presented for you to select from.
VNC Password:
On Unix or MacOSX IF there is a VNC password for the server you can
enter it in the "VNC Password:" entry box.
This is *REQUIRED* on MacOSX when Chicken of the VNC is used, because
that viewer does not put up a user password prompt when it learns
that a password is needed.
On Unix (including MacOSX using the X11 viewer) if you choose not to
enter the password you will simply be prompted for it in the terminal
window running TightVNC viewer if one is required.
On Windows TightVNC viewer will prompt you if a password is required.
NOTE: when you Save a VNC profile, the password is NOT saved (you need
to enter it each time). Nor is the 'Verify All Certs' setting.
Profiles:
Use "Save" to save a profile (i.e. a host:display and its specific
settings) with a name.
To load in a saved Options profile, click on the "Load" button.
To list your profiles from the command line use:
ssvnc -profiles (or -list)
You can launch ssvnc and have it immediately connect to the server
by invoking it something like this:
ssvnc profile1 (launches profile named "profile1")
ssvnc hostname:0 (connect to hostname VNC disp 0 via SSL)
ssvnc vnc+ssl://hostname:0 (same)
ssvnc vnc+ssh://hostname:0 (connect to hostname VNC disp 0 via SSH)
see the Tips 3 and 9 for more about the URL-like syntax.
SSL Certificate Verification:
*** IMPORTANT ***: If you do not take the steps to VERIFY the VNC Server's
SSL Certificate, you are in principle vulnerable to a Man-In-The-Middle
attack. Without SSL Certificate verification, only passive network
sniffing attacks will be guaranteed to be prevented. There are hacker
tools like dsniff/webmitm and cain that implement SSL Man-In-The-Middle
attacks. They rely on the client user not bothering to check the cert.
You can use the "Fetch Cert" button to retrieve the Cert and then
after you check it is OK (say, via comparing the MD5 or other info)
you can "Save" it and use it to verify future connections to servers.
(However, see the note at the end of this section about CA certificates.)
When "Verify All Certs" is checked, this check is always enforced,
and so the first time you connect to a new server you may need to
follow a few dialogs to inspect and save the server certificate.
See the "Certs... -> Help" for information on how to manage certificates.
"Verify All Certs" is on by default.
Note, however, "Fetch Cert" and "Verify All Certs" are currently disabled
in the very rare "SSH + SSL" usage mode to avoid SSHing in twice.
You can manually set a ServerCert or CertsDir in this case if you like.
Advanced Method: Certificate Authority (CA):
If you, or your site administrator, goes though the steps of setting up
a Certificate Authority (CA) to sign the VNC server and/or VNC client
Certs, that can be used instead and avoids the need to manually verify
every cert while still authenticating every connection. More info:
http://www.karlrunge.com/x11vnc/faq.html#faq-ssl-ca
See the cmdline option -cacert file below in 'SSL Certificates'
for setting a default ServerCert/CA Cert.
You may also Import the CA Cert and save it to the 'Accepted Certs'
directory so the "Verify All Certs" automatic checking will find it.
Note that if a Server is using a CA signed certificate instead of
its own Self-Signed one, then the default "Verify All Certs/Fetch Cert"
saving mechanism will NOT succeed. You must obtain the CA certificate
and explicitly set it as the ServerCert or Import it to Accepted Certs.
SSL/TLS Variants; VeNCrypt and ANONTLS:
SSVNC can also connect to VNC SSL/TLS variants; namely the VeNCrypt and
"TLS" VNC Security types. Vino uses the latter (we call it "ANONTLS");
and a growing number use VeNCrypt (QEMU, ggi, virt-manager, VeNCrypt, Xen.)
Via the VeNCrypt bridge that SSVNC provides, the VeNCrypt/ANONTLS
support ALSO works with ANY 3rd party VNC Viewers you specify via
'Change VNC Viewer' (e.g. RealVNC, TightVNC, UltraVNC, etc.) that do
not directly support VeNCrypt or ANONTLS. This works on all platforms:
Unix, MacOSX, and Windows.
Notes on VeNCrypt/ANONTLS Auto-detection:
IMPORTANT: VeNCrypt Server Auto-detection *ONLY* occurs in SSL mode
and when an initial fetch-cert action takes place.
While the initial certificate fetch is taking place SSVNC applies
heuristics to try to automatically detect the VeNCrypt or ANONTLS
protocol use by the VNC server. This way it learns that the server
is using it and then knows to switch to VeNCrypt encrypted SSL/TLS at
the right point. Then SSVNC makes a second (the real) connection to
VNC server and connects the VNC viewer to it.
In the default "Verify All Certs" mode, a fetch cert action always
takes place, and so VeNCrypt/ANONTLS will be autodected.
However, if you have specified an explicit ServerCert or disabled
"Verify All Certs" then even though the initial fetch cert action is no
longer needed, it is performed anyway because it allows VeNCrypt/ANONTLS
auto-detection.
To disabled this initial fetch (e.g. you know the VNC server is normal
SSL and not VeNCrypt/ANONTLS and want to connect more quickly) then
select "Do not Probe for VeNCrypt" in the Advanced Options menu.
On the other hand, if you know the VNC server ONLY supports VeNCrypt or
ANONTLS, to improve the accuracy and speed with which the connection
takes place, you can specify the one or both of the 'Server uses
VeNCrypt SSL encryption' and 'Server uses Anonymous Diffie-Hellman'
in the 'Advanced' options panel. That way guessing via an initial
probe is not needed or performed. See each options's Advanced Options
Help for more info.
Note that if you are using VeNCrypt or ANONTLS for REVERSE connections
(Listen) then you *MUST* set the 'Server uses VeNCrypt SSL encryption'
(and the ANON-DH if it applies) option in Advanced. Note also that
REVERSE VeNCrypt and ANONTLS connections currently do not work on
Windows.
Also, if you are using the "Use SSH+SSL" double tunnel, you MUST set
'Server uses VeNCrypt SSL encryption' (and the ANON-DH if it applies)
because the initial fetch cert is disabled in SSH+SSL mode.
Deciphering SSL Negotiation Success or Failure:
Since SSVNC is a "glue program", in this case gluing VNCViewer and stunnel
together (with possibly a proxy helper) reporting is clumsy at best.
(In SSH encryption mode, it glues to ssh instead of stunnel.) In most
cases the programs being "glued" are run in a terminal window where you
can see the program's output. On Windows you will need to double click
on the stunnel tray icon to view its log.
Although the output is quite cryptic, you are encouraged to learn to
recognize some of the errors reported in it.
Here is stunnel output for a case of successfully verifying the VNC
Server's Certificate:
2008.11.20 08:09:39 LOG5[1472]: VERIFY OK: depth=0, /C=AU/L=...
2008.11.20 08:09:39 LOG6[1472]: SSL connected: new session negotiated
2008.11.20 08:09:39 LOG6[1472]: Negotiated ciphers: AES256-SHA SSLv3 ...
Here is a case where the Server's Cert did not match the ServerCert
we set:
2008.11.20 08:12:31 LOG4[1662]: VERIFY ERROR: depth=0, error=self ...
2008.11.20 08:12:31 LOG3[1662]: SSL_connect: 14090086: error:14090086:SSL
routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed
Here is a case where the Server's Cert has expired:
2009.12.27 12:20:25 LOG4[25500]: VERIFY ERROR: depth=0, error=certificate
has expired: /C=AU/L=...
2009.12.27 12:20:25 LOG3[25500]: SSL_connect: 14090086: error:14090086:SSL
routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed
If you disable "Verify All Certs" and do not supply a ServerCert,
then there will be no 'VERIFY ...' in the output because the SSVNC
stunnel accepts the server's cert without question (this is insecure.)
Also in the output will be messages about whether the SSL VNC server
rejected your connection because it requires you to authenticate
yourself with a certificate (MyCert). Here is the case when you
supplied no MyCert:
2008.11.20 08:16:29 LOG3[1746]: SSL_connect: 14094410: error:14094410:
SSL routines:SSL3_READ_BYTES:sslv3 alert handshake failure
or you used a certificate the server did not recognize:
2008.11.20 08:18:46 LOG3[1782]: SSL_connect: 14094412: error:14094412:
SSL routines:SSL3_READ_BYTES:sslv3 alert bad certificate
or your certificate has been revoked:
2008.11.20 08:20:08 LOG3[1913]: SSL_connect: 14094414: error:14094414:
SSL routines:SSL3_READ_BYTES:sslv3 alert certificate revoked
SSH:
Click on "Use SSH" if you want to use an *SSH* tunnel instead of SSL
(then the VNC Server does not need to speak SSL or use STUNNEL or socat).
You will need to be able to login to your account on the remote host
via SSH (e.g. via password, ssh keys, or ssh-agent).
Specify the SSH hostname and VNC display in the VNC Host:Display entry.
Use something like:
username@far-away.east:0
if your remote username is different from the one on the local viewer
machine.
On Windows you *MUST* supply the "username@" part because Putty/Plink
needs it to work correctly.
"SSH + SSL" is similar but its use is more rare because it requires 2
encrypted tunnels to reach the VNC server. See the Help under Options
for more info.
To connect to a non-standard SSH port, see SSH Proxies/Gateways section.
See Tip 8) for how to make this application be SSH-only with the -ssh
command line option or "sshvnc".
Remote SSH Command:
In SSH or SSH + SSL mode you can also specify a remote command to run
on the remote ssh host in the "Remote SSH Command" entry. The default
is just to sleep a bit (e.g. sleep 30) to make sure the tunnel ports
are established. Alternatively you could have the remote command start
the VNC server, e.g.
x11vnc -display :0 -rfbport 5900 -localhost -nopw
When starting the VNC server this way, note that sometimes you will need
to correlate the VNC Display number with the "-rfbport" (or similar)
option of the server. E.g.:
VNC Host:Display username@somehost.com:2
Remote SSH Command: x11vnc -find -rfbport 5902 -nopw
See the Tip 18) for using x11vnc PORT=NNNN feature (or vncserver(1)
output) to not need to specify the VNC display number or the x11vnc
-rfbport option.
SSL Certificates:
If you want to use a SSL Certificate (PEM) file to authenticate YOURSELF to
the VNC server ("MyCert") and/or to verify the identity of the VNC Server
("ServerCert" or "CertsDir") select the certificate file by clicking the
"Certs ..." button before connecting.
Certificate verification is needed to prevent Man-In-The-Middle attacks;
if it is not done then only passive network sniffing attacks are prevented.
There are hacker tools like dsniff/webmitm and cain that implement SSL
Man-In-The-Middle attacks. They rely on the client user not bothering to
check the cert.
See the x11vnc documentation:
http://www.karlrunge.com/x11vnc/ssl.html
for how to create and use PEM SSL certificate files. An easy way is:
x11vnc -ssl SAVE ...
where it will print out its automatically generated certificate to the
screen and that can be copied safely to the viewer side.
You can also use the "Create Certificate" feature of this program under
"Certs ...". Just click on it and follow the instructions in the dialog.
Then copy the cert file to the VNC Server and specify the other one in
the "Certs ..." dialog.
Alternatively you can use the "Import Certificate" action to paste in a
certificate or read one in from a file. Or you can use the "Fetch Cert"
button on the main panel. If "Verify All Certs" is checked, you will
be forced to check Certs of any new servers the first time you connect.
Note that "Verify All Certs" is on by default so that users who do not
understand the SSL Man-In-The-Middle problem will not be left completely
vulnerable to it (everyone still must make the effort to verify new
certificates by an external method to be completely safe).
To have "Verify All Certs" toggled off at startup, use "ssvnc -nv" or
set SSVNC_NO_VERIFY_ALL=1 before starting. If you do not even want to
see the button, use "ssvnc -nvb" or SSVNC_NO_VERIFY_ALL_BUTTON=1.
Use the "-mycert file" option (same as "-cert file") to set a default
MyCert. This is the same as "mycert=file" (also "cert=file") in the
~/.ssvncrc file. See Certs -> Help for more info.
Use the "-cacert file" option (same as "-ca file") to set a default
ServerCert (or CA). This is the same as "cacert=file" (also "ca=file")
in the ~/.ssvncrc file. See Certs -> Help for more info.
Use the "-crl file" option to set a default CRL File. This is the same
as "crl=file" in the ~/.ssvncrc file. See Certs -> Help for more info.
Prefix any of these files with "FORCE:" to make them immutable.
More Options:
To set other Options, e.g. for View-Only usage or to limit the number
of colors used, click on the "Options ..." button and read the Help there.
More Info:
Press the 'Proxies', 'Misc', and 'Tips' buttons below.
See also these links for more information:
http://www.karlrunge.com/x11vnc/faq.html#faq-ssl-tunnel-ext
http://stunnel.mirt.net
http://www.tightvnc.com
============================================================================
Help Proxies:
SSVNC version: 1.0.26
Here are a number of long sections on all sorts of proxies, Web, SOCKS,
SSH tunnels/gateways, UltraVNC, Single Click, etc., etc.
Proxies/Gateways:
If an intermediate proxy is needed to make the SSL connection
(e.g. a web gateway out of a firewall) enter it in the "Proxy/Gateway"
entry box:
VNC Host-Display: host:number
Proxy/Gateway: proxy-host:port
e.g.:
VNC Host-Display: far-away.east:0
Proxy/Gateway: myproxy.west:8080
If the "double proxy" case is required (e.g. coming out of a web
proxied firewall environment and then INTO a 2nd proxy to ultimately
reach the VNC server), separate them via a comma, e.g.:
VNC Host-Display: far-away:0
Proxy/Gateway: myproxy.west:8080,myhome.net:443
So it goes: viewer -> myproxy.west -> myhome.net -> far-away (VNC)
The proxies are assumed to be Web proxies. To use SOCKS proxies:
VNC Host-Display: far-away.east:0
Proxy/Gateway: socks://mysocks.west:1080
Use socks5:// to force the SOCKS5 proxy protocol (e.g. for ssh -D).
You can prefix web proxies with http:// in SSL mode but it doesn't matter
since that is the default for a proxy. (NOTE that in SSH or SSH+SSL
mode you MUST supply the http:// prefix for web proxies because in those
modes an SSH tunnel is the default proxy type: see the next section.)
Note that Web proxies are often configured to ONLY allow outgoing
connections to ports 443 (HTTPS) and 563 (SNEWS), so you might
have run the VNC server (or router port redirector) on those ports.
SOCKS proxies usually have no restrictions on port number.
You can chain up to 3 proxies (any combination of web (http://) and
socks://) by separating them with commas (i.e. first,second,third).
Proxies also work for un-encrypted connections ("None" or vnc://, Tip 5)
See the ss_vncviewer description and x11vnc FAQ for info on proxies:
http://www.karlrunge.com/x11vnc/faq.html#ss_vncviewer
http://www.karlrunge.com/x11vnc/faq.html#faq-ssl-java-viewer-proxy
SSH Proxies/Gateways:
Proxy/Gateway also applies to SSH mode, it is a usually a gateway SSH
machine to log into via ssh that is not the workstation running the
VNC server. However, Web and SOCKS proxies can also be used (see below).
For example if a company had a central login server: "ssh.company.com"
(accessible from the internet) and the internal workstation with VNC was
named "joes-pc", then to create an SSH tunnel one could put this in:
VNC Host:Display: joes-pc:0
Proxy/Gateway: ssh.company.com
It is OK if the hostname "joes-pc" only resolves inside the firewall.
The 2nd leg, from ssh.company.com -> joes-pc is done by a ssh -L
redir and is not encrypted (but the viewer -> ssh.company.com 1st leg is
an encrypted tunnel).
To SSH encrypt BOTH legs, try the "double SSH gateway" method using
the "comma" notation:
VNC Host:Display: localhost:0
Proxy/Gateway: ssh.company.com,joes-pc
this requires an SSH server also running on joes-pc. So an initial SSH
login is done to ssh.company.com, then a 2nd SSH is performed (through
port a redirection of the first) to login straight to joes-pc where
the VNC server is running.
Use username@host (e.g. joe@joes-pc jsmith@ssh.company.com) if the
user names differ between the various machines.
NOTE: On Windows you MUST always supply the username@ because putty's
plink requires it.
NON-STANDARD SSH PORT: To use a non-standard ssh port (i.e. a port other
than 22) you need to use the Proxy/Gateways as well. E.g. something
like this for port 2222:
VNC Host:Display: localhost:0
Proxy/Gateway: joe@far-away.east:2222
On Unix/MacOSX the username@ is not needed if it is the same as on
the client. This will also work going to a different internal machine,
e.g. "joes-pc:0" instead of "localhost:0", as in the first example.
A Web or SOCKS proxy can also be used with SSH. Use this if you are
inside a firewall that prohibits direct connections to remote SSH servers.
VNC Host:Display: joe@far-away.east:0
Proxy/Gateway: http://myproxy.west:8080
or for SOCKS:
VNC Host:Display: joe@far-away.east:0
Proxy/Gateway: socks://mysocks.west:1080
Use socks5://... to force the SOCKS5 version. Note that the http://
prefix is REQUIRED for web proxies in SSH or SSH+SSL modes (but it is
the default proxy type in SSL mode.)
You can chain up to 3 proxies (any combination of http://, socks://
and ssh) by separating them with commas (i.e. first,second,third).
Note: the Web and/or SOCKS proxies must come before any SSH gateways.
For a non-standard SSH port and a Web or SOCKS proxy try:
VNC Host:Display: localhost:0
Proxy/Gateway: http://myproxy.west:8080,joe@far-away.east:2222
Even the "double SSH gateway" method (2 SSH encrypted legs) described
above works with an initial Web or SOCKS proxy, e.g.:
VNC Host:Display: localhost:0
Proxy/Gateway: http://mysocks.west:1080,ssh.company.com,joes-pc
Some Notes on SSH localhost tunnelling with SSH options
NoHostAuthenticationForLocalhost=yes and UserKnownHostsFile=file:
Warning: Note that for proxy use with ssh(1), tunnels going through
'localhost' are used. This means ssh(1) thinks the remote hostname is
'localhost', which may cause collisions and confusion when storing
and checking SSH keys.
By default on Unix when a 'localhost' ssh host is involved the
ssh option -o NoHostAuthenticationForLocalhost=yes is applied (see
ssh_config(1) for details.) This avoids the warnings and ssh refusing
to connect, but it reduces security. A man in the middle attack may
be possible. SSVNC prints out a warning in the terminal every time
the NoHostAuthenticationForLocalhost option is used.
On Unix to disable the use of NoHostAuthenticationForLocalhost set the env.
variable SSVNC_SSH_LOCALHOST_AUTH=1. This may induce extra ssh(1) dialogs.
On Unix a MUCH SAFER and more convenient way to proceed is to set the
known hosts option in Options -> Advanced -> 'Private SSH KnownHosts file'
Then, only for the host in the current profile, a private known_hosts
file will be used and so there will be no 'localhost' collisions.
This method is secure (assuming you verify the SSH key fingerprint)
and avoids the man in the middle attack.
On Windows, Putty/Plink is used and does not have the UserKnownHosts
or NoHostAuthenticationForLocalhost features. Keys are stored in
the registry as localhost:port pairs and so it is possible to use the
'Port Slot' option to keep the keys separate to avoid the dialogs and
also maintain good security.
Note that for the "double SSH gateway" method the risk from using
NoHostAuthenticationForLocalhost is significantly less because the first
ssh connection does not use the option (it connects directly to the remote
host) and the second one is only exposed for the leg inside the first
gateway (but is still vulnerable there when NoHostAuthenticationForLocalhost
is used.)
UltraVNC Proxies/Gateways:
UltraVNC has a "repeater" tool (http://www.uvnc.com/addons/repeater.html
and http://koti.mbnet.fi/jtko/) that acts as a VNC proxy. SSVNC can
work with both mode I and mode II schemes of this repeater.
Note that even though the UltraVNC repeater tool is NOT SSL enabled,
it can nevertheless act as a proxy for SSVNC SSL connections.
This is because, just as with a Web proxy, the proxy negotiations
occur before the SSL traffic starts. (There is a separate UltraVNC
tool, repeater_SSL.exe, that is SSL enabled and is discussed below.)
Note: it seems only SSL SSVNC connections make sense with the
UltraVNC repeater. SSH connections (previous section) do not seem to
and so are not enabled to (let us know if you find a way to use it.)
Unencrypted (aka Direct) SSVNC VNC connections (Vnc:// prefix in
'VNC Host:Display'; see Tip 5) also work with the UltraVNC repeater.
For the mode I repeater the viewer initiates the connection and
passes a string that is the VNC server's IP address (or hostname)
and port or display:
VNC Host:Display: :0
Proxy/Gateway: repeater://myuvncrep.west:5900+joes-pc:1
Where "myuvncrep.west" is running the UltraVNC repeater and
"joes-pc:1" is the VNC server the repeater will connect us to.
Note here that the VNC Host:Display can be anything because it is
not used; we choose :0.
The Proxy/Gateway format is repeater://proxy:port+vncserver:display.
The string after the "+" sign is passed to the repeater server for
it to interpret (and so does not have to be the UltraVNC repeater;
you could create your own if you wanted to.) For this example,
instead of joes-pc:1 it could be joes-pc:5901 or 192.168.1.4:1,
192.168.1.4:5901, etc.
If you do not supply a proxy port, then the default 5900 is assumed,
e.g. use repeater://myuvncrep.west+joes-pc:1 for port 5901.
For the mode II repeater both the VNC viewer and VNC server initiate
connections to the repeater proxy. In this case they pass a string
that identifies their mutual connection via "ID:XYZ":
VNC Host:Display: :0
Proxy/Gateway: repeater://myuvncrep.west:5900+ID:1234
again, the default proxy port is 5900 if not supplied.
In this case, mode II, you MUST set Options -> Reverse VNC Connection.
That is to say a "Listening Connection". The reason for this is that
the VNC server acts as a SSL *client* and so requires the Viewer end
to have the SSL cert, (which it does in Listen mode).
Note that in Listening SSL mode you must supply a MyCert or use the
"listen.pem" one you are prompted to create.
We have also found that usually the Listening viewer must be started
BEFORE the VNC Server connects to the proxy. This bug may be in
SSVNC, x11vnc, or the repeater tool.
Set REPEATER_FORCE=1 in the Host:Display (then hit Enter, and then
clear it, and reenter host:disp) to force SSVNC to try a forward
connection in this situation.
Note that for unencrypted (i.e. direct) SSVNC connections (see vnc://
in Tip 5) there is no need to use a reverse "Listening connection"
and so you might as well use a forward connection.
For mode II when tunnelling via SSL, you probably should also disable
"Verify All Certs" unless you have taken the steps beforehand to
import the VNC server's certificate, or have previously accepted
it using another method. With the mode II proxying scheme, there
is no way to do the initial "Fetch Cert" and check if it has been
previously accepted.
Even when you disable "Verify All Certs", you are of course free to
set a ServerCert or CertsDir under "Certs ..." to authenticate the
VNC Server against.
Also, after the connection you MUST terminate the listening VNC Viewer
(Ctrl-C) and connect again (the proxy only runs once.) In Windows,
go to the System Tray and terminate the Listening VNC Viewer.
Subsequent connection attempts after the first one will fail unless
you return to the GUI and restart listening.
BTW, the x11vnc VNC server command for the mode II case would be
something like:
x11vnc -ssl SAVE -connect repeater=ID:1234+myuvncrep.west:5500 ...
x11vnc also supports -connect repeater://myuvncrep.west:5500+ID:1234
URL-like notation.
For mode I operation x11vnc simply runs as a normal SSL/VNC server
x11vnc -ssl SAVE
In the previous sections it was mentioned one can chain up to 3
proxies together by separating them with commas: proxy1,proxy2,proxy3.
Except where explicitly noted below this should work for "repeater://..."
as the final proxy. E.g. you could use a web proxy to get out of a
firewall, and then connect to a remote repeater.
The UltraVNC SSL enabled repeater_SSL.exe is discussed below.
UltraVNC Single Click:
UltraVNC has Single Click (SC) Windows VNC servers that allow naive
users to get them running very easily (a EXE download and a few
mouse clicks). See http://sc.uvnc.com/ for details on how to create
these binaries. Also there is a how-to here:
http://www.simply-postcode-lookup.com/SingleClickUltraVNC/SingleClickVNC.htm
The SC EXE is a VNC *server* that starts up a Reverse VNC connection
to a Listening Viewer (e.g. the viewer address/port/ID is hardwired
into the SC EXE). So SC is not really a proxy, but it can be used
with UltraVNC repeater proxies and so we describe it here.
One important point for SC III binary creation: do NOT include
"-id N" in the helpdesk.txt config file. This is because the with
SSVNC the Ultra VNC repeater IS NOT USED (see below for how to
use it). Use something like for helpdesk.txt:
[TITLE]
My UltraVNC SC III
[HOST]
Internet Support XYZ
-sslproxy -connect xx.xx.xx.xx:5500 -noregistry
(replace xx.xx.xx.xx with IP address or hostname of the SSVNC machine.)
The Unix SSVNC vncviewer supports the both the unencrypted "SC I"
mode and the SSL encrypted "SC III" mode. For both cases SSVNC
must be run in Listening mode (Options -> Reverse VNC Connection)
For SC I, enable Reverse VNC Connection and put Vnc://0 (see Tip 5
below) in the VNC Host:Display to disable encryption (use a different
number if you are not using the default listening port 5500).
Then click on the "Listen" button and finally have the user run your
Single Click I EXE.
BTW, we used this for a SC I helpdesk.txt:
[TITLE]
My UltraVNC SC I
[HOST]
Internet Support XYZ
-connect xx.xx.xx.xx:5500 -noregistry
For SC III (SSL), enable Reverse VNC Connection and then UNSET "Verify
All Certs" (this is required). Let the VNC Host:Display be ":0"
(use a different number if you are not using the default listening
port 5500). Then click on the "Listen" button and finally have the
user run your Single Click III EXE.
Note that in Listening SSL mode you MUST supply a MyCert or use the
"listen.pem" one you are prompted to create.
UltraVNC repeater_SSL.exe proxy:
For repeater_SSL.exe SSL usage, with Single Click III or otherwise
(available at http://www.uvnc.com/pchelpware/SCIII/index.html)
it helps to realize that the ENTIRE connection is SSL encrypted,
even the proxy host:port/ID:NNNN negotiation, and so a different
approach needs to be taken from that described above in 'UltraVNC
Proxies/Gateways'. In this case do something like this:
VNC Host:Display: :0
Proxy/Gateway: sslrepeater://myuvncrep.west:443+ID:1234
The sslrepeater:// part indicates the entire ID:XYZ negotiation must
occur inside the SSL tunnel. Listening mode is not required in this
case: a forward VNC connection works fine (and is recommended).
As before, the ":0" is simply a placeholder and is not used.
Note that the UltraVNC repeater_SSL.exe listens on port 443 (HTTPS),
(it is not clear that it can be modified to use another port.)
Non-ID connections sslrepeater://myuvncrep.west:443+host:disp also
work, but the 2nd leg repeater <-> host:disp must be unencrypted.
The first leg SSVNC <-> repeater is, however, SSL encrypted.
sslrepeater:// only works on Unix or MacOSX using the provided
SSVNC vncviewer. The modified viewer is needed; stock VNC viewers
will not work. Also, proxy chaining (bouncing off of more than one
proxy) currently does not work.
============================================================================
Help Misc:
SSVNC version: 1.0.26
Windows STUNNEL problems:
Note that on Windows when the Viewer connection is finished by default
SSVNC will try to kill the STUNNEL process for you.
If Options -> Kill Stunnel Automatically is not set you will be
prompted if you want SSVNC to try to kill the STUNNEL process for you.
Usually you will say Yes, however if there are problems connecting
you may want to look at the STUNNEL Log first.
Before it is killed, double clicking the STUNNEL tray icon (dark green)
will show you its Log file (useful for debugging connection problems).
Even though SSVNC will kill the STUNNEL process for you, you will
still need to move the mouse over the icon to make the little picture
go away!!! This is unfortunate but there does not seem to be a way
to avoid it.
In some cases you may need to terminate STUNNEL manually from the System
Tray (right click on dark green icon) and selecting "Exit".
Use -nokillstunnel or killstunnel=0 in ~/.ssvncrc to have SSVNC
start up with stunnel killing disabled.
Untrusted Local Users:
*IMPORTANT WARNING*: If you run SSVNC on a workstation or computer
that other users can log into and you DO NOT TRUST these users
(it is a shame but sometimes one has to work in an environment like
this), then please note the following warning.
By 'do not trust' we mean they might try to gain access to remote
machines you connect to via SSVNC. Note that an untrusted local
user can often obtain root access in a short amount of time; if a
user has acheived that, then all bets are off for ANYTHING that you
do on the workstation. It is best to get rid of Untrusted Local
Users as soon as possible.
Both the SSL and SSH tunnels set up by SSVNC listen on certain ports
on the 'localhost' address and redirect TCP connections to the remote
machine; usually the VNC server running there (but it could also be
another service, e.g. CUPS printing). These are the stunnel(8) SSL
redirection and the ssh(1) '-L' port redirection. Because 'localhost'
is used only users or programs on the same workstation that is
running SSVNC can connect to these ports, however this includes any
local users (not just the user running SSVNC.)
If the untrusted local user tries to connect to these ports, he may
succeed by varying degrees to gain access to the remote machine.
We now list some safeguards one can put in place to try to make this
more difficult to acheive.
It probably pays to have the VNC server require a password, even
though there has already been SSL or SSH authentication (via
certificates or passwords). In general if the VNC Server requires
SSL authentication of the viewer that helps, unless the untrusted
local user has gained access to your SSVNC certificate keys.
If the VNC server is configured to only allow one viewer connection
at a time, then the window of opportunity that the untrusted local
user can use is greatly reduced: he might only have a second or two
between the tunnel being set up and the SSVNC vncviewer connecting
to it (i.e. if the VNC server only allows a single connection, the
untrusted local user cannot connect once your session is established).
Similarly, when you disconnect the tunnel is torn down quickly and
there is little or no window of opportunity to connect (e.g. x11vnc
in its default mode exits after the first client disconnects).
Also for SSL tunnelling with stunnel(8) on Unix using one of the SSVNC
prebuilt 'bundles', a patched stunnel is provided that denies all
connections after the first one, and exits when the first one closes.
This is not true if the system installed stunnel(8) is used and is
not true when using SSVNC on Windows.
The following are experimental features that are added to SSVNC to
improve the situation for the SSL/stunnel and SSH cases. Set them
via Options -> Advanced -> "STUNNEL Local Port Protections" or
"SSH Local Port Protections".
STUNNEL:
1) For SSL tunnelling with stunnel(8) on Unix there is a setting
'Use stunnel EXEC mode' that will try to exec(2) stunnel
instead of using a listening socket. This will require using
the specially modified vncviewer unix viewer provided by SSVNC.
The mode works well and is currently set as the default.
Disable it if it causes problems or conflicts.
2) For SSL tunnelling with stunnel(8) on Unix there is a setting
'Use stunnel IDENT check' (experimental) to limit socket
connections to be from you (this assumes the untrusted local
user has not become root on your workstation and has modified
your local IDENT check service; if he has you have much bigger
problems to worry about...)
Neither of the above methods are available on Windows.
SSH:
1) There is also a simple LD_PRELOAD trick for SSH to limit the
number of accepted port redirection connections. This makes the
window of time the untrusted local user can connect to the tunnel
much smaller. Enable it via Options -> Advanced -> "SSH Local
Port Protections". You will need to have the lim_accept.so file
in your SSVNC package. The mode works well and is currently set
as the default. Disable it if it causes problems or conflicts.
The above method is not available on Windows.
The main message is to 'Watch your Back' when you connect via the
SSVNC tunnels and there are users you don't trust on your workstation.
The same applies to ANY use of SSH '-L' port redirections or outgoing
stunnel SSL redirection services.
============================================================================
Help Tips:
SSVNC version: 1.0.26
Tips and Tricks:
Table of Contents:
1) Connect to Non-Standard SSH port.
2) Reverse VNC connections (Listening)
3) Global options in ~/.ssvncrc
4) Fonts
5) vnc://host for un-encrypted connection
6) Home directory for memory stick usage, etc.
7) vncs:// vncssl:// vnc+ssl:// vnc+ssh:// URL-like prefixes
8) sshvnc / -ssh SSH only GUI
9) tsvnc / -ts Terminal services only GUI (SSH+x11vnc)
10) 2nd GUI window on Unix/MacOSX
11) Ctrl-L or Button3 to Load profile
12) SHELL command or Ctrl-S for SSH terminal w/o VNC
13) KNOCK command for port-knock sequence
14) Unix/MacOSX general SSL redirector (not just VNC)
15) Environment variables
16) Bigger "Open File" dialog window
17) Unix/MacOSX extra debugging output
18) Dynamic VNC Server Port determination with SSH
19) No -t ssh cmdline option for older sshd
1) To connect in SSH-Mode to a server running SSH on a non-standard
port (22 is the standard port) you need to use the Proxy/Gateway
setting. The following is from the Proxies Help panel:
NON-STANDARD SSH PORT: To use a non-standard ssh port (i.e. a port other
than 22) you need to use the Proxy/Gateways as well. E.g. something
like this for port 2222:
VNC Host:Display: localhost:0
Proxy/Gateway: joe@far-away.east:2222
The username@ is not needed if it is the same as on the client. This
will also work going to a different internal machine, e.g. "joes-pc:0"
instead of "localhost:0", as in the first example.
2) Reverse VNC connections (Listening) are possible as well.
In this case the VNC Server initiates the connection to your
waiting (i.e. listening) SSVNC viewer.
Go to Options and select "Reverse VNC connection". In the 'VNC
Host:Display' entry box put in the number (e.g. "0" or ":0", or
":1", etc) that corresponds to the Listening display (0 -> port
5500, 1 -> port 5501, etc.) you want to use. Then clicking on
'Listen' puts your SSVNC viewer in a "listening" state on that
port number, waiting for a connection from the VNC Server.
See the Options Help for more info.
3) You can put global options in your ~/.ssvncrc file (ssvnc_rc on
Windows). Currently they are:
Put "mode=tsvnc" or "mode=sshvnc" in the ~/.ssvncrc file to have
the application start up in the given mode.
desktop_type=wmaker (e.g.) to switch the default Desktop Type.
desktop_size=1280x1024 (e.g.) to switch the default Desktop Size.
desktop_depth=24 (e.g.) to switch the default Desktop Color Depth
xserver_type=Xdummy (e.g.) to switch the default X Server Type.
(The above 4 settings apply only to the Terminal Services Mode.)
noenc=1 (same as the -noenc option for a 'No Encryption' option)
noenc=0 (do not show the 'No Encryption' option)
killstunnel=1 (same as -killstunnel), on Windows automatically kills
the STUNNEL process when the viewer exits. Disable via killstunnel=0
and -nokillstunnel.
cotvnc=1 have the default vncviewer on Mac OS X be the Chicken of
the VNC. By default the included ssvnc X11 vncviewer is used
(requires Mac OS X X11 server to be running.)
mycert=file (same as -mycert file option). Set your default MyCert
to "file". If file does not exist ~/.vnc/certs/file is used.
cacert=file (same as -cacert file option). Set your default ServerCert
to "file". If file does not exist ~/.vnc/certs/file is used. If
file is "CA" then ~/.vnc/certs/CA/cacert.pem is used.
crl=file (same as -crl file option). Set your default CRL File
to "file". If file does not exist ~/.vnc/certs/file is used.
Prefix any of these cert/key files with "FORCE:" to make them
immutable, e.g. "cacert=FORCE:CA".
You can set any environment variable in ~/.ssvncrc by using a line
like env=VAR=value, for example: env=SSVNC_FINISH_SLEEP=2
To change the fonts (see Tip 4 below for examples):
font_default=tk-font-name (sets the font for menus and buttons)
font_fixed=tk-font-name (sets the font for help text)
4) Fonts: To change the tk fonts, set these environment variables
before starting up ssvnc: SSVNC_FONT_DEFAULT and SSVNC_FONT_FIXED.
For example:
% env SSVNC_FONT_DEFAULT='helvetica -20 bold' ssvnc
% env SSVNC_FONT_FIXED='courier -14' ssvnc
or set both of them at once. You can also set 'font_default' and
'font_fixed' in your ~/.ssvncrc. E.g.:
font_default=helvetica -16 bold
font_fixed=courier -12
5) If you want to make a Direct VNC connection, WITH *NO* SSL OR
SSH ENCRYPTION or authentication, use the "vnc://" prefix in the
VNC Host:Display entry box, e.g. "vnc://far-away.east:0" This
also works for reverse connections, e.g. vnc://0
Use Vnc:// (i.e. capital 'V') to avoid being prompted if you are
sure you want no encryption. For example, "Vnc://far-away.east:0"
Shift+Ctrl-E in the entry box is a short-cut to add or remove
the prefix "Vnc://" from the host:disp string.
You can also run ssvnc with the '-noenc' cmdline option (now
the default) to have a check option 'None' that lets you turn off
Encryption (and profiles will store this setting). Pressing Ctrl-E
on the main panel is a short-cut to toggle between the -noenc 'No
Encryption' mode and normal mode. The option "Show 'No Encryption'
Option" under Options also toggles it.
The '-enc' option disables the button (and so makes it less obvious
to naive users how to disable encryption.)
Note as of SSVNC 1.0.25 the '-noenc' mode is now the default. I.e.
the 'No Encryption' option ('None') is shown by default. When
you select 'None' you do not need to supply the "vnc://" prefix.
To disable the button supply the '-enc' cmdline option.
Setting SSVNC_DISABLE_ENCRYPTION_BUTTON=1 in your environment is
the same as -noenc. You can also put noenc=1 in your ~/.ssvncrc file.
Setting SSVNC_DISABLE_ENCRYPTION_BUTTON=0 in your environment is
the same as -enc. You can also put noenc=0 in your ~/.ssvncrc file.
Please be cautious/thoughtful when you make a VNC connection with
encryption disabled. You may send sensitive information (e.g. a
password) over the network that can be sniffed.
It is also possible (although difficult) for someone to hijack an
existing unencrypted VNC session.
Often SSVNC is used to connect to x11vnc where the Unix username and
password is sent over the channel. It would be a very bad idea to
let that data be sent over an unencrypted connection! In general,
it is not wise to have a plaintext VNC connection.
Note that even the VNC Password challenge-response method (the password
is not sent in plaintext) leaves your VNC password susceptible to a
dictionary attack unless encryption is used to hide it.
So (well, before we made the button visible by default!) we forced
you to learn about and supply the "vnc://" or "Vnc://" prefix to
the host:port or use -noenc or the "Show 'No Encryption' Option"
to disable encryption. This is a small hurdle, but maybe someone
will think twice. It is a shame that VNC has been around for
over 10 years and still does not have built-in strong encryption.
Note the Vnc:// or vnc:// prefix will be stored in any profile that
you save so you do not have to enter it every time.
Set the env var SSVNC_NO_ENC_WARN=1 to skip the warning prompts the
same as the capitalized Vnc:// does.
6) Mobile USB memory stick / flash drive usage: You can unpack
ssvnc to a flash drive for impromptu usage (e.g. from a friends
computer).
If you create a directory "Home" in the toplevel ssvnc directory,
then that will be the default location for your VNC profiles
and certs. So they follow the drive this way. If you run like
this: "ssvnc ." or "ssvnc.exe ." the "Home" directory will be
created for you.
WARNING: if you use ssvnc from an "Internet Cafe", i.e. an
untrusted computer, an unscrupulous person may be capturing
keystrokes, etc.!
You can also set the SSVNC_HOME env. var. to point to any
directory you want. It can be set after starting ssvnc by putting
HOME=/path/to/dir in the Host:Display box and clicking "Connect".
For a Windows BAT file to get the "Home" directory correct
something like this might be needed:
cd \ssvnc\Windows
start \ssvnc\Windows\ssvnc.exe
7) In the VNC Host:Display entry you can also use these "URL-like"
prefixes:
vncs://host:0, vncssl://host:0, vnc+ssl://host:0 for SSL
and
vncssh://host:0, vnc+ssh://host:0 for SSH
There is no need to toggle the SSL/SSH setting. These also work
from the command line, e.g.: ssvnc vnc+ssh://mymachine:10
8) If you want this application to be SSH only, then supply the
command line option "-ssh" or set the env. var SSVNC_SSH_ONLY=1.
Then no GUI elements specific to SSL will appear (the
documentation wills still refer to the SSL mode, however).
To convert a running app to ssh-only select "Mode: SSH-Only"
in Options.
The wrapper scripts "sshvnc" and "sshvnc.bat" will start it up
automatically this way.
Or in your ~/.ssvncrc (or ~/ssvnc_rc on Windows) put "mode=sshvnc"
to have the tool always start up in that mode.
9) For an even simpler "Terminal Services" mode use "tsvnc" or
"tsvnc.bat" (or "-ts" option). This mode automatically launches
x11vnc on the remote side to find or create your Desktop session
(usually the Xvfb X server). So x11vnc must be available on the
remote server machines under "Terminal Services" mode.
From a full ssvnc you can press Ctrl-h to go into ssh-only mode
and Ctrl-t to toggle between "tsvnc" and "ssvnc" modes. The
Options Mode menu also let you switch.
Or in your ~/.ssvncrc (or ~/ssvnc_rc on Windows) put "mode=tsvnc"
to have the tool always start up in that mode.
10) On Unix to get a 2nd GUI (e.g. for a 2nd connection) press Ctrl-N
on the GUI. If only the xterm window is visible you can press
Ctrl-N or try Ctrl-LeftButton -> New SSVNC_GUI. On Windows you
will have to manually Start a new one: Start -> Run ..., etc.
11) Pressing the "Load" button or pressing Ctrl-L or Clicking the Right
mouse button on the main GUI will invoke the Load dialog.
Pressing Ctrl-O on the main GUI will bring up the Options Panel.
Pressing Ctrl-A on the main GUI will bring up the Advanced Options.
12) If you use "SHELL" for the "Remote SSH Command" (or in the display
line: "user@hostname cmd=SHELL") then you get an SSH shell only:
no VNC viewer will be launched. On Windows "PUTTY" will try
to use putty.exe (better terminal emulation than plink.exe).
A ShortCut for this is Ctrl-S with user@hostname in the entry box.
13) If you use "KNOCK" for the "Remote SSH Command" (or in the display
line "user@hostname cmd=KNOCK") then only the port-knocking is done.
A ShortCut for this is Ctrl-P with hostname the entry box.
If it is KNOCKF, i.e. an extra "F", then the port-knocking
"FINISH" sequence is sent, if any. A ShortCut for this
Shift-Ctrl-P as long as hostname is present.
14) On Unix to have SSVNC act as a general STUNNEL redirector (i.e. no
VNC), put the desired host:port in VNC Host:Display (use a
negative port value if it is to be less than 200), then go to
Options -> Advanced -> Change VNC Viewer. Change the "viewer"
command to be "xmessage OK" or "xmessage " (or sleep) where
port is the desired local listening port. Then click Connect.
If you didn't set the local port look for it in the terminal output.
On Windows set 'viewer' to "NOTEPAD" or similar; you can't
control the port though. It is usually 5930, 5931, ... Watch
the messages or look at the stunnel log.
15) Tricks with environment variables:
You can change the X DISPLAY variable by typing DISPLAY=... into
VNC Host:Display and hitting Return or clicking Connect. Same
for HOME=. On Mac, you can set DYLD_LIBRARY_PATH=... too.
It should propagate down the viewer.
Setting SLEEP=n increases the amount of time waited before
starting the viewer. The env. var. SSVNC_EXTRA_SLEEP also does
this (and also Sleep: Option setting) Setting FINISH=n sets the
amount of time slept before the Terminal window exits on Unix
and MacOS X. (same as SSVNC_FINISH_SLEEP env. var.)
Full list of parameters HOME/SSVNC_HOME, DISPLAY/SSVNC_DISPLAY
DYLD_LIBRARY_PATH/SSVNC_DYLD_LIBRARY_PATH, SLEEP/SSVNC_EXTRA_SLEEP
FINISH/SSVNC_FINISH_SLEEP, DEBUG_NETSTAT, REPEATER_FORCE, SSH_ONLY.
(the ones joined by "/" are equivalent names, and the latter can
be set as an env. var. as well.)
After you set the parameter, clear out the 'VNC Host:Display'
entry and replace it with the actual host and display number.
To replace the xterm terminal where most of the external commands
are run set SSVNC_XTERM_REPLACEMENT to a command that will run
a command in a terminal. I.e.: "$SSVNC_XTERM_REPLACEMENT cmd"
will run cmd. If present, %GEOMETRY is expanded to a desired
+X+Y geometry. If present, %TITLE is expanded to a desired title.
Examples: SSVNC_XTERM_REPLACEMENT='gnome-terminal -e'
SSVNC_XTERM_REPLACEMENT='gnome-terminal -t "%TITLE" -e'
SSVNC_XTERM_REPLACEMENT='konsole -e'
16) On Unix you can make the "Open File" and "Save File" dialogs
bigger by setting the env. var. SSVNC_BIGGER_DIALOG=1 or
supplying the -bigger option. If you set it to a Width x Height,
e.g. SSVNC_BIGGER_DIALOG=500x200, that size will be used.
17) On Unix / MacOSX to enable debug output you can set these env.
vars to 1: SSVNC_STUNNEL_DEBUG, SSVNC_VENCRYPT_DEBUG, and
SS_DEBUG (very verbose)
18) Dynamic VNC Server Port determination and redirection: If you
are running SSVNC on Unix and are using SSH to start the remote
VNC server and the VNC server prints out the line "PORT=NNNN"
to indicate which dynamic port it is using (x11vnc does this),
then if you prefix the SSH command with "PORT=" SSVNC will watch
for the PORT=NNNN line and uses ssh's built in SOCKS proxy
(ssh -D ...) to connect to the dynamic VNC server port through
the SSH tunnel. For example:
VNC Host:Display user@somehost.com
Remote SSH Command: PORT= x11vnc -find -nopw
or "PORT= x11vnc -display :0 -localhost", etc. Or use "P= ..."
There is also code to detect the display of the regular Unix
vncserver(1). It extracts the display (and hence port) from
the lines "New 'X' desktop is hostname:4" and also
"VNC server is already running as :4". So you can use
something like:
PORT= vncserver; sleep 15
or: PORT= vncserver :4; sleep 15
the latter is preferred because when you reconnect with it will
find the already running one. The former one will keep creating
new X sessions if called repeatedly.
On Windows if PORT= is supplied SOCKS proxying is not used, but
rather a high, random value of the VNC port is chosen (e.g. 8453)
and assumed to be free, and is passed to x11vnc's -rfbport option.
This only works with x11vnc (not vncserver).
19) On Unix if you are going to an older SSH server (e.g. Solaris 10),
you will probably need to set the env. var. SS_VNCVIEWER_NO_T=1
to disable the ssh "-t" option being used (that can prevent the
command from being run).
============================================================================
SSL/SSH Viewer Options Help:
Use SSL: The default, use SSL via STUNNEL (this requires SSL aware VNC
server, e.g. x11vnc -ssl SAVE ...) See the description in the
main Help panel.
Use SSH: Instead of using STUNNEL SSL, use ssh(1) for the encrypted
tunnel. You must be able to log in via ssh to the remote host.
On Unix the cmdline ssh(1) program (it must already be installed)
will be run in an xterm for passphrase authentication, prompts
about RSA keys, etc. On Windows the cmdline plink.exe program
will be launched in a Windows Console window. (Apologies for
the klunkiness..)
You can set the "VNC Host:Display" to "user@host:disp" to
indicate ssh should log in as "user" on "host". NOTE: On
Windows you *MUST* always supply the "user@" part (due to a
plink deficiency). E.g.:
VNC Host:Display: fred@far-away.east:0
Gateway: If an intermediate gateway machine must be used
(e.g. to enter a firewall; the VNC Server is not running on it),
put it in the Proxy/Gateway entry, e.g.:
VNC Host:Display: workstation:0
Proxy/Gateway: user@gateway-host:port
ssh is used to login to user@gateway-host and then a -L port
redirection is set up to go to workstation:0 from gateway-host.
":port" is optional, use it if the gateway-host SSH port is
not the default value 22.
Chaining 2 ssh's: One can also do a "double ssh", i.e. a
first SSH to the gateway login machine then a 2nd ssh to the
destination machine (presumably it is running the vnc server).
Unlike the above example, the "last leg" (gateway-host ->
workstation) is also encrypted by SSH this way. Do this by
splitting the gateway in two with a comma, the part before it
is the first SSH:
VNC Host:Display: localhost:0
Proxy/Gateway: user@gateway-host:port,user@workstation:port
Web and SOCKS proxies can also be used with SSH:
VNC Host:Display: user@workstation:0
Proxy/Gateway: socks://socks.server:1080
See the "SSH Proxies/Gateways" in the Main Help document for full
details.
Remote Command: In the "Remote SSH Command" entry you can to
indicate that a remote command to be run. The default is
"sleep 15". For example, to run x11vnc for your X :0 display:
x11vnc -display :0 -nopw
Trick: If you use "SHELL" asl the "Remote SSH Command" then
you get an SSH shell only: no VNC viewer will be launched.
On Windows "PUTTY" will try to use putty.exe (better terminal
emulation than plink.exe) A shortcut for this is Ctrl-S as
long as user@hostname is present in the "VNC Host:Display" box.
Use SSH + SSL:
Tunnel the SSL connection through a SSH tunnel. Use this
if you want end-to-end SSL and must use a SSH gateway (e.g. to
enter a firewall) or if additional SSH port redirs are required
(CUPS, Sound, SMB tunnelling: See Advanced Options).
This is a RARELY used mode, but included in case the need arises.
No Encryption:
In '-noenc' mode, which is now the default, (Ctrl-E also toggles
this mode), use this to make a Direct connection to the VNC Server
with no encryption whatsoever. (Be careful about passwords, etc.)
The -noenc mode is now the default since SSVNC 1.0.25, use
the '-enc' cmdline option to disable the button.
Automatically Find X Session:
When using SSH mode to connect, you can select this option. It
simply sets the Remote SSH Command to:
PORT= x11vnc -find -localhost
This requires that x11vnc is installed on the remote computer
and is available in $PATH for the ssh login. The command
"x11vnc -find -localhost" command is run on the remote
machine.
The -find option causes x11vnc to try to find an existing X
session owned by the user (i.e. who you ssh in as). If it
does it attaches to it; otherwise the x11vnc VNC server exits
immediately followed by your VNC Viewer.
The PORT= option just means to let x11vnc pick its own
VNC port and then connect to whatever it picked. Use P=
for more debugging output.
The idea for this mode is you simply type 'username@workstation'
in the VNC Host:Display box, Select 'Options -> Automatically
Find X Session', and then click Connect. The tsvnc mode is
similar (it runs x11vnc on the remote side with the intent
of automatically finding, or creating, your desktop).
Unix Username & Password:
This is only available on Unix and MacOSX and when using
the SSVNC enhanced TightVNC viewer (it has been modified to
do Unix logins). It supports a login dialog with servers
doing something like x11vnc's "-unixpw" mode. After any
regular VNC authentication takes place (VNC Password), then
it sends the Unix Username, a Return, the Unix Password and
a final Return. This saves you from typing them into the
"login:" and "Password:" prompts in the viewer window.
Note that the x11vnc -unixpw login mode is external to the
VNC protocol, so you need to be sure the VNC server is in
this mode and will be waiting for the dialog. Otherwise the
username and password will be typed directly into the desktop
application that happens to have the focus!
When you select this option "Unix Username:" and "Unix
Password:" entry boxes appear on the main panel where you can
type them in. x11vnc has settings that can be specified after
a ":" in the Unix username; they may be used here as well.
(For example: username:3/4,nc for a smaller screen and -nocache)
If the Unix Username is not set when you click Connect, then
any SSH username@host is used. Otherwise the environment
variable $USER or $LOGNAME and finally whoami(1) is used.
Also Note that the Unix Password is never saved in a VNC
profile (so you have to type it each time). Also, the remote
x11vnc server is instructed to not echo the Username string
by sending an initial Escape. Set the SSVNC_UNIXPW_NOESC=1
environment variable to override this.
Reverse VNC Connection:
Reverse (listening) VNC connections are possible as well.
In this case the VNC Server initiates the connection to your
waiting (i.e. listening) SSVNC viewer.
For SSL connections in the 'VNC Host:Display' entry box put in
the number (e.g. "0" or ":0" or ":1", etc.) that corresponds to
the Listening display (0 -> port 5500, 1 -> port 5501, etc.) you
want to use. For example x11vnc can then be used via:
"x11vnc ... -ssl SAVE -connect hostname:port" using the "port"
with the one you chose.
Clicking on the 'Listen' button puts your SSVNC viewer
in a "listening" state on that port number, waiting for a
connection from the VNC Server.
Then a VNC server should establish a reverse connection to
that port on this machine (e.g. -connect this-machine:5500
or -connect this-machine:5503, etc.)
Server SSL certificates will be verified, however you WILL
NOT be prompted about unrecognized ones; rather, you MUST
set up the correct Server certificate (e.g. by importing).
prior to any connections.
If the connection is failing in Reverse VNC (listening) mode,
check the STUNNEL log output to see if STUNNEL is unable to
authenticate the VNC Server. If you want to allow in a
reverse connection with NO Server authentication, unset the
'Verify All Certs' option.
When listening in SSL, you will ALSO need to specify YOUR
OWN SSL cert, "MyCert", or otherwise let the GUI prompt you
to create a "listen.pem" and use that.
The "listen.pem" will be reused in later SSL Listening
connections unless you specify a different one with MyCert.
For reverse connections in SSH or SSH + SSL modes it is a
little trickier. The SSH tunnel (with -R tunnel) must be
established and remain up waiting for reverse connections.
The default time is "sleep 1800", i.e. 30 mins. You can put
a longer or shorter sleep in "Remote SSH Command" (perhaps
after your command runs: cmd; sleep 3600).
For SSH reverse connections put "hostname:n" in
'VNC Host:Display' or "user@hostname:n". The "n" will be the
listening display on the *REMOTE* side. So to have the remote
x11vnc connect use: "x11vnc ... -connect localhost:n" or
"x11vnc -R connect:localhost:n" (-ssl will be needed for SSH+SSL
mode). If the -R port cannot be opened because it is in use
by another program you will have to kill everything and start
over using a different port.
In reverse connections mode be careful to protect the listening
VNC Viewer from direct connections (neither SSL nor SSH)
connecting directly to its listening port thereby bypassing
the tunnel. This can be done by a host-level firewall that
only lets in, say, port 5500 (the default one ":0" for stunnel
to listen on). Or for SSH reverse connections allow NO 5500+n
ports in. For reverse connections, the Unix enhanced tightvnc
viewers supplied in the SSVNC package will only listen on
localhost so these precautions are not needed.
Note that for SSL connections use of "Proxy/Gateway" does not
make sense: the remote side cannot initiate its reverse connection
via the Proxy.
Note that for SSH or SSH+SSL connections use of "Proxy/Gateway"
does not make sense (the ssh cannot do a -R on a remote host:port),
unless it is a double proxy where the 2nd host is the machine with
the VNC server.
View Only: Have VNC Viewer ignore mouse and keyboard input.
Fullscreen: Start the VNC Viewer in fullscreen mode.
Raise On Beep: Deiconify viewer when bell rings.
Use 8bit color: Request a very low-color pixel format.
Do not use JPEG: Do not use the jpeg aspect of the tight encoding.
Use X11 vncviewer on MacOSX:
On MacOSX try to use the bundled X11 vncviewer
instead of the Chicken of the VNC viewer;
The Xquartz X server must be installed (it is by
default on 10.5.x) and the DISPLAY variable must
be set (see Tip 15 of Help to do this manually.)
Put cotvnc=1 in ~/.ssvncrc to switch the default.
Kill Stunnel Automatically:
On Windows, automatically try to kill the STUNNEL
process when the VNC Viewer exits. This is a
global setting (not per-profile); it can be also
set via either the -killstunnel cmdline option,
or killstunnel=1 in ssvnc_rc. To disable it supply
-nokillstunnel or put killstunnel=0 in ssvnc_rc.
As of 1/2009 this option is on by default.
The main drawback to having STUNNEL automatically
killed is that you will not be able to view its
logfile. If you are having trouble connecting via
SSL, disable this option and double click on the
dark green STUNNEL icon in the tray to view the log.
Compress Level/Quality: Set TightVNC encoding parameters.
Putty PW: On Windows only: use the supplied password for plink SSH
logins. Unlike the other options the value is not saved
when 'Save' is performed. This feature is useful when
options under "Advanced" are set that require TWO SSH's:
you just have to type the password once in this entry box.
The bundled pagent.exe and puttygen.exe programs can also
be used to avoid repeatedly entering passwords (note this
requires setting up and distributing SSH keys). Start up
pagent.exe or puttygen.exe and read the instructions there.
Note, that there is a small exposure to someone seeing the
putty password on the plink command line.
Note that the Putty PW is not cleared if you load in a
new VNC profile.
Port Slot: On Windows ports cannot be selected or checked as easily as
on Unix. So listening ports for ssh redirs, proxy tunnelling,
and etc. things are picked via finding a free "slot".
The slots run from 30 to 99 and are locked based on the
existence of a file with the slot number in it. When the
connection is about to be made, a free slot is found and used
to work out some ports (e.g. 5930 for the local VNC port,
etc.) This way simultaneous SSVNC connections can take place.
One drawback of this is that Putty/Plink stores SSH keys based
on hostname:port, and with a proxy tunnel the hostname is
"localhost". So the Putty key store may have key collisions
for the localhost tunnels, and plink will prompt you to
resolve the conflict WRT a different SSH key being discovered.
To work around this to some degree you can select a unique
Port Slot (in the range 50-99) for a specific host. Then the
ssh redir port to this host will never change and so the
Putty localhost:fixed-port key should remain valid.
Mode: To change the GUI Mode, select between the full SSVNC
(i.e. SSL and SSH), SSHVNC (i.e. SSH-Only), and Terminal
Services mode (TSVNC; uses x11vnc)
Note: You can put "mode=tsvnc" or "mode=sshvnc" in your
~/.ssvncrc file (ssvnc_rc on Windows) to have the application
start up in the given mode.
Show 'No Encryption' Option:
Note: since SSVNC 1.0.25 the 'No Encryption' Option is
enabled by default.
Select this to display a button that disables both SSL and
SSH encryption. This is the same as Ctrl+E. This puts
a check item "None" on the main panel and also a "No
Encryption" check item in the "Options" panel. If you
select this item, there will be NO encryption for the VNC
connection (use cautiously) See Tip 5) under Help for more
information about disabling encryption.
Buttons:
Use Defaults: Set all options to their defaults (i.e. unset).
Delete Profile: Delete a saved profile.
Advanced: Bring up the Advanced Options dialog.
Save and Load:
You can Save the current settings by clicking on Save
(.vnc file) and you can also read in a saved one with Load
Profile. Use the Browse... button to select the filename
via the GUI.
Pressing Ctrl-L or Clicking the Right mouse button on the
main GUI will invoke the Load dialog.
Note: On Windows since the TightVNC Viewer will save its own
settings in the Registry, some unexpected behavior is possible
because the viewer is nearly always directed to the VNC host
"localhost:30". E.g. if you specify "View Only" in this gui
once but not next time the Windows VNC Viewer may remember
the setting. Unfortunately there is not a /noreg option for
the Viewer.
============================================================================
Advanced Options Help:
These Advanced Options that may require extra software installed on
the VNC server-side (the remote server machine) and/or on the VNC
client-side (where this gui is running).
The Service redirection options, CUPS, ESD/ARTSD, and SMB will
require that you use SSH for tunneling so that they can use the -R
port redirection will be enabled for each service. I.e. "Use SSH"
or "SSH + SSL" mode.
These options may also require additional configuration to get them
to work properly. Please submit bug reports if it appears it should
be working for your setup but is not.
Brief (and some not so brief) descriptions:
CUPS Print tunnelling:
Redirect localhost:6631 (say) on the VNC server to your local
CUPS server. SSH mode is required.
ESD/ARTSD Audio tunnelling:
Redirect localhost:16001 (say) on the VNC server to your local
ESD, etc. sound server. SSH mode is required.
SMB mount tunnelling:
Redirect localhost:1139 (say) on the VNC server and through that
mount SMB file shares from your local server. The remote machine
must be Linux with smbmount installed. SSH mode is required.
Additional Port Redirs (via SSH):
Specify additional -L port:host:port and -R port:host:port
cmdline options for SSH to enable additional services.
SSH mode is required.
Automatically Find X Login/Greeter:
This mode is similar to "Automatically Find X Session" except
that it will attach to a X Login/Greeter screen that no one
has logged into yet. It requires root privileges via sudo(1)
on the remote machine. SSH mode is required.
As with "Automatically Find X Session" it works only with SSH
mode and requires x11vnc be installed on the remote computer.
It simply sets the Remote SSH Command to:
PORT= sudo x11vnc -find -localhost -env FD_XDM=1
An initial ssh running 'sudo id' is performed to try to
'prime' sudo so the 2nd one that runs x11vnc does not need
a password. This may not always succeed... please mail us
the details if it doesn't.
See the 'X Login' description in 'Terminal Services' Mode
Help for more info.
Private SSH KnownHosts file:
On Unix in SSH mode, let the user specify a non-default
ssh known_hosts file to be used only by the current profile.
This is the UserKnownHostsFile ssh option and is described in the
ssh_config(1) man page. This is useful to avoid proxy 'localhost'
SSH key collisions.
Normally one should simply let ssh use its default file
~/.ssh/known_hosts for tracking SSH keys. The only problem that
happens is when multiple SSVNC connections use localhost tunnel
port redirections. These make ssh connect to 'localhost' on some
port (where the proxy is listening.) Then the different keys
from the multiple ssh servers collide when ssh saves them under
'localhost' in ~/.ssh/known_hosts.
So if you are using a proxy with SSVNC or doing a "double SSH
gateway" your ssh will connect to a proxy port on localhost, and you
should set a private KnownHosts file for that connection profile.
This is secure and avoids man-in-the-middle attack (as long as
you actually verify the initial save of the SSH key!)
The default file location will be:
~/.vnc/ssh_known_hosts/profile-name.known
but you can choose any place you like. It must of course be
unique and not shared with another ssh connection otherwise they
both may complain about the key for 'localhost' changing, etc.
SSH Local Port Protections:
An LD_PRELOAD hack to limit the number of SSH port redirections
to 1 and within the first 35 seconds. So there is a smaller
window when the user can try to use your tunnel compared to
the duration of your session. SSH mode is required.
STUNNEL Local Port Protections:
Try to prevent Untrusted Local Users (see the main Help panel)
from using your STUNNEL tunnel to connect to the remote VNC
Server.
Change VNC Viewer:
Specify a non-bundled VNC Viewer (e.g. UltraVNC or RealVNC)
to run instead of the bundled TightVNC Viewer.
Port Knocking:
For "closed port" services, first "knock" on the firewall ports
in a certain way to open the door for SSH or SSL. The port
can also be closed when the encrypted VNC connection finishes.
UltraVNC DSM Encryption Plugin:
On Unix only, by using the supplied tool, ultravnc_dsm_helper,
encrypted connections to UltraVNC servers using their plugins
is enabled. Support for secret key encryption to Non-UltraVNC
DSM servers is also supported, e.g. x11vnc -enc blowfish:my.key
Do not Probe for VeNCrypt:
Disable VeNCrypt auto-detection probe when not needed.
By default in SSL mode an initial probe for the use of the
VeNCrypt or ANONTLS protocol is performed. This is done
during the initial fetch-cert action. Once auto-detected in
the initial probe, the real connection to the VNC Server will
use this information to switch to SSL/TLS at the right point in
the VeNCrypt/ANONTLS handshake.
In "Verify All Certs" mode initial the fetch-cert action is
required so the automatic probing for VeNCrypt is always done.
The fetch-cert is not needed if you specified a ServerCert or if
you disabled "Verify All Certs". But by default the fetch-cert
is done anyway to try to auto-detect VeNCrypt/ANONTLS.
Set 'Do not Probe for VeNCrypt' to skip this unneeded fetch-cert
action (and hence speed up connecting.) Use this if you
know the VNC Server uses normal SSL and not VeNCrypt/ANONTLS.
See also the next option, 'Server uses VeNCrypt SSL encryption'
to if you know it uses VeNCrypt/ANONTLS (the probing will also
be skipped if that option is set.)
Server uses VeNCrypt SSL encryption:
Indicate that the VNC server uses the VeNCrypt extension to VNC;
it switches to an SSL/TLS tunnel at a certain point in the
VNC Handshake. This is in constrast to the default ssvnc/x11vnc
SSL tunnel behavior where the *entire* VNC traffic goes through
SSL (i.e. it is vncs:// in the way https:// uses SSL)
Enable this option if you know the server supports VeNCrypt.
Also use this option for the older ANONTLS extension (vino).
Doing so will give the quickest and most reliable connection
to VeNCrypt/ANONTLS servers. If set, any probing to try to
auto-detect VeNCrypt/ANONTLS will be skipped.
Some VNC servers supporting VeNCrypt: VeNCrypt, QEMU, ggi,
virt-manager, and Xen. Vino supports ANONTLS.
The SSVNC VeNCrypt/ANONTLS support even works with 3rd party
VNC Viewers you specify via 'Change VNC Viewer' (e.g. RealVNC,
TightVNC, UltraVNC etc.) that do not directly support it.
Note: many VeNCrypt servers only support Anonymous Diffie Hellman
TLS which has NO built in authentication and you will also need
to set the option described in the next section.
If you are using VeNCrypt or ANONTLS for REVERSE connections
(Listen) then you *MUST* set this 'Server uses VeNCrypt SSL
encryption' option. Note also that REVERSE connections using
VeNCrypt/ANONTLS currently do not work on Windows.
Also, if you are using the "Use SSH+SSL" double tunnel to a
VeNCrypt/ANONTLS server, you MUST set 'Server uses VeNCrypt
SSL encryption' because "Verify All Certs" is disabled in
SSH+SSL mode.
Server uses Anonymous Diffie-Hellman
Anonymous Diffie-Hellman can be used for SSL/TLS connections but
there are no Certificates for authentication. Therefore only
passive eavesdropping attacks are prevented, not Man-In-The-Middle
attacks. Not recommended; try to use verified X509 certs instead.
Enable this option if you know the server only supports Anon DH.
When you do so, remember that ALL Certificate checking will be
skipped (even if you have 'Verify All Certs' selected or set
a ServerCert.)
SSVNC may be able to autodetect Anon DH even if you haven't
selected 'Server uses Anonymous Diffie-Hellman'. Once detected, it
will prompt you whether it should continue. Set the 'Server uses
Anonymous Diffie-Hellman' option to avoid trying autodetection
(i.e. forcing the issue.)
Note that most Anonymous Diffie-Hellman VNC Servers do so
via the VeNCrypt or ANONTLS VNC extensions (see the previous
section.) For these servers if you select 'Server uses Anonymous
Diffie-Hellman' you *MUST* ALSO select 'Server uses VeNCrypt SSL
encryption', otherwise SSVNC may have no chance to auto-detect
the VeNCrypt/ANONTLS protocol.
Also note, if you are using the "Use SSH+SSL" double tunnel to
a VeNCrypt/ANONTLS server using Anon DH you MUST set 'Server
uses Anonymous Diffie-Hellman' because "Verify All Certs"
is disabled in SSH+SSL mode.
Include:
Default settings and Include Templates:
Before explaining how Include works, first note that if you
do not prefer some of SSVNC's default settings you can start
up SSVNC and then change the settings for the options that you
want to have a different default value. Then type "defaults"
in VNC Host:Display entry box and press "Save" to save them in
the "defaults.vnc" profile. After this, SSVNC will initialize
all of the default values and then apply your override values
in "defaults".
For example, suppose you always want to use a different, 3rd
party VNC Viewer. Set Options -> Advanced -> Change VNC Viewer
to what you want, and then save it as the "defaults" profile.
Now that default setting will apply to all profiles, and SSVNC
in its startup state.
To edit the defaults Load it, make changes, and then Save it.
Delete the "defaults" profile to go back to no modifications.
Note that defaults created and saved while defaults.vnc existed
will NOT be automatically adjusted.
Include Templates:
Now suppose you have a certain class of settings that you do
not want to always be applied, but you want them to apply to a
group of profiles.
For example, suppose you have some settings for very low
bandwidth connections (e.g. low color modes and/or aggressive
compression and quality settings.) Set these values in SSVNC
and then in the VNC Host:Display entry box type in, say,
"slowlink" and then press Save. This will save those settings
in the template profile named "slowlink.vnc".
Now to create a real profile that uses this template type the
host:disp in "VNC Host:Display" and in Options -> Advanced
-> Includes type in "slowlink". Then press Save to save the
host profile. Then re-Load it. The "slowlink" settings will
be applied after the defaults. Make any other changes to the
setting for this profile and Save it again. Next time you load
it in, the Include template settings will override the defaults
and then the profile itself is read in.
You may supply a comma or space separated list of templates
to include. They are applied in the order listed. They can be
full path names or basenames relative to the profiles directory.
You do not need to supply the .vnc suffix. The non-default
settings in them will be applied first, and then any values in
the loaded Profile will override them.
Sleep:
Enter a number to indicate how many extra seconds to sleep
while waiting for the VNC viewer to start up. On Windows this
can give extra time to enter the Putty/Plink password, etc.
Unix ssvncviewer:
Display a popup menu with options that apply to the special
Unix SSVNC VNC Viewer (perhaps called 'ssvncviewer') provided by
this SSVNC package. This only applies to Unix or Mac OS X.
Use ssh-agent:
On Unix only: restart the GUI in the presence of ssh-agent(1)
(e.g. in case you forgot to start your agent before starting
this GUI). An xterm will be used to enter passphrases, etc.
This can avoid repeatedly entering passphrases for the SSH logins
(note this requires setting up and distributing SSH keys).
About the CheckButtons:
Ahem, Well...., yes quite a klunky UI: you have to toggle the
CheckButton to pull up the Dialog box a 2nd, etc. time... don't
worry your settings will still be there!
============================================================================
ssvncviewer Options Help:
These Unix SSVNC VNC Viewer Options apply only on Unix or Mac OS X
when using the viewer (ssvncviewer) supplied by this SSVNC package.
Brief descriptions:
Multiple LISTEN Connections:
Allow multiple VNC servers to reverse connect at the same time
and so display each of their desktops on your screen at the
same time.
Listen Once:
Try to have the VNC Viewer exit after the first listening
connection. (It may not always be detected; use Ctrl-C to exit)
Listen Accept Popup Dialog:
In -listen (reverse connection listening) mode when a reverse
VNC connection comes in show a popup asking whether to Accept
or Reject the connection. (-acceptpopup vncviewer option.)
Accept Popup UltraVNC Single Click:
As in 'Listen Accept Popup Dialog', except assume the remote
VNC server is UltraVNC Single Click and force the execution of
the protocol to retrieve the extra remote-side info (Windows
User, ComputerName, etc) which is then also displayed in the
Popup window. (-acceptpopupsc vncviewer option.)
Use X11 Cursor:
When drawing the mouse cursor shape locally, use an X11 cursor
instead of drawing it directly into the framebuffer. This
can sometimes give better response, and avoid problems under
'Scaling'.
Disable Bell:
Disable beeps coming from remote side.
Use Raw Local:
Use the VNC Raw encoding for 'localhost' connections (instead
of assuming there is a local tunnel, SSL or SSH, going to the
remote machine.
Avoid Using Terminal:
By default the Unix ssvncviewer will prompt for usernames,
passwords, etc. in the terminal it is running inside of.
Set this option to use windows for messages and prompting as
much as possible. Messages will also go to the terminal, but
all prompts will be done via popup window.
Note that stunnel(1) may prompt for a passphrase to unlock a
private SSL key. This is fairly rare because it is usually
for Client-side SSL authentication. stunnel will prompt from
the terminal; there seems to be no way around this.
Also, note that ssh(1) may prompt for an ssh key passphrase
or Unix password. This can be avoided in a number of ways,
the simplest one is to use ssh-agent(1) and ssh-add(1).
However ssh(1) may also prompt you to accept a new public key
for a host or warn you if the key has changed, etc.
Use Popup Fix:
Enable a fix that warps the popup (F8) to the mouse pointer.
Use XGrabServer (for fullscreen):
On Unix only, use the XGrabServer workaround for older window
managers. Sometimes also needed on recent (2008) GNOME. This
workaround can make going into/out-of Fullscreen work better.
Cursor Alphablending:
Use the x11vnc alpha hack for translucent cursors (requires Unix,
32bpp and same endianness)
TurboVNC:
If available on your platform, use a ssvncviewer compiled with
TurboVNC support. This is based on the VirtualGL project:
http://www.sourceforge.net/projects/virtualgl You will need
to install the VirtualGL's TurboJPEG library too.
Currently (May/2009) only Linux.i686, Linux.x86_64, and
Darwin.i386 have vncviewer.turbovnc binaries shipped in the
ssvnc bundles. See the build instructions for how you might
compile your own.
Disable Pipelined Updates:
Disable the TurboVNC-like pipelined updates mode. Pipelined
updates is the default even when not TurboVNC enabled. They
ask for the next screen update before the current one has
finished downloading, and so this might reduce the slowdown
due to high latency or low bandwidth by 2X or so. Disable
them if they cause problems with the remote VNC Server or
use too much bandwidth.
Send CLIPBOARD not PRIMARY:
When sending locally selected text to the VNC server side,
send the CLIPBOARD selection instead of the PRIMARY selection.
Send Selection Every time:
Send selected text to the VNC server side every time the mouse
focus enters the main VNC Viewer window instead only when it
appears to have changed since the last send.
Scaling:
Use viewer-side (i.e. local) scaling of the VNC screen. Supply
a fraction, e.g. 0.75 or 3/4, or a WxH geometry, e.g. 1280x1024,
or the string 'fit' to fill the current screen. Use 'auto'
to scale the desktop to match the viewer window size.
If you observe mouse trail painting errors try using X11 Cursor.
Note that since the local scaling is done in software it can
be slow. Since ZRLE is better than Tight in this regard, when
scaling is detected, the encoding will be switched to ZRLE.
Use the Popup to go back to Tight if you want to, or set the
env. var. SSVNC_PRESERVE_ENCODING=1 to disable the switch.
For additional speedups under local scaling: try having a solid
desktop background on the remote side (either manually or using
'x11vnc -solid ...'); and also consider using client side caching
'x11vnc -ncache 10 ...' if the remote server is x11vnc.
Escape Keys:
Enable 'Escape Keys', a set of modifier keys that, if all are
pressed down, enable local Hot Key actions. Set to 'default'
to use the default (Alt_L,Super_L on unix, Control_L,Meta_L
on macosx) or set to a list of modifier keys.
Y Crop:
This is for x11vnc's -ncache client side caching scheme with our
Unix TightVNC viewer. Sets the Y value to "crop" the viewer
size at (below the cut is the pixel cache region you do not
want to see). If the screen is tall (H > 2*W) ycropping will
be autodetected, or you can set to -1 to force autodection.
Otherwise, set it to the desired Y value. You can also set
the scrollbar width (very thin by default) by appending ",sb=N"
(or use ",sb=N" by itself to just set the scrollbar width).
ScrollBar Width:
This is for x11vnc's -ncache client side caching scheme with our
Unix TightVNC viewer. For Y-Crop mode, set the size of the
scrollbars (often one want it to be very narrow, e.g. 2 pixels
to be less distracting.
RFB Version:
Set the numerical version of RFB (VNC) protocol to pretend to
be, 3.x. Usually only needed with UltraVNC servers.
Encodings:
List encodings in preferred order, for example
'copyrect zrle tight' The list of encodings is:
copyrect tight zrle zywrle hextile zlib corre rre raw
Extra Options:
String of extra Unix ssvncviewer command line options. I.e. for
ones like -16bpp that cannot be set inside this SSVNC GUI. For a
list click Help then 'SSVNC vncviewer -help Output'.
These are environment variables one may set to affect the options
of the SSVNC vncviewer:
VNCVIEWER_ALPHABLEND (-alpha, see Cursor Alphablending above)
VNCVIEWER_POPUP_FIX (-popupfix, warp popup to mouse location)
VNCVIEWER_GRAB_SERVER (-graball, see Use XGrabServer above)
VNCVIEWER_YCROP (-ycrop, see Y Crop above)
VNCVIEWER_SBWIDTH (-sbwidth, see ScrollBar Width above)
VNCVIEWER_RFBVERSION (-rfbversion, e.g. 3.6)
VNCVIEWER_ENCODINGS (-encodings, e.g. "copyrect zrle hextile")
VNCVIEWER_NOBELL (-nobell)
VNCVIEWER_X11CURSOR (-x11cursor, see Use X11 Cursor above)
VNCVIEWER_RAWLOCAL (-rawlocal, see Use Raw Local above)
VNCVIEWER_NOTTY (-notty, see Avoid Using Terminal above)
VNCVIEWER_ESCAPE (-escape, see Escape Keys above)
VNCVIEWER_ULTRADSM (-ultradsm)
VNCVIEWER_SEND_CLIPBOARD (-sendclipboard)
VNCVIEWER_SEND_ALWAYS (-sendalways)
VNCVIEWER_RECV_TEXT (-recvtext clipboard/primary/both)
VNCVIEWER_NO_CUTBUFFER (do not send CUTBUFFER0 as fallback)
VNCVIEWER_NO_PIPELINE_UPDATES (-nopipeline)
VNCVIEWERCMD (unix viewer command, default vncviewer)
VNCVIEWERCMD_OVERRIDE (force override of VNCVIEWERCMD)
VNCVIEWERCMD_EXTRA_OPTS (extra options to pass to VNCVIEWERCMD)
VNCVIEWER_LISTEN_LOCALHOST (force ssvncviewer to -listen on localhost)
VNCVIEWER_NO_SEC_TYPE_TIGHT(force ssvncviewer to skip rfbSecTypeTight)
SSVNC_MULTIPLE_LISTEN (-multilisten, see Multiple LISTEN above)
SSVNC_ACCEPT_POPUP (-acceptpopup, see Accept Popup Dialog)
SSVNC_ACCEPT_POPUP_SC (-acceptpopupsc, see Accept Popup Dialog)
SSVNC_TURBOVNC (see TurboVNC above)
SSVNC_UNIXPW (-unixpw)
SSVNC_UNIXPW_NOESC (do not send escape in -unixpw mode)
SSVNC_SCALE (-scale, see Scaling above)
SSVNC_NOSOLID (do not do solid region speedup in
scaling mode.)
SSVNC_PRESERVE_ENCODING (do not switch to ZRLE when scaling)
SSVNC_FINISH_SLEEP (on unix/macosx sleep this many seconds
before exiting the terminal, default 5)
Misc (special usage or debugging or ss_vncviewer settings):
SSVNC_MESG_DELAY (sleep this many millisec between messages)
SSVNC_EXTRA_SLEEP (same as Sleep: window)
SSVNC_NO_ULTRA_DSM (disable ultravnc dsm encryption)
SSVNC_ULTRA_FTP_JAR (file location of ultraftp.jar jar file)
SSVNC_KNOWN_HOSTS_FILE (file for per-connection ssh known hosts)
SSVNC_SCALE_STATS
SSVNC_DEBUG_RELEASE
SSVNC_DEBUG_ESCAPE_KEYS
SSVNC_NO_MAYBE_SYNC
SSVNC_MAX_LISTEN (number of time to listen for reverse conn.)
SSVNC_LISTEN_ONCE (listen for reverse conn. only once)
SSVNC_EXIT_DEBUG
SSVNC_DEBUG_CHAT
SSVNC_NO_MESSAGE_POPUP
SSVNC_SET_SECURITY_TYPE
SSVNC_PREDIGESTED_HANDSHAKE
SSVNC_SKIP_RFB_PROTOCOL_VERSION
SSVNC_DEBUG_SEC_TYPES
SSVNC_DEBUG_MSLOGON
SSVNC_DEBUG_RECTS
SSVNC_DEBUG_CHAT
SSVNC_DELAY_SYNC
SSVNC_DEBUG_SELECTION
SSVNC_REPEATER
SSVNC_VENCRYPT_DEBUG
SSVNC_STUNNEL_DEBUG
SSVNC_TEST_SEC_TYPE
SSVNC_LIM_ACCEPT_PRELOAD
SSVNC_SOCKS5
============================================================================
SSL Certificates Help:
Description:
*** IMPORTANT ***: Only with SSL Certificate verification (either manually
or via a Certificate Authority certificate) can Man-In-The-Middle attacks be
prevented. Otherwise, only passive network sniffing attacks are prevented.
There are hacker tools like dsniff/webmitm and cain that implement SSL
Man-In-The-Middle attacks. They rely on the client user not bothering to
check the cert.
The SSL Certificate files described below may have been created externally
(e.g. by x11vnc or openssl): you can import them via "Import Certificate".
OR you can click on "Create Certificate ..." to use THIS program to generate
a Certificate + Private Key pair for you (in this case you will need to
distribute one of the generated files to the VNC Server).
Then you associate the Saved cert with the VNC server, see the panel entry
box description below. Then click Connect. You will usually want to Save
this association in a VNC Server profile for the next time you connect.
Expiration:
SSL Certificates will Expire after a certain period (usually 1-2 years;
if you create a cert with this tool you can set it to any length you want).
So if for a particular Cert you find you can no longer connect, check the
STUNNEL log output to see if the cert has expired. Then create and distribute
a new one.
Fetch Cert:
You can also retrieve and view the VNC Server's Cert via the "Fetch Cert"
button on the main panel. After you check that it is the correct Cert (e.g. by
comparing MD5 hash or other info), you can save it. The file it was saved
as will be set as the "ServerCert" to verify against for the next connection.
To make this verification check permanent, you will need to save the profile
via 'Save'.
NOTE: See the CA section below for how "Fetch Cert/Verify All Certs" WILL NOT
WORK when a Certificate Authority (CA) is used (i.e. you need to save the CA's
cert instead.) It will work if the certificate is Self-Signed.
Verify All Certs:
If "Verify All Certs" is checked on the main panel, you are always forced
to check unrecognized server certs, and so the first time you connect to
a new server you may need to follow a few dialogs to inspect and save the
server certificate.
Under "Verify All Certs", new certificates are saved in the 'Accepted Certs'
directory. When the checkbox is set all host profiles with "CertsDir" set to
"ACCEPTED_CERTS" (and an empty "ServerCert" setting) will be checked against
the pool of accepted certificates in the 'Accepted Certs' directory.
Note that we have "Verify All Certs" on by default so that users who do not
understand the SSL Man-In-The-Middle problem will not be left completely
vulnerable to it. Everyone still must make the effort to verify new
certificates by an external method to be completely safe.
To have "Verify All Certs" toggled off at startup, use "ssvnc -nv" or set
SSVNC_NO_VERIFY_ALL=1 before starting. If you do not even want to see the
button, use "ssvnc -nvb" or SSVNC_NO_VERIFY_ALL_BUTTON=1.
Note: "Fetch Cert" and "Verify All Certs" are currently not implemented in
"SSH + SSL" mode. In this case to have server authentication "ServerCert"
must be set explicitly to a file (or "CertsDir" to a directory).
Also note that "Fetch Cert" only works in a limited fashion in "Listen"
mode (it is the VNC Server that initiates the connection), and so you
may need to be set via "ServerCert" as well.
NOTE: See the CA section below for how "Fetch Cert/Verify All Certs"
WILL NOT WORK when a Certificate Authority (CA) is used (i.e. you need
to save the CA's cert instead.) The "Fetch Cert" saving method will
work if the certificate is Self-Signed.
CA:
One can make SSL VNC server authentication more "automatic" as it is in
Web Browsers going to HTTPS sites, by using a Certificate Authority (CA)
cert (e.g. a professional one like Verisign or Thawte, or one your company
or organization creates) for the "ServerCert". This is described in detail
here: http://www.karlrunge.com/x11vnc/ssl.html
CA's are not often used, but if the number of VNC Servers scales up it can
be very convenient because the viewers (i.e. SSVNC) only need the CA cert,
not all of the Server certs.
IMPORTANT NOTE: if a VNC Server is using a CA signed certificate instead
of its own Self-Signed one, then "Fetch Cert", etc. saving mechanism
WILL NOT WORK. You must obtain the CA certificate and explicitly set
it as the ServerCert or import it to 'Accepted Certs'.
Now what goes into the panel's entry boxes is described.
Your Certificate + Key (MyCert):
You can specify YOUR own SSL certificate (PEM) file in "MyCert" in which
case it is used to authenticate YOU (the viewer) to the remote VNC Server.
If this fails the remote VNC Server will drop the connection.
So the Server could use this method to authenticate Viewers instead of the
more common practice of using a VNC password or x11vnc's -unixpw mode.
Server Certificates (ServerCert/CertsDir):
Server certs can be specified in one of two ways:
- A single certificate (PEM) file for a single server
or a single Certificate Authority (CA)
- A directory of certificate (PEM) files stored in
the special OpenSSL hash fashion.
The former is set via "ServerCert" in this gui.
The latter is set via "CertsDir" in this gui.
The former corresponds to the "CAfile" STUNNEL parameter.
The latter corresponds to the "CApath" STUNNEL parameter.
See stunnel(8) or stunnel.mirt.net for more information.
If the remote VNC Server fails to authenticate itself with respect to the
specified certificate(s), then the VNC Viewer (your side) will drop the
connection.
Select which file or directory by clicking on the appropriate "Browse..."
button. Once selected, if you click Info or the Right Mouse button on
"Browse..." then information about the certificate will be displayed.
If, as is the default, "CertsDir" is set to the token "ACCEPTED_CERTS"
(and "ServerCert" is unset) then the certificates accumulated in the special
'Accepted Certs' directory will be used. "ACCEPTED_CERTS" is the default for
every server ("Verify All Certs"). Note that if you ever need to clean this
directory, each cert is saved in two files, for example:
hostname-0=bf-d0-d6-9c-68-5a-fe-24-c6-60-ba-b4-14-e6-66-14.crt
and
9eb7c8be.0
This is because of the way OpenSSL must use hash-based filenames in Cert dirs.
The file will have a "full filename:" line indicating the fingerprint and
hostname associated with it. Be sure to remove both files. The Delete Certs
dialog should automatically find the matching one for you and prompt you to
remove it as well.
Certificate Revocation List (CRL File):
For large scale deployments, usually involving a CA Cert, it is worthwhile
to be able to revoke individual certs (so that a new CA cert does not need to
be created and new keys distributed). Set CRL File to the path to the
file containing the revoked certificates (or a directory containing
OpenSSL style hash-based filenames.) See the x11vnc -sslCRL documentation
for how to create CRL's. In short, the commands 'openssl ca -revoke ...'
and 'openssl ca -gencrl ...' are the ones to look for; See the ca(1) manpage.
Create Certificate:
A simple dialog to create a Self-Signed Certificate. See the x11vnc
-sslGenCA, -sslGenCert options for creating a CA Cert and signing with it.
Import Certificate:
You can paste in a Certificate or read one in from a file to add to your
list of Server Certificates. If (also) saved in the 'Accepted Certs'
directory, it will be automatically used to verify any Server when in
'Verify All Certs' Mode.
Deleting Certificates:
To delete a Certificate+private_key pair click on "Delete Certificate"
and select one in the menu. You will be prompted to remove it,
and also any corresponding .pem or .crt file. For "ACCEPTED_CERTS"
it will find the matching "HASH" file and prompt you to remove that too.
Default Certs and Keys:
Use the "-mycert file" option (same as "-cert file") to set a default
MyCert. The user will then have to manually clear the field to not
use a certificate. This is the same as "mycert=file" (also "cert=file")
in the ~/.ssvncrc file. If "file" does not exist, then ~/.vnc/certs is
prepended to it.
Use the "-cacert file" option (same as "-ca file") to set a default
ServerCert. The user will then have to manually clear the field to not
set a server cert. This is the same as "cacert=file" (also "ca=file")
in the ~/.ssvncrc file. If "file" does not exist, then ~/.vnc/certs is
prepended to it. Use "-cacert CA" to set it to ~/.vnc/certs/CA/cacert.pem
Use the "-crl file" option to set a default CRL File. The user will
then have to manually clear the field to not use a CRL. This is the
same as "crl=file" in the ~/.ssvncrc file. If "file" does not exist,
then ~/.vnc/certs is prepended to it.
A sys-admin might set up an SSVNC deployment for user's workstations or
laptops using one or more of -cacert (authenticate VNC server to the
user) or -mycert (authenticate user to VNC server) or -crl (supply a
list of revoked certificates). Prefix either one with "FORCE:" to make
the setting unchangable.
Notes:
If "Use SSH" has been selected then SSL certs are disabled.
See the x11vnc and STUNNEL documentation for how to create and use PEM
certificate files:
http://www.karlrunge.com/x11vnc/faq.html#faq-ssl-tunnel-ext
http://www.karlrunge.com/x11vnc/ssl.html
http://stunnel.mirt.net
A common way to create and use a VNC Server certificate is:
x11vnc -ssl SAVE ...
and then copy the Server certificate to the local (viewer-side) machine.
x11vnc prints out to the screen the Server certificate it generates
(stored in ~/.vnc/certs/server.crt). You can set "ServerCert" to it
directly or use the "Import Certificate" action to save it to a file.
Or use the "Fetch Cert" method to retrieve it (be sure to verify the
MD5 fingerprint, etc).
x11vnc also has command line utilities to create server, client, and CA
(Certificate Authority) certificates and sign with it. See the above URLs.
============================================================================
Fetch Certificates Help:
The displayed SSL Certificate has been retrieved from the VNC Server via the
"Fetch Cert" action.
It has merely been downloaded via the SSL Protocol:
*** IT HAS NOT BEEN VERIFIED OR AUTHENTICATED IN ANY WAY ***
So, in principle, it could be a fake certificate being inserted by a bad
person attempting to perform a Man-In-The-Middle attack on your SSL connection.
If, however, by some external means you can verify the authenticity of this SSL
Certificate you can use it for your VNC SSL connection to the VNC server you
wish to connect to. It will provide an authenticated and encrypted connection.
You can verify the SSL Certificate by comparing the MD5 or SHA1 hash value
via a method/channel you know is safe (i.e. not also under control of a
Man-In-The-Middle attacker). You could also check the text between the
-----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- tags, etc.
Once you are sure it is correct, you can press the Save button to save the
certificate to a file on the local machine for use when you connect via VNC
tunneled through SSL. If you save it, then that file will be set as the
Certificate to verify the VNC server against. You can see this in the dialog
started via the "Certs..." button on the main panel.
NOTE: If you want to make Permanent the association of the saved SSL certificate
file with the VNC server host, you MUST save the setting as a profile for
loading later. To Save a Profile, click on Options -> Save Profile ...,
and choose a name for the profile and then click on Save.
If "Verify All Certs" is checked, then you are forced to check all new certs.
In this case the certs are saved in the 'Accepted Certs' directory against
which all servers will be checked unless "ServerCert" or "CertsDir" has been
set to something else.
To reload the profile at a later time, click on the "Load" button on the
main panel and then select the name and click "Open". If you want to be
sure the certificate is still associated with the loaded in host, click on
"Certs..." button and make sure the "ServerCert" points to the desired SSL
filename.
See the Certs... Help for more information. A sophisticated method can be set
up using a Certificate Authority key to verify never before seen certificates
(i.e. like your web browser does).
============================================================================
Create SSL Certificate Dialog:
This dialog helps you to create a simple Self-Signed SSL certificate.
On Unix the openssl(1) program must be installed and in $PATH.
On Windows, a copy of the openssl program is provided for convenience.
The resulting certificate files can be used for either:
1) authenticating yourself (VNC Viewer) to a VNC Server
or 2) your verifying the identity of a remote VNC Server.
In either case you will need to safely copy one of the generated key or
certificate files to the remote VNC Server and have the VNC Server use
it. Or you could send it to the system administrator of the VNC Server.
For the purpose of description, assume that the filename selected in the
"Save to file" entry is "vnccert.pem". That file will be generated
by this process and so will the "vnccert.crt" file. "vnccert.pem"
contains both the Private Key and the Public Certificate. "vnccert.crt"
only contains the Public Certificate.
For case 1) you would copy "vnccert.crt" to the VNC Server side and
instruct the server to use it. For x11vnc it would be for example:
x11vnc -sslverify /path/to/vnccert.crt -ssl SAVE ...
(it is also possible to handle many client certs at once in a directory,
see the -sslverify documentation). Then you would use "vnccert.pem"
as the MyCert entry in the SSL Certificates dialog.
For case 2) you would copy "vnccert.pem" to the VNC Server side and
instruct the server to use it. For x11vnc it would be for example:
x11vnc -ssl /path/to/vnccert.pem
Then you would use "vnccert.crt" as the as the ServerCert entry in the
"SSL Certificates" dialog.
Creating the Certificate:
Choose a output filename (ending in .pem) in the "Save to file" entry.
Then fill in the identification information (Country, State or Province,
etc).
The click on "Create" to generate the certificate files.
Encrypting the Private Key: It is a very good idea to encrypt the
Private Key that goes in the "vnccert.pem". The downside is that
whenever that key is used (e.g. starting up x11vnc using it) then
the passphrase will need to be created. If you do not encrypt it and
somebody steals a copy of the "vnccert.pem" file then they can pretend
to be you.
After you have created the certificate files, you must copy and import
either "vnccert.pem" or "vnccert.pem" to the remote VNC Server and
also select the other file in the "SSL Certificates" dialog.
See the description above.
For more information see:
http://www.karlrunge.com/x11vnc/ssl.html
http://www.karlrunge.com/x11vnc/faq.html#faq-ssl-tunnel-int
The first one describes how to use x11vnc to create Certificate
Authority (CA) certificates in addition to Self-Signed ones.
Tip: if you choose the "Common Name" to be the internet hostname
(e.g. gateway.mydomain.com) that connections will be made to or
from that will avoid many dialogs when connecting mentioning that
the hostname does not match the Common Name.
============================================================================
Import SSL Certificate Dialog:
This dialog lets you import a SSL Certificate by either pasting one in or by
loading from another file. Choose which input mode you want to use by the toggle
"Paste / Read from File".
There are two types of files we use 1) Certificate only, and 2) Private Key
and Certificate.
Type 1) would be used to verify the identity of a remote VNC Server, whereas
type 2) would be used to authenticate ourselves to the remote VNC Server.
A type 1) by convention ends with file suffix ".crt" and looks like:
-----BEGIN CERTIFICATE-----
MIID2jCCAsKgAwIBAgIJALKypfV8BItCMA0GCSqGSIb3DQEBBAUAMIGgMQswCQYD
(more lines) ...
TCQ+tbQ/DOiTXGKx1nlcKoPdkG+QVQVJthlQcpam
-----END CERTIFICATE-----
A type 2) by convention ends with file suffix ".pem" and looks like:
-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEA4sApd7WaPKQRWnFe9T04D4pglQB0Ti0/dCVHxg8WEVQ8OdcW
(more lines) ...
9kBmNotUiTpvRM+e7E/zRemhvY9qraFooqMWzi9JrgYfeLfSvvFfGw==
-----END RSA PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
MIID2jCCAsKgAwIBAgIJALKypfV8BItCMA0GCSqGSIb3DQEBBAUAMIGgMQswCQYD
(more lines) ...
TCQ+tbQ/DOiTXGKx1nlcKoPdkG+QVQVJthlQcpam
-----END CERTIFICATE-----
You do not need to use the ".crt" or ".pem" convention if you do not want to.
First, either paste in the text or set the "Read from File" filename.
Next, set the "Save to File" name to the file where the imported certificate
will be saved.
Then, click on "Save" to save the imported Certificate.
After you have imported the Certificate (or Key + Certificate), select it to
use for a connection via the "MyCert" or "ServerCert" dialog.
============================================================================
Save SSL Certificate Dialog:
This dialog lets you import a SSL Certificate retrieved from a VNC server.
Be sure to have verified its authenticity via an external means (checking
the MD5 hash value sent to you by the administrator, etc)
Set "Save to File" to the filename where the imported cert will be saved.
If you also want the Certificate to be saved to the pool of certs in the
'Accepted Certs' directory, select the checkbox. By default all Servers are
verified against the certificates in this pool.
Then, click on "Save" to save the imported Certificate.
After you have imported the Certificate it will be automatically selected as
the "ServerCert" for the next connection to this host: help:0
To make the ServerCert setting to the imported cert file PERMANENT, select
'Save' to save it in the profile for this host.
============================================================================
Terminal Services Help:
SSVNC version: 1.0.26
Terminal Services:
The Terminal Services VNC Viewer uses SSH to establish an encrypted
and authenticated connection to the remote server.
Through the SSH channel, it automatically starts x11vnc in terminal
services mode on the remote server to find or create your desktop
session. x11vnc is used for both the session management and the
VNC transport.
You MUST be able to log in via SSH to the remote terminal server.
Ask your administrator to set this up for you if it isn't already.
x11vnc must also be installed on the remote server machine.
See "Requirements" below.
This mode is started by the commands 'tsvnc' or 'ssvnc -ts' or
toggled by pressing Ctrl-t. "SSVNC Mode" under Options -> Advanced
will also return to the full SSVNC.
Or in your ~/.ssvncrc (or ~/ssvnc_rc on Windows) put "mode=tsvnc"
to have the tool always start up in that mode. To constrain the UI,
run with -tso or SSVNC_TS_ALWAYS set to prevent leaving the Terminal
Services mode.
Hosts and Displays:
Enter the remote VNC Terminal Services hostname in the
'VNC Terminal Server' entry.
Examples:
24.67.132.27
far-away.east
fred@someplace.no
Then click on "Connect".
Once the SSH is running (you may need to type a password or accept
a new ssh key in the terminal window that pops up), the VNC Viewer
will be automatically started directed to the local port of the SSH
tunnel which, in turn, encrypts and redirects the connection to the
remote VNC server.
x11vnc is run remotely to find or create your terminal services desktop
session. It must be installed and accessible on the remote system.
Enter "user@hostname.com" in 'VNC Terminal Server' if the remote
username is different from the yours on this machine. On Windows
you *MUST* supply the remote username due to a deficiency in Plink.
This entry is passed to SSH; it could also be an SSH alias you have
created (in ~/.ssh/config).
If the remote SSH server is run on a non-standard port, e.g. 2222, use
something like one of these:
far-away.east:2222
fred@someplace.no:2222
(unlike SSVNC mode, the number is the SSH port, not the VNC display)
Zeroconf/Bonjour:
On Unix or Mac OS X, if the 'avahi-browse' or 'dns-sd' command is
available on the system and in your PATH, a 'Find' button is placed by
'VNC Host:Display'. Clicking on Find will try to find VNC Servers
on your Local Network that advertize via the Zeroconf protocol.
A menu of found hosts is presented for you to select from.
Profiles:
Use "Save" to save a profile (i.e. a host:display and its specific
settings) with a name. The "TS-" prefix will be suggested to help
you distinguish between Terminal Services and regular profiles.
To load in a saved Options profile, click on the "Load" button,
and choose which one you want.
To list your profiles from the command line use:
tsvnc -profiles (or -list)
To launch profile1 directly from the command-line, or to a server
use things like:
tsvnc profile1
tsvnc hostname
tsvnc user@hostname
Note that the 'Verify All Certs' setting is NOT saved in profiles.
Proxies/Gateways:
Proxy/Gateway is usually a gateway machine to log into via SSH that is
not the machine running the VNC terminal services. However, Web and
SOCKS proxies can also be used (see below).
For example if a company had a central login server: "ssh.company.com"
(accessible from the internet) and the internal server name was
"ts-server", one could put in
VNC Terminal Server: ts-server
Proxy/Gateway: ssh.company.com
It is OK if the hostname "ts-server" only resolves inside the firewall.
The 2nd host, ts-server in this example, MUST also be running an SSH
server and you must be able to log into it. You may need to supply
a 2nd password to it to login.
Use username@host (e.g. joe@ts-server or jsmith@ssh.company.com)
if the user name differs between machines.
NOTE: On Windows you MUST always supply the username@ because putty's
plink requires it.
NON-STANDARD SSH PORT: To use a non-standard ssh port (i.e. a port other
than 22) you need to use the Proxy/Gateways as well. E.g. something
like this for port 2222:
VNC Terminal Server: ts-server
Proxy/Gateway: jsmith@ssh.company.com:2222
On Unix/MacOSX the username@ is not needed if it is the same as on this
machine.
A Web or SOCKS proxy can also be used. Use this if you are inside a
firewall that prohibits direct connections to remote SSH servers.
In Terminal Services SSH mode, the "http://" prefix is required for
web proxies.
VNC Terminal Server: fred@someplace.no
Proxy/Gateway: http://myproxy.west:8080
or for SOCKS:
VNC Terminal Server: fred@someplace.no
Proxy/Gateway: socks://mysocks.west:1080
use socks5://... to force the SOCKS5 version. For a non-standard
port the above would be, e.g., fred@someplace.no:2222
One can also chain proxies and other things. See the section
"SSH Proxies/Gateways" in the Main SSVNC Help for full details.
Options:
Click on Options to get to dialog boxes to:
- Desktop Type (kde, gnome, failsafe, twm...)
- Desktop Size (Geometry WxH and pixel depth)
- X Server Type (Xvfb, Xdummy, Xvnc)
- Enable Printing (CUPS and/or SMB/Windows)
- Enable Sound (TBD, ESD partially working)
- File Transfer (Ultra or TightVNC filexfer)
- View Only (View only client)
- Change VNC Viewer (Realvnc, ultra, etc...)
- X11 viewer MacOSX (use bundled X11 vncviewer)
- Delete Profile... (Delete a saved profile)
- Advanced Options:
- VNC Shared (optional traditional VNC sharing)
- Multiple Sessions (more than 1 session per server)
- X Login Greeter (Connect to Login/Greeter Display)
- Other VNC Server (redirect to 3rd party VNC Server)
- Use unixpw (optional x11vnc login mode)
- Client 8bit Color (VNC Viewer requests low color mode)
- Client-Side Caching (experimental x11vnc speedup)
- X11VNC Options (set any extra x11vnc options)
- Extra Sleep (delay a bit before starting viewer)
- SSH Local Protections (a bit of safety on local side)
- SSH KnownHosts file (to avoid SSH 'localhost' collisions)
- SSVNC Mode (Return to full SSVNC mode)
- Unix ssvncviewer (set options for supplied Unix viewer)
Requirements:
When running this application on Unix/MacOSX the ssh(1) program must
be installed locally. On Windows a plink/putty binary is included.
On the remote VNC Terminal Services host, x11vnc must be installed
(0.9.3 or higher), and at least one virtual X server: Xvfb, Xdummy,
or Xvnc must be available. Xvfb is the most often used one. All of
these programs must be available in $PATH on the remote server when
logged in via SSH.
The VNC terminal services administrator can make "x11vnc" be a wrapper
script that sets everything up correctly and then runs the real x11vnc.
Real X servers:
As a *BONUS*, if on the remote host, say a workstation, you have a
regular X session running on the physical hardware that you are
ALREADY logged into you can access to that display as well (x11vnc
will find it).
So this tool can be used as a simple way to launch x11vnc to find
your real X display on your workstation and connect to it.
The Printing and Sound redirection won't work for this mode however.
You will need to use the full SSVNC application to attempt that.
If you (mistakenly) have not logged into an X session on the real
X server on the workstation, a VIRTUAL (Xvfb, etc.) server will be
created for you (that may or may not be what you want).
The X Login Advanced setting can be used to connect to a X Display
Manger Greeter login panel (no one is logged in yet). This requires
sudo(1) privileges on the remote machine.
More Info:
See these links for more information:
http://www.karlrunge.com/x11vnc/#tunnelling
============================================================================
Terminal Services VNC Options Help:
Options: Click on a checkbox to enable a feature and bring up its Dialog.
Deselecting a checkbox will disable the feature (but settings from the
Dialog are remembered). Click on it again to re-enable.
Desktop Type:
The default type of remote Desktop type is the "kde" (The K Desktop
Environment) You can choose a different type: gnome, failsafe,
twm, etc.
This setting will ONLY be used if the desktop needs to be created.
If an existing session of yours is found it will be used instead
(log out of that session if you want to create a new Desktop type
or see the Multiple Sessions option under Advanced).
Desktop Size:
The default size of remote Desktop type is the "1280x1024" with a
Color depth of 16 bits per pixel (BPP). Choose one of the standard
WxH values or enter a custom one (TBD).
This setting will ONLY be used if the desktop needs to be created.
If an existing session of yours is found it will be used instead
(log out of that session if you want to create a new Desktop size
or see the Multiple Sessions option under Advanced).
Some X servers, Xdummy or a real X server, will allow dynamic screen
size changing after the session has started via a GUI configuration
tool (or xrandr(1) from the command line).
X Server Type:
The default type of remote X session is the "Xvfb" (X virtual frame
buffer) X server. It is available on most systems. To choose a
different type, select "Xdummy", "Xvnc", "Xvnc.redirect".
Xdummy is part of the x11vnc project and is a virtual X server with
some nice features, but it Linux only and requires root permission
to run. One user put 'ALL ALL = NOPASSWD: /usr/local/bin/Xdummy*'
in his sudo(1) configuration (via visudo).
For Xvnc that server is started up, and x11vnc polls it in its
normal way. Use Xvnc.redirect if you want x11vnc to find and/or
create the Xvnc session, but after that merely transfer packets back
and forth between VNC viewer and Xvnc (I.e. x11vnc does no polling
or VNC protocol).
Enable Printing:
This sets up a SSH port redirection for you from your remote session
to your local print server. The CUPS mechanism is used. The local
print server can also be SMB/Windows.
Enable Sound:
Not completely implemented yet. A partially working ESD method
is provided. It may change over to http://nas.sourceforge.net in
the future. As with printing, it uses a SSH port redirection to a
server running locally.
File Transfer:
x11vnc supports both the UltraVNC and TightVNC file transfer
extensions. On Windows both viewers support their file transfer
protocol. On Unix only the SSVNC VNC Viewer has filexfer support;
it supports the UltraVNC flavor via a Java helper program.
Choose the one you want based on VNC viewer you will use.
The defaults for the SSVNC viewer package are TightVNC on Windows
and UltraVNC on Unix.
View Only:
Start the VNC Viewer in View-Only mode (it may be switched to full
access later in the session).
Change VNC Viewer:
If you do not like the VNC Viewer bundled in the package, you can
indicate another one here.
X11 viewer MacOSX:
On MacOSX try to use the bundled X11 vncviewer instead of the
Chicken of the VNC viewer; the Xquartz X server must be installed
(it is by default on 10.5.x) and the DISPLAY variable must be set
(see Tip 15 of SSVNC Help to do this manually.)
Advanced Options:
VNC Shared:
Normal use of this program, 'tsvnc', *ALREADY* allows simultaneous
shared access of the remote desktop: You simply log in as many
times from as many different locations with 'tsvnc' as you like.
Select this option for the traditional VNC server shared mode of
operation using a single x11vnc server. SSH access is still required.
Multiple Sessions:
To enable one user to have more than one Terminal Services Desktop
X session on a single machine, this option lets you create Tags for
multiple ones (e.g. KDE_BIG, TWM_800x600)
X Login Greeter:
If you have root (sudo(1)) permission on the remote machine,
you can have x11vnc try to connect to X displays that have nobody
logged in yet. This is most likely the login greeter running on
the Physical console. sudo(1) is used to run x11vnc with FD_XDM=1.
An initial ssh running 'sudo id' is performed to try to 'prime'
sudo so the 2nd one that starts x11vnc does not need a password.
Note that if someone is already logged into the console of the XDM
display you will see their X session.
Other VNC Server:
The x11vnc program running on the remote machine can be instructed to
immediately redirect to some other (3rd party, e.g. Xvnc or vnc.so)
VNC server.
Use unixpw:
This enables the x11vnc unixpw mode. A Login: and Password: dialog
will be presented in the VNC Viewer for the user to provide any Unix
username and password whose session he wants to connect to.
This mode is useful if a shared terminal services user (e.g. 'tsuser')
is used for the SSH login part (say via the SSH authorized_keys
mechanism and all users share the same private SSH key for 'tsuser').
In normal usage the per-user SSH login should be the simplest and
sufficient, in which case the unixpw option should NOT be selected.
Client 8bit Color:
Have the VNC Viewer request low color mode (8 bits per pixel) for
slow links. This may be disabled or further tuned (e.g. 64 color
mode) in the viewer during the session.
Client-Side Caching:
x11vnc has an experiment Client-Side caching scheme "-ncache n"
that can give nice speedups. But there are some drawbacks
because the cache-region is visible and uses much RAM.
http://www.karlrunge.com/x11vnc/faq.html#faq-client-caching
X11VNC Options:
If you are familiar with x11vnc, you can specify any of its features
that you would like enabled.
SSVNC Mode:
Clicking on this button will return you to the full SSVNC Mode.
Unix ssvncviewer:
Clicking on this button will popup a menu for setting options
of the Unix (and Mac OS X) provided SSVNC vncviewer.
~/.ssvncrc file:
You can put global options in your ~/.ssvncrc file (ssvnc_rc on
Windows). Currently they are:
Put "mode=tsvnc" or "mode=sshvnc" in the ~/.ssvncrc file to have
the application start up in the given mode.
desktop_type=wmaker (e.g.) to switch the default Desktop Type.
desktop_size=1280x1024 (e.g.) to switch the default Desktop Size.
desktop_depth=24 (e.g.) to switch the default Desktop Color Depth.
xserver_type=Xdummy (e.g.) to switch the default X Server Type.
(The above 4 settings apply only to the Terminal Services Mode.)
noenc=1 (same as the -noenc option for a 'No Encryption' option)
noenc=0 (do not show the 'No Encryption' option)
font_default=tk-font-name (sets the font for menus and buttons)
font_fixed=tk-font-name (sets the font for help text)
============================================================================
Terminal Services Use unixpw Dialog:
This enables the x11vnc unixpw mode. A Login: and Password: dialog
will be presented in the VNC Viewer for the user to provide any Unix
username and password whose session he wants to connect to. So this
may require typing in the password a 2nd time after the one for SSH.
This mode is useful if a shared terminal services user (e.g. 'tsuser')
is used for the SSH login part (say via the SSH authorized_keys
mechanism and all users share the same private SSH key for 'tsuser').
Note, However that the default usage of a per-user SSH login should
be the simplest and also sufficient for most situations, in which
case this "Use unixpw" option should NOT be selected.
============================================================================
Terminal Services VNC Shared Dialog:
Normal use of this program, 'tsvnc', *ALREADY* allows simultaneous
shared access of the remote desktop: You simply log in as many
times from as many different locations with 'tsvnc' as you like.
However, doing it that way starts up a new x11vnc for each connection.
In some circumstances you may want a single x11vnc running but allow
multiple VNC viewers to access it simultaneously.
This option (VNC Shared) enables that rarer usage case by passing
'-shared' to the remote x11vnc command.
With this option enabled, the new shared connections must
still connect to the Terminal Server via SSH for encryption and
authentication. They must also do the normal SSH port redirection
to access the x11vnc port (usually 5900, but look for the PORT=
output for the actual value).
They could use SSVNC for that, or do it manually in terminal
windows, more information:
http://www.karlrunge.com/x11vnc/#tunnelling
============================================================================
Terminal Services Multiple Sessions Dialog:
Normally in Terminal Services mode (tsvnc) your user account (the
one you SSH in as) can only have a single Terminal Services X session
running at a time on one server machine.
This is simply because x11vnc chooses the first Desktop (X session)
of yours that it can find. It will never create a 2nd X session
because it keeps finding the 1st one.
To have Multiple Sessions for one username on a single machine,
choose a unique Session "Tag", that will be associated with the X
session and x11vnc will only choose the one that has this Tag.
For this to work ALL of your sessions on the server machine must
have a different tag (that is, if you have an existing session with
no tag, x11vnc might find a tagged one first instead of it).
The tag must be made of only letters, numbers, dash, or underscore.
Examples: KDE_SMALL, gnome-2, test1
============================================================================
Terminal Services X Login Dialog:
If you have root (sudo(1)) permission on the remote machine, you
can have x11vnc try to connect to a X display(s) that has No One
Logged In Yet. This is most likely the login greeter running on
the Physical console. sudo(1) is used to run x11vnc with FD_XDM=1.
This is different from tsvnc's regular Terminal Services mode where
usually a virtual (RAM only, e.g. Xvfb) X server used. With this option
it is the physical graphics hardware that will be connected to.
Note that if your user is ALREADY logged into the physical display,
you don't need to use this X Login option because x11vnc should find
it in its normal find-display procedure and not need sudo(1).
An initial ssh running 'sudo id' is performed to try to 'prime'
sudo so the 2nd one that runs x11vnc does not need a password.
This may not always succeed...
Note that if someone is already logged into the display console
via XDM (GDM, KDM etc.) you will see and control their X session.
Otherwise, you will get the Greeter X login screen where you can
log in via username and password. Your SSVNC 'Terminal Services'
Desktop Type, Size, Printing etc. settings will be ignored in this
case of course because XDM, GDM, or KDM is creating your X session,
not x11vnc.
Note that the GDM display manager has a setting KillInitClients in
gdm.conf that will kill x11vnc right after you log in, and so you would
have to repeat the whole process ('Connect' button) to attach to your
session. See http://www.karlrunge.com/x11vnc/faq.html#faq-display-manager
for more info.
============================================================================
Terminal Services Other VNC Server Dialog:
The x11vnc program running on the remote machine can be instructed to
immediately redirect to some other (3rd party, e.g. Xvnc or vnc.so)
VNC server.
It should be a little faster to have x11vnc forward the VNC protocol
rather than having it poll the corresponding X server for changes
in the way it normally does and translate to VNC.
This mode also enables a simple way to add SSL or find X display
support to a 3rd party VNC Server lacking these features.
In the entry box put the other vnc display, e.g. "localhost:0" or
"somehost:5".
The string "find" in the entry will have x11vnc try to find an X
display in its normal way, and then redirect to the corresponding VNC
server port. This assumes if the X display is, say, :2 (i.e. port
6002) then the VNC display is also :2 (i.e. port 5902). This mode is
the same as an "X Server Type" of "Xvnc.redirect" (and overrides it).
============================================================================
Terminal Services Client-Side Caching Dialog:
This enables the *experimental* x11vnc client-side caching mode.
It often gives nice speedups, but can sometimes lead to painting
errors or window "flashing". (you can repaint the screen by tapping
the Left Alt key 3 times in a row)
It is a very simple but hoggy method: uncompressed image pixmaps are
stored in the viewer in a large (20-100MB) display region beneath
the actual display screen. You may need also to adjust your VNC Viewer
to not show this region (the SSVNC Unix viewer does it automatically).
The scheme uses a lot of RAM, but at least it has the advantage that
it works with every VNC Viewer. Otherwise the VNC protocol would
need to be modified, changing both the server and the viewer.
Set the x11vnc "-ncache" parameter to an even integer between 2
and 20. This is the increase in area factor over the normal screen
for the caching region. So 10 means use 10 times the RAM to store
pixmaps. The default is 8.
More info: http://www.karlrunge.com/x11vnc/faq.html#faq-client-caching
============================================================================
Terminal Services x11vnc Options Dialog:
If you are an expert with x11vnc's endless options and tweaking
parameters feel free to specify any you want here in "Options".
Also, if you need to specify the path to the x11vnc program on the
remote side because it will not be in $PATH, put it in the "Full
Path" entry.
Port Redirs are additional SSH "-L port:host:port" or "-R port:host:port"
(forward or reverse, resp.) port redirections you want. In SSVNC mode,
see the detailed description under: Options -> Advanced -> Port Redirs.
Some potentially useful options:
-solid -scale -scale_cursor
-passwd -rfbauth -http
-xrandr -rotate -noxdamage
-xkb -skip_lockkeys -nomodtweak
-repeat -cursor -wmdt
-nowireframe -ncache_cr -speeds
More info: http://www.karlrunge.com/x11vnc/faq.html#faq-cmdline-opts
============================================================================
Terminal Services File Transfer Dialog:
x11vnc supports both the UltraVNC and TightVNC file transfer
extensions. On Windows both viewers support their file transfer
protocol. On Unix only the SSVNC VNC Viewer can do filexfer; it
supports the UltraVNC flavor via a Java helper program (and so
java(1) is required on the viewer-side).
Choose the one you want based on VNC viewer you will use.
The defaults for the SSVNC viewer package are TightVNC on
Windows and UltraVNC on Unix.
For more info see: http://www.karlrunge.com/x11vnc/faq.html#faq-filexfer
============================================================================
Terminal Services Sound Tunnelling Dialog:
Your remote Desktop will be started in an Enlightenment Sound Daemon
(ESD) environment (esddsp(1), which must be installed on the remote
machine), and a local ESD sound daemon (esd(1)) will be started to
play the sounds for you to hear.
In the entry box below you can choose the port that the local esd
will use to listen on. The default ESD port is 16001. You will
need to choose different values if you will have more than one esd
running locally.
The command run (with port replaced by your choice) will be:
esd -promiscuous -as 5 -port 16010 -tcp -bind 127.0.0.1
Note: Unfortunately not all applications work with ESD.
And esd's LD_PRELOAD is broken on 64+32bit Linux (x86_64).
And so this mode is not working well currently...
For more info see: http://www.karlrunge.com/x11vnc/faq.html#faq-sound
============================================================================
Terminal Services CUPS Dialog:
This method requires a working CUPS Desktop setup on the remote side
of the connection and working CUPS (or possibly Windows SMB or IPP)
printing on the local viewer-side of the connection.
For CUPS printing redirection to work properly, you MUST enable it for
the connection that *creates* your terminal services X session (i.e. the
first connection.) You cannot retroactively enable CUPS redirection
on an already existing terminal services X session. (See CUPS printing
for normal SSVNC mode for how you might do that.)
Enter the VNC Viewer side (i.e. where you are sitting) CUPS server
under "Local CUPS Server". Use "localhost:631" if there is one
on your viewer machine (normally the case if you set up a printer
on your unix or macosx system), or, e.g., "my-print-srv:631" for a
nearby CUPS print server. Note that 631 is the default CUPS port.
(On MacOSX it seems better to use "127.0.0.1" instead of "localhost".)
The SSVNC Terminal Services created remote Desktop session will have
the variables CUPS_SERVER and IPP_PORT set so all printing applications
will be redirected to your local CUPS server. So your locally available
printers should appear in the remote print dialogs.
Windows/SMB Printers: Under "Local SMB Print Server" you can set a
port redirection for a Windows (non-CUPS) SMB printer. If localhost:139
does not work, try the literal string "IP:139", or use the known value
of the IP address manually. 139 is the default SMB port; nowadays 445
might be a better possibility.
For Windows/SMB Printers if there is no local CUPS print server, it is
usually a very good idea to make the CUPS Server setting EMPTY (to avoid
desktop apps trying incessantly to reach the nonexistent CUPS server.)
On the remote side, in the Desktop session the variables $SMB_SERVER,
$SMB_HOST, and $SMB_PORT will be set for you to use.
Unfortunately, printing to Windows may only ve partially functional due
to the general lack PostScript support on Windows.
If you have print admin permission on the remote machine you can
configure CUPS to know about your Windows printer via lpadmin(8) or
a GUI tool. You give it the URI:
smb://localhost:port/printername
or possibly:
smb://localhost:port/computer/printername
"port" will be found in the $SMB_PORT. You also need to identify
the printer type. NOTE: You will leave "Local CUPS Server" blank in
this case. The smbspool(1) command should also work as well, at least
for PostScript printers.
A similar thing can be done with CUPS printers if you are having problems
with the above default mechanism. Use
http://localhost:port/printers/printername
For more info see: http://www.karlrunge.com/x11vnc/faq.html#faq-cups
============================================================================
Unix SSVNC viewer Options Help:
These Unix SSVNC VNC Viewer Options apply only on Unix or Mac OS X
when using the viewer (ssvncviewer) supplied by this SSVNC package.
Brief descriptions:
Multiple LISTEN Connections:
Allow multiple VNC servers to reverse connect at the same time
and so display each of their desktops on your screen at the
same time.
Listen Once:
Try to have the VNC Viewer exit after the first listening
connection. (It may not always be detected; use Ctrl-C to exit)
Listen Accept Popup Dialog:
In -listen (reverse connection listening) mode when a reverse
VNC connection comes in show a popup asking whether to Accept
or Reject the connection. (-acceptpopup vncviewer option.)
Accept Popup UltraVNC Single Click:
As in 'Listen Accept Popup Dialog', except assume the remote
VNC server is UltraVNC Single Click and force the execution of
the protocol to retrieve the extra remote-side info (Windows
User, ComputerName, etc) which is then also displayed in the
Popup window. (-acceptpopupsc vncviewer option.)
Use X11 Cursor:
When drawing the mouse cursor shape locally, use an X11 cursor
instead of drawing it directly into the framebuffer. This
can sometimes give better response, and avoid problems under
'Scaling'.
Disable Bell:
Disable beeps coming from remote side.
Use Raw Local:
Use the VNC Raw encoding for 'localhost' connections (instead
of assuming there is a local tunnel, SSL or SSH, going to the
remote machine.
Avoid Using Terminal:
By default the Unix ssvncviewer will prompt for usernames,
passwords, etc. in the terminal it is running inside of.
Set this option to use windows for messages and prompting as
much as possible. Messages will also go to the terminal, but
all prompts will be done via popup window.
Note that stunnel(1) may prompt for a passphrase to unlock a
private SSL key. This is fairly rare because it is usually
for Client-side SSL authentication. stunnel will prompt from
the terminal; there seems to be no way around this.
Also, note that ssh(1) may prompt for an ssh key passphrase
or Unix password. This can be avoided in a number of ways,
the simplest one is to use ssh-agent(1) and ssh-add(1).
However ssh(1) may also prompt you to accept a new public key
for a host or warn you if the key has changed, etc.
Use Popup Fix:
Enable a fix that warps the popup (F8) to the mouse pointer.
Use XGrabServer (for fullscreen):
On Unix only, use the XGrabServer workaround for older window
managers. Sometimes also needed on recent (2008) GNOME. This
workaround can make going into/out-of Fullscreen work better.
Cursor Alphablending:
Use the x11vnc alpha hack for translucent cursors (requires Unix,
32bpp and same endianness)
TurboVNC:
If available on your platform, use a ssvncviewer compiled with
TurboVNC support. This is based on the VirtualGL project:
http://www.sourceforge.net/projects/virtualgl You will need
to install the VirtualGL's TurboJPEG library too.
Currently (May/2009) only Linux.i686, Linux.x86_64, and
Darwin.i386 have vncviewer.turbovnc binaries shipped in the
ssvnc bundles. See the build instructions for how you might
compile your own.
Disable Pipelined Updates:
Disable the TurboVNC-like pipelined updates mode. Pipelined
updates is the default even when not TurboVNC enabled. They
ask for the next screen update before the current one has
finished downloading, and so this might reduce the slowdown
due to high latency or low bandwidth by 2X or so. Disable
them if they cause problems with the remote VNC Server or
use too much bandwidth.
Send CLIPBOARD not PRIMARY:
When sending locally selected text to the VNC server side,
send the CLIPBOARD selection instead of the PRIMARY selection.
Send Selection Every time:
Send selected text to the VNC server side every time the mouse
focus enters the main VNC Viewer window instead only when it
appears to have changed since the last send.
Scaling:
Use viewer-side (i.e. local) scaling of the VNC screen. Supply
a fraction, e.g. 0.75 or 3/4, or a WxH geometry, e.g. 1280x1024,
or the string 'fit' to fill the current screen. Use 'auto'
to scale the desktop to match the viewer window size.
If you observe mouse trail painting errors try using X11 Cursor.
Note that since the local scaling is done in software it can
be slow. Since ZRLE is better than Tight in this regard, when
scaling is detected, the encoding will be switched to ZRLE.
Use the Popup to go back to Tight if you want to, or set the
env. var. SSVNC_PRESERVE_ENCODING=1 to disable the switch.
For additional speedups under local scaling: try having a solid
desktop background on the remote side (either manually or using
'x11vnc -solid ...'); and also consider using client side caching
'x11vnc -ncache 10 ...' if the remote server is x11vnc.
Escape Keys:
Enable 'Escape Keys', a set of modifier keys that, if all are
pressed down, enable local Hot Key actions. Set to 'default'
to use the default (Alt_L,Super_L on unix, Control_L,Meta_L
on macosx) or set to a list of modifier keys.
Y Crop:
This is for x11vnc's -ncache client side caching scheme with our
Unix TightVNC viewer. Sets the Y value to "crop" the viewer
size at (below the cut is the pixel cache region you do not
want to see). If the screen is tall (H > 2*W) ycropping will
be autodetected, or you can set to -1 to force autodection.
Otherwise, set it to the desired Y value. You can also set
the scrollbar width (very thin by default) by appending ",sb=N"
(or use ",sb=N" by itself to just set the scrollbar width).
ScrollBar Width:
This is for x11vnc's -ncache client side caching scheme with our
Unix TightVNC viewer. For Y-Crop mode, set the size of the
scrollbars (often one want it to be very narrow, e.g. 2 pixels
to be less distracting.
RFB Version:
Set the numerical version of RFB (VNC) protocol to pretend to
be, 3.x. Usually only needed with UltraVNC servers.
Encodings:
List encodings in preferred order, for example
'copyrect zrle tight' The list of encodings is:
copyrect tight zrle zywrle hextile zlib corre rre raw
Extra Options:
String of extra Unix ssvncviewer command line options. I.e. for
ones like -16bpp that cannot be set inside this SSVNC GUI. For a
list click Help then 'SSVNC vncviewer -help Output'.
These are environment variables one may set to affect the options
of the SSVNC vncviewer:
VNCVIEWER_ALPHABLEND (-alpha, see Cursor Alphablending above)
VNCVIEWER_POPUP_FIX (-popupfix, warp popup to mouse location)
VNCVIEWER_GRAB_SERVER (-graball, see Use XGrabServer above)
VNCVIEWER_YCROP (-ycrop, see Y Crop above)
VNCVIEWER_SBWIDTH (-sbwidth, see ScrollBar Width above)
VNCVIEWER_RFBVERSION (-rfbversion, e.g. 3.6)
VNCVIEWER_ENCODINGS (-encodings, e.g. "copyrect zrle hextile")
VNCVIEWER_NOBELL (-nobell)
VNCVIEWER_X11CURSOR (-x11cursor, see Use X11 Cursor above)
VNCVIEWER_RAWLOCAL (-rawlocal, see Use Raw Local above)
VNCVIEWER_NOTTY (-notty, see Avoid Using Terminal above)
VNCVIEWER_ESCAPE (-escape, see Escape Keys above)
VNCVIEWER_ULTRADSM (-ultradsm)
VNCVIEWER_SEND_CLIPBOARD (-sendclipboard)
VNCVIEWER_SEND_ALWAYS (-sendalways)
VNCVIEWER_RECV_TEXT (-recvtext clipboard/primary/both)
VNCVIEWER_NO_CUTBUFFER (do not send CUTBUFFER0 as fallback)
VNCVIEWER_NO_PIPELINE_UPDATES (-nopipeline)
VNCVIEWERCMD (unix viewer command, default vncviewer)
VNCVIEWERCMD_OVERRIDE (force override of VNCVIEWERCMD)
VNCVIEWERCMD_EXTRA_OPTS (extra options to pass to VNCVIEWERCMD)
VNCVIEWER_LISTEN_LOCALHOST (force ssvncviewer to -listen on localhost)
VNCVIEWER_NO_SEC_TYPE_TIGHT(force ssvncviewer to skip rfbSecTypeTight)
SSVNC_MULTIPLE_LISTEN (-multilisten, see Multiple LISTEN above)
SSVNC_ACCEPT_POPUP (-acceptpopup, see Accept Popup Dialog)
SSVNC_ACCEPT_POPUP_SC (-acceptpopupsc, see Accept Popup Dialog)
SSVNC_TURBOVNC (see TurboVNC above)
SSVNC_UNIXPW (-unixpw)
SSVNC_UNIXPW_NOESC (do not send escape in -unixpw mode)
SSVNC_SCALE (-scale, see Scaling above)
SSVNC_NOSOLID (do not do solid region speedup in
scaling mode.)
SSVNC_PRESERVE_ENCODING (do not switch to ZRLE when scaling)
SSVNC_FINISH_SLEEP (on unix/macosx sleep this many seconds
before exiting the terminal, default 5)
Misc (special usage or debugging or ss_vncviewer settings):
SSVNC_MESG_DELAY (sleep this many millisec between messages)
SSVNC_EXTRA_SLEEP (same as Sleep: window)
SSVNC_NO_ULTRA_DSM (disable ultravnc dsm encryption)
SSVNC_ULTRA_FTP_JAR (file location of ultraftp.jar jar file)
SSVNC_KNOWN_HOSTS_FILE (file for per-connection ssh known hosts)
SSVNC_SCALE_STATS
SSVNC_DEBUG_RELEASE
SSVNC_DEBUG_ESCAPE_KEYS
SSVNC_NO_MAYBE_SYNC
SSVNC_MAX_LISTEN (number of time to listen for reverse conn.)
SSVNC_LISTEN_ONCE (listen for reverse conn. only once)
SSVNC_EXIT_DEBUG
SSVNC_DEBUG_CHAT
SSVNC_NO_MESSAGE_POPUP
SSVNC_SET_SECURITY_TYPE
SSVNC_PREDIGESTED_HANDSHAKE
SSVNC_SKIP_RFB_PROTOCOL_VERSION
SSVNC_DEBUG_SEC_TYPES
SSVNC_DEBUG_MSLOGON
SSVNC_DEBUG_RECTS
SSVNC_DEBUG_CHAT
SSVNC_DELAY_SYNC
SSVNC_DEBUG_SELECTION
SSVNC_REPEATER
SSVNC_VENCRYPT_DEBUG
SSVNC_STUNNEL_DEBUG
SSVNC_TEST_SEC_TYPE
SSVNC_LIM_ACCEPT_PRELOAD
SSVNC_SOCKS5
============================================================================
Unix Change VNC Viewer Dialog:
To use your own VNC Viewer (i.e. one installed by you, not included in this
package), e.g. UltraVNC or RealVNC, type in the program name, or browse for
the full path to it. You can put command line arguments after the program.
Note that due to incompatibilities with respect to command line options
there may be issues, especially if many command line options are supplied.
You can specify your own command line options below if you like (and try to
avoid setting any others in this GUI under "Options").
If the path to the program name has spaces it in, surround it with double quotes:
"C:\Program Files\My Vnc Viewer\VNCVIEWER.EXE"
Make sure the very first character is a quote. You should quote the command
even if it is only the command line arguments that need extra protection:
"wine" -- "/home/fred/Program Flies/UltraVNC-1.0.2.exe" /64colors
Since the command line options differ between them greatly, if you know it
is of the RealVNC 4.x flavor, indicate on the check box. Otherwise we guess.
To have SSVNC act as a general STUNNEL redirector (no VNC) set the viewer to be
"xmessage OK" or "xmessage " or "sleep n" or "sleep n " (or "NOTEPAD"
on Windows). The default listen port is 5930. The destination is set in "VNC
Host:Display" (for a remote port less than 200 use the negative of the port value).
============================================================================
CUPS Dialog:
CUPS Printing requires SSH be used to set up the CUPS Print service TCP
port redirection. This will be either of the "Use SSH" or "SSH+SSL" modes.
NOTE: For pure SSL tunnelling it currently will not work.
This method requires working CUPS software setups on BOTH the remote
and local sides of the connection.
If the remote VNC server is Windows you probably cannot SSH into it
anyway... If you can, you will still need to set up a special printer
TCP port redirection on your own. Perhaps adding and configuring a
"Unix Printer" under Windows (like Method #2 below) will work.
If the local machine (SSVNC side) is Windows, see the bottom of this
help for redirecting to SMB printers.
If the remote VNC server is Mac OS X this method may or may not work.
Sometimes applications need to be restarted to get them to notice the
new printers. Adding and configuring a special "Unix Printer",
(Method #2) below, might yield more reliable results at the cost of
additional setup and permissions.
For Unix/Linux remote VNC servers, applications may also need to be
restarted to notice the new printers. The only case known to work
well is the one where the remote side has no CUPS printers configured.
As mentioned above, see Method #2 for another method.
*************************************************************************
*** Directions:
You choose your own remote CUPS redir port below under "Use Remote
CUPS Port". 6631 is our default and is used in the examples below.
Use it or some random value greater than 1024. Note that the standard
CUPS server port is 631.
The port you choose must be unused on the VNC server machine (it is NOT
checked for you). Print requests connecting to it are redirected to
your local VNC viewer-side CUPS server through the SSH tunnel.
(Note: root SSH login permission is needed for ports less than 1024,
e.g. 631; this is not recommended, use something around 6631 instead).
Then enter the VNC Viewer side (i.e. where you are sitting) CUPS server
into "Local CUPS Server". A good choice is the default "localhost:631"
if there is a cups server on your viewer machine (this is usually the case
if you have set up a printer). Otherwise enter, e.g., "my-print-srv:631"
for your nearby (viewer-side) CUPS print server.
The "Manage 'ServerName' in the $HOME/.cups/client.conf file for me"
setting below is enabled by default. It should handle most situations.
What it does is modify the .cups/client.conf file on the VNC server-side
to redirect the print requests while the SSVNC viewer is connected. When
SSVNC disconnects .cups/client.conf is restored to its previous setting.
If, for some reason, the SSVNC CUPS script fails to restore this file
after SSVNC disconnects, run this command on the remote machine:
cp $HOME/.cups/client.conf.back $HOME/.cups/client.conf
to regain your initial printing configuration.
You can also use CUPS on the VNC server-side to redirect to Windows
(SMB) printers. See the additional info for Windows Printing at the
bottom of this help.
In case the default method (automatic .cups/client.conf modification)
fails, we describe below all of the possible methods that can be tried.
As noted above, you may need to restart applications for them to notice
the new printers or for them to revert to the original printers. If this
is not acceptable, consider Method #2 below if you have the permission
and ability to alter the print queues for this.
*************************************************************************
*** Method #1: Manually create or edit the file $HOME/.cups/client.conf
on the VNC server side by putting in something like this in it:
ServerName localhost:6631
based on the port you set in this dialog's entry box.
After the remote VNC Connection is finished, to go back to the non-SSH
tunnelled CUPS server and either remove the client.conf file or comment
out the ServerName line. This restores the normal CUPS server for
you on the remote VNC server machine.
Select "Manage 'ServerName' in the $HOME/.cups/client.conf file for me"
to do this editing of the VNC server-side CUPS config file for you
automatically. NOTE: It is now on by default (deselect it if you want
to manage the file manually; e.g. you print through the tunnel only very
rarely, or often print locally when the tunnel is up, etc.)
Select "Pass -env FD_CUPS= to x11vnc command line" if you are
starting x11vnc as the Remote SSH Command, and x11vnc is running in
-create mode (i.e. FINDCREATEDISPLAY). That way, when your X session
is created IPP_PORT will be set correctly for the entire session.
This is the mode used for 'Terminal Services' printing.
NOTE: You probably would never select both of the above two options
at the same time, since they conflict with each other to some degree.
*************************************************************************
*** Method #2: If you have admin permission on the VNC Server machine
you can likely "Add a Printer" via a GUI dialog, a Wizard, CUPS Web
interface (i.e. http://localhost:631/), lpadmin(8), etc.
You will need to tell the dialog that the network printer located
is at, e.g., localhost:6631, and anything else needed to identify
the printer (type, model, etc). NOTE: sometimes it is best to set
the model/type as "Generic / Postscript Printer" to avoid problems
with garbage being printed out.
For the URI to use, we have successfully used ones like this with CUPS:
http://localhost:6631/printers/Deskjet-3840
ipp://localhost:6631/printers/Deskjet-3840
for an HP Deskjet-3840 printer. See the CUPS documentation for more
about the URI syntax and pathname.
This mode makes the client.conf ServerName parameter unnecessary
(BE SURE TO DISABLE the "Manage 'ServerName' ... for me" option.)
*************************************************************************
*** Method #3: Restarting individual applications with the IPP_PORT
set will enable redirected printing for them, e.g.:
env IPP_PORT=6631 firefox
If you can only get this method to work, an extreme application would
be to run the whole desktop, e.g. "env IPP_PORT=6631 gnome-session", but
then you would need some sort of TCP redirector (ssh -L comes to mind),
to direct it to 631 when not connected remotely.
*************************************************************************
*** Windows/SMB Printers: Under "Local SMB Print Server" you can set
a port redirection for a Windows (non-CUPS) SMB printer. E.g. port
6632 -> localhost:139.
If localhost:139 does not work, try the literal string "IP:139", or
insert the actual IP address manually. NOTE: Nowadays on Windows port
445 might be a better choice.
For Windows printers, if there is no local CUPS print server, set the
'Local CUPS Server' and 'Use Remote CUPS Port' to be EMPTY (to avoid
desktop apps trying incessantly to reach the nonexistent CUPS server.)
You must enable Sharing for your local Windows Printer. Use Windows
Printer configuration dialogs to do this.
Next, you need to have sudo or print admin permission so that you can
configure the *remote* CUPS to know about this Windows printer via
lpadmin(8) or GUI Printer Configuration dialog, etc (Method #2 above).
You basically give it the URI:
smb://localhost:6632/printername
For example, we have had success with GNOME CUPS printing configuration
using:
smb://localhost:6632/HPOffice
smb://localhost:6632/COMPUTERNAME/HPOffice
where "HPOffice" was the name Windows shares the printer as.
Also with this SMB port redir mode, as a last resort you can often print
using the smbspool(8) program like this:
smbspool smb://localhost:6632/printer job user title 1 "" myfile.ps
You could put this in a script. For this URI, it appears only the number
of copies ("1" above) and the file itself are important.
If on the local (SSVNC viewer) side there is some nearby CUPS print server
that knows about your Windows printer, you might have better luck with
that instead of using SMB. Set 'Local CUPS Server' to it.
For more info see: http://www.karlrunge.com/x11vnc/faq.html#faq-cups
============================================================================
ESD Audio Tunnelling Dialog:
Sound tunnelling to a sound daemon requires SSH be used to set up the
service port redirection. This will be either of the "Use SSH" or
"SSH+SSL" modes. NOTE: For pure SSL tunnelling it currently will not work.
This method requires working Sound daemon (e.g. ESD or ARTSD) software
setups on BOTH the remote and local sides of the connection.
Often this means you want to run your ENTIRE remote desktop with ALL
applications instructed to use the sound daemon's network port. E.g.
esddsp -s localhost:16001 startkde
esddsp -s localhost:16001 gnome-session
and similarly for artsdsp, etc. You put this in your ~/.xession,
or other startup file. This is non standard. If you do not want to
do this you still can direct *individual* sound applications through
the tunnel, for example "esddsp -s localhost:16001 soundapp", where
"soundapp" is some application that makes noise (say xmms or mpg123).
Select "Pass -env FD_ESD= to x11vnc command line." if you are
starting x11vnc as the Remote SSH Command, and x11vnc is running in
-create mode (i.e. FINDCREATEDISPLAY). That way, your X session is
started via "esddsp -s ... " and the ESD variables will be
set correctly for the entire session. (This mode make most sense for
a virtual, e.g. Xvfb or Xdummy session, not one a physical display).
Also, usually the remote Sound daemon must be killed BEFORE the SSH port
redir is established (because it is listening on the port we want to use
for the SSH redir), and, presumably, restarted when the VNC connection
finished.
One may also want to start and kill a local sound daemon that will
play the sound received over the network on the local machine.
You can indicate the remote and local Sound daemon commands below and
how they should be killed and/or restart. Some examples:
esd -promiscuous -as 5 -port 16001 -tcp -bind 127.0.0.1
artsd -n -p 7265 -F 10 -S 4096 -n -s 5 -m artsmessage -l 3 -f
or you can leave some or all blank and kill/start them manually.
For convenience, a Windows port of ESD is provided in the util/esound
directory, and so this might work for a Local command:
esound\esd -promiscuous -as 5 -port 16001 -tcp -bind 127.0.0.1
NOTE: If you indicate "Remote Sound daemon: Kill at start." below,
then THERE WILL BE TWO SSH'S: THE FIRST ONE TO KILL THE DAEMON.
So you may need to supply TWO SSH PASSWORDS, unless you are using
something like ssh-agent(1), the Putty PW setting, etc.
You will also need to supply the remote and local sound ports for
the SSH redirs. For esd the default port is 16001, but you can choose
another one if you prefer.
For "Local Sound Port" you can also supply "host:port" instead of just
a numerical port to specify non-localhost connections, e.g. to another
nearby machine.
For more info see: http://www.karlrunge.com/x11vnc/faq.html#faq-sound
============================================================================
SMB Mounting Dialog:
Windows/Samba Filesystem mounting requires SSH be used to set up the SMB
service port redirection. This will be either of the "Use SSH" or
"SSH+SSL" modes. NOTE: For pure SSL tunnelling it currently will not work.
This method requires a working Samba software setup on the remote
side of the connection (VNC server) and existing Samba or Windows file
server(s) on the local side (VNC viewer).
The smbmount(8) program MUST be installed on the remote side. This
evidently limits the mounting to Linux systems. Let us know of similar
utilities on other Unixes. Mounting onto remote Windows machines is
currently not supported (our SSH mode with services setup only works
to Unix). On Debian and Ubuntu the smbmount program is currently in
the package named 'smbfs'.
Depending on how smbmount is configured you may be able to run it
as a regular user, or it may require running under su(1) or sudo(8)
(root password or user password required, respectively). You select
which one you want via the checkbuttons below.
In addition to a possible su(1) or sudo(8) password, you may ALSO
need to supply passwords to mount each SMB share. This is an SMB passwd.
If it has no password just hit enter after the "Password:" prompt.
The passwords are supplied when the 1st SSH connection starts up;
be prepared to respond to them.
NOTE: USE OF SMB TUNNELLING MODE WILL REQUIRE TWO SSH'S, AND SO YOU
MAY NEED TO SUPPLY TWO LOGIN PASSWORDS UNLESS YOU ARE USING SOMETHING
LIKE ssh-agent(1) or the Putty PW setting.
To indicate the Windows/Samba shares to mount enter them one per line
in one of the forms:
//machine1/share ~/Desktop/my-mount1
//machine2/fubar /var/tmp/my-foobar2 192.168.100.53:3456
1139 //machine3/baz /var/tmp/baz [...]
The first part is the standard SMB host and share name //hostname/dir
(note this share is on the local viewer-side not on the remote end).
A leading '#' will cause the entire line to be skipped.
The second part, e.g. /var/tmp/my-foobar2, is the directory to mount
the share on the remote (VNC Server) side. You must be able to
write to this directory. It will be created if it does not exist.
A leading character ~ will be expanded to $HOME. So will the string
%HOME. The string %USER will get expanded to the remote username.
An optional part like 192.168.100.53:3456 is used to specify the real
hostname or IP address, and possible non-standard port, on the local
side if for some reason the //hostname is not sufficient.
An optional leading numerical value, 1139 in the above example, indicates
which port to use on the Remote side to SSH redirect to the local side.
Otherwise a random one is tried (a unique one is needed for each SMB
server:port combination). A fixed one is preferred: choose a free
remote port.
The standard SMB service ports (local side) are 445 and 139. 139 is
used by this application.
Sometimes "localhost" will not work on Windows machines for a share
hostname, and you will have to specify a different network interface
(e.g. the machine's IP address). If you use the literal string "IP"
it will be attempted to replace it with the numerical IP address, e.g.:
//machine1/share ~/Desktop/my-mount1 IP
VERY IMPORTANT: Before terminating the VNC Connection, make sure no
applications are using any of the SMB shares (or shells are cd-ed
into the share). This way the shares will be automatically unmounted.
Otherwise you will need to log in again, stop processes from using
the share, become root and umount the shares manually ("smbumount
/path/to/share", etc.)
For more info see: http://www.karlrunge.com/x11vnc/faq.html#faq-smb-shares
============================================================================
Additional Port Redirections Dialog:
Specify any additional SSH port redirections you desire for the
connection. Put as many as you want separated by spaces. These only
apply to SSH and SSH+SSL connections, they do not apply to Pure SSL
connections.
-L port1:host:port2 will listen on port1 on the local machine (where
you are sitting) and redirect them to port2 on
"host". "host" is relative to the remote side
(VNC Server). Use "localhost" for the remote
machine itself.
-R port1:host:port2 will listen on port1 on the remote machine
(where the VNC server is running) and redirect
them to port2 on "host". "host" is relative
to the local side (where you are sitting).
Use "localhost" for this machine.
Perhaps you want a redir to a web server inside an intranet:
-L 8001:web-int:80
Or to redir a remote port to your local SSH daemon:
-R 5022:localhost:22
etc. There are many interesting possibilities.
Sometimes, especially for Windows Shares, you cannot do a -R redir to
localhost, but need to supply the IP address of the network interface
(e.g. by default the Shares do not listen on localhost:139). As a
convenience you can do something like -R 1139:IP:139 (for any port
numbers) and the IP will be attempted to be expanded. If this fails
for some reason you will have to use the actual numerical IP address.
============================================================================
Port Knocking Dialog:
Description:
Port Knocking is where a network connection to a service is not provided
to just any client, but rather only to those that immediately prior to
connecting send a more or less secret pattern of connections to other
ports on the firewall.
Somewhat like "knocking" on the door with the correct sequence before it
being opened (but not necessarily letting you in yet). It is also possible
to have a single encrypted packet (e.g. UDP) payload communicate with the
firewall instead of knocking on a sequence of ports.
Only after the correct sequence of ports is observed by the firewall does
it allow the IP address of the client to attempt to connect to the service.
So, for example, instead of allowing any host on the internet to connect
to your SSH service and then try to login with a username and password, the
client first must "tickle" your firewall with the correct sequence of ports.
Only then will it be allowed to connect to your SSH service at all.
This does not replace the authentication and security of SSH, it merely
puts another layer of protection around it. E.g., suppose an exploit for
SSH was discovered, you would most likely have more time to fix/patch
the problem than if any client could directly connect to your SSH server.
For more information http://www.portknocking.org/ and
http://www.linuxjournal.com/article/6811
Tip:
If you just want to use the Port Knocking for an SSH shell and not
for a VNC tunnel, then specify something like "user@hostname cmd=SHELL"
(or "user@hostname cmd=PUTTY" on Windows) in the VNC Host:Display entry box
on the main panel. This will do everything short of starting the viewer.
A shortcut for this is Ctrl-S as long as user@hostname is present.
Specifying the Knocks:
In the text area below "Supply port knocking pattern" you put in the pattern
of "knocks" needed for this connection. You can separate the knocks by
commas or put them one per line.
Each "knock" is of this form:
[host:]port[/udp] [delay]
In the simplest form just a numerical port, e.g. 5433, is supplied.
Items inside [...] are optional and described below.
The packet is sent to the same host that the VNC (or SSH) connection will
be made to. If you want it to go to a different host or IP use the [host:]
prefix. It can be either a hostname or numerical IP.
A TCP packet is sent by default.
If you need to send a UDP packet, the netcat (aka "nc") program must be
installed on Unix (tcl/tk does not support udp connections). Indicate this
with "/udp" following the port number (you can also use "/tcp", but since
it is the default it is not necessary). (You can also use ":udp" to match
the knockd syntax). See the example below. For convenience a Windows netcat
binary is supplied.
The last field, [delay], is an optional number of milliseconds to delay
before continuing on to the next knock.
Examples:
5433, 12321, 1661
fw.example.com:5433, 12321/udp 3000, 1661 2000
fw.example.com:5433
12321/udp 3000
1661 2000
Note how the first two examples separate their knocks via commas ",".
The 3rd example is equivalent to the 2nd and splits them up by new lines.
Note for each knock any second number (e.g. the "2000" in "1661 2000") is
a DELAY in milliseconds, not a port number. If you had a comma separating
them: "1661, 2000" that would mean two separate knocks: one to port 1661
followed by one to 2000 (with basically no delay between them).
In examples 2 and 3, "fw.example.com" represents some machine other than
the VNC/SSH host. By default, the VNC/SSH host is the one the packet is
sent to.
If one of the items is the string "FINISH", then the part before it is
used prior to connecting and the part after is used once the connection
is finished. This can be used, say, to close the firewall port. Example:
5433, 12321, FINISH, 7659, 2314
(or one can split them up via lines as above.)
Advanced port knock actions:
If the string in the text field contains anywhere the strings "CMD=", "CMDX=",
or "SEND=", then splitting on commas is not done: it is only split on lines.
Then, if a line begins CMD=... the string after the = is run as an
external command. The command could be anything you want, e.g. it could
be a port-knocking client that does the knocking, perhaps encrypting the
"knocks" pattern somehow or using a Single Packet Authorization method such
as http://www.cipherdyne.com/fwknop/
Extra quotes (sometimes "'foo bar'") may be needed to preserve spaces in
command line arguments because the tcl/tk eval(n) command is used. You
can also use {...} for quoting strings with spaces.
If a line begins CMDX=... then before the command is run the following
tokens are expanded to strings:
%IP Current machine's IP address (NAT may make this not useful).
%NAT Try to get effective IP by contacting http://www.whatismyip.com
%HOST The remote host of the connection.
%USER The current user.
%SECS The current time in seconds (platform dependent).
%MSECS Platform dependent time having at least millisecond granularity.
Lines not matching CMD= or CMDX= are treated as normal port knocks but with
one exception. If a line ends in SEND=... (i.e. after the [host:]port,
etc., part) then the string after the = is sent as a payload for the tcp
or udp connection to [host:]port. netcat is used for these SEND cases
(and must be available on Unix). If newlines (\n) are needed in the
SEND string, use %NEWLINE. Sending binary data is not yet supported;
use CMD= with your own program.
Advanced Examples:
CMD=port_knock_client -password wombat33
CMDX=port_knock_client -password wombat33 -host %HOST -src %NAT
fw.example.com:5433/udp SEND=ASDLFKSJDF
More tricks:
To temporarily "comment out" a knock, insert a leading "#" character.
Use "sleep N" to insert a raw sleep for N milliseconds (e.g. between
CMD=... items or at the very end of the knocks to wait).
If a knock entry matches "delay N" the default delay is set to
N milliseconds (it is 150 initially).
One Time Pads:
If the text contains a (presumably single) line of the form:
PAD=/path/to/a/one/time/pad/file
then that file is opened and the first non-blank line not beginning
with "#" is used as the knock pattern. The pad file is rewritten
with that line starting with a "#" (so it will be skipped next time).
The PAD=... string is replaced with the read-in knock pattern line.
So, if needed, one can preface the PAD=... with "delay N" to set the
default delay, and one can also put a "sleep N" after the PAD=...
line to indicate a final sleep. One can also surround the PAD=
line with other knock and CMD= CMDX= lines, but that usage sounds
a bit rare. Example:
delay 1000
PAD=C:\My Pads\work-pad1.txt
sleep 4000
Port knock only:
If, in the 'VNC Host:Display' entry, you use "user@hostname cmd=KNOCK"
then only the port-knocking is performed. A shortcut for this is
Ctrl-P as long as hostname is present in the entry box. If it
matches cmd=KNOCKF, i.e. an extra "F", then the port-knocking
"FINISH" sequence is sent, if any. A shortcut for this Shift-Ctrl-P
as long as hostname is present.
============================================================================
SSVNC Escape Keys Help:
SSVNC Escape Keys:
The Unix SSVNC VNC Viewer, ssvncviewer(1), has an 'Escape Keys'
mechanism that enables using keystrokes that are bound as 'Hot Keys'
to specific actions.
So, when you have all of the modifier keys ('escape keys') pressed down,
then subsequent keystrokes are interpreted as local special actions
instead of being sent to the remote VNC server.
This enables quick parameter changing and also panning of the viewport.
E.g. the keystroke 'r' is mapped to refresh the screen.
Enter 'default' in the entry box to enable this feature and to use the
default modifier list (Alt_L,Super_L on unix and Control_L,Meta_L on
macosx) or set it to a list of modifier keys, e.g. Alt_L,Control_L.
Note that _L means left side of keyboard and _R means right side.
Alt_L is the 'Alt' key on the left side of the keyboard, and Super_L
is usually the 'WindowsFlaggie(TM)' on the left side of the keyboard,
so when both of those are pressed, the escape keys mapping take effect.
Here is info from the ssvncviewer(1) manual page:
-escape str This sets the 'Escape Keys' modifier sequence and enables
escape keys mode. When the modifier keys escape sequence
is held down, the next keystroke is interpreted locally
to perform a special action instead of being sent to the
remote VNC server.
Use '-escape default' for the default modifier sequence.
(Unix: Alt_L,Super_L and MacOSX: Control_L,Meta_L)
Here are the 'Escape Keys: Help+Set' instructions from the Popup Menu:
Escape Keys: Enter a comma separated list of modifier keys to be the
'escape sequence'. When these keys are held down, the next keystroke is
interpreted locally to invoke a special action instead of being sent to
the remote VNC server. In other words, a set of 'Hot Keys'.
To enable or disable this, click on 'Escape Keys: Toggle' in the Popup.
Here is the list of hot-key mappings to special actions:
r: refresh desktop b: toggle bell c: toggle full-color
f: file transfer x: x11cursor z: toggle Tight/ZRLE
l: full screen g: graball e: escape keys dialog
s: scale dialog +: scale up (=) -: scale down (_)
t: text chat a: alphablend cursor
V: toggle viewonly Q: quit viewer 1 2 3 4 5 6: UltraVNC scale 1/n
Arrow keys: pan the viewport about 10% for each keypress.
PageUp / PageDown: pan the viewport by a screenful vertically.
Home / End: pan the viewport by a screenful horizontally.
KeyPad Arrow keys: pan the viewport by 1 pixel for each keypress.
Dragging the Mouse with Button1 pressed also pans the viewport.
Clicking Mouse Button3 brings up the Popup Menu.
The above mappings are *always* active in ViewOnly mode, unless you set the
Escape Keys value to 'never'.
If the Escape Keys value below is set to 'default' then a default list of
of modifier keys is used. For Unix it is: Alt_L,Super_L and for MacOSX it
is Control_L,Meta_L. Note: the Super_L key usually has a Windows(TM) Flag
on it. Also note the _L and _R mean the key is on the LEFT or RIGHT side
of the keyboard.
On Unix the default is Alt and Windows keys on Left side of keyboard.
On MacOSX the default is Control and Command keys on Left side of keyboard.
Example: Press and hold the Alt and Windows keys on the LEFT side of the
keyboard and then press 'c' to toggle the full-color state. Or press 't'
to toggle the ultravnc Text Chat window, etc.
To use something besides the default, supply a comma separated list (or a
single one) from: Shift_L Shift_R Control_L Control_R Alt_L Alt_R Meta_L
Meta_R Super_L Super_R Hyper_L Hyper_R or Mode_switch.
============================================================================
STUNNEL Local Port Protections Dialog:
See the discussion of "Untrusted Local Users" in the main 'Help'
panel for info about users who are able to log into the workstation
you run SSVNC on and might try to use your encrypted tunnel to gain
access to the remote VNC machine.
On Unix, for STUNNEL SSL tunnels we provide two options as extra
safeguards against untrusted local users. Both only apply to Unix/MacOSX.
Note that Both options are *IGNORED* in reverse connection (Listen) mode.
1) The first one 'Use stunnel EXEC mode' (it is mutually exclusive with
option 2). For this case the modified SSVNC Unix viewer must be
used: it execs the stunnel program instead of connecting to it via
TCP/IP. Thus there is no localhost listening port involved at all.
This is the best solution for SSL stunnel tunnels, it works well and
is currently enabled by default. Disable it if there are problems.
2) The second one 'Use stunnel IDENT check', uses the stunnel(8)
'ident = username' to use the local identd daemon (IDENT RFC 1413
http://www.ietf.org/rfc/rfc1413.txt) to check that the locally
connecting program (the SSVNC vncviewer) is being run by your userid.
See the stunnel(8) man page for details.
Normally the IDENT check service cannot be trusted much when used
*remotely* (the remote host may be have installed a modified daemon).
However when using the IDENT check service *locally* it should be
reliable. If not, it means the local machine (where you run SSVNC)
has already been root compromised and you have a serious problem.
Enabling 'Use stunnel IDENT check' requires a working identd on the
local machine. Often it is not installed or enabled (because it is not
deemed to be useful, etc). identd is usually run out of the inetd(8)
super-server. Even when installed and running it is often configured
incorrectly. On a Debian/lenny system we actually found that the
kernel module 'tcp_diag' needed to be loaded! ('modprobe tcp_diag')
============================================================================
Disable SSL Workarounds Dialog:
Some SSL implementations are incomplete or buggy or do not work properly
with other implementations. SSVNC uses STUNNEL for its SSL encryption,
and STUNNEL uses the OpenSSL SSL implementation.
This causes some problems with non-OpenSSL implementations on the VNC server
side. The most noticable one is the UltraVNC Single Click III (SSL) server:
http://www.uvnc.com/pchelpware/SCIII/index.html
It can make a reverse connection to SSVNC via an encrypted SSL tunnel.
Unfortunately, in the default operation with STUNNEL the connection will be
dropped after 2-15 minutes due to an unexpected packet.
Because of this, by default SSVNC will enable some SSL workarounds to make
connections like these work. This is the STUNNEL 'options = ALL' setting:
it enables a basic set of SSL workarounds.
You can read all about these workarounds in the stunnel(8) manpage and the
OpenSSL SSL_CTX_set_options(3) manpage.
Why are we mentioning this? STUNNELS's 'options = ALL' lowers the SSL
security a little bit. If you know you do not have an incompatible SSL
implementation on the server side (e.g. any one using OpenSSL is compatible,
x11vnc in particular), then you can regain that little bit of security by
selecting the "Disable SSL Workarounds" option.
"Disable All SSL Workarounds" selected below will do that. On the other hand,
choose "Keep the DONT_INSERT_EMPTY_FRAGMENTS Workaround" to retain that one,
commonly needed workaround.
BTW, you can set the environment variable STUNNEL_EXTRA_OPTS_USER to add
any lines to the STUNNEL global config that you want to. See the stunnel(8)
man page for more details.
============================================================================
UltraVNC DSM Encryption Plugin Dialog:
On Unix and MacOSX with the provided SSVNC vncviewer, you can connect to an
UltraVNC server that is using one of its DSM encryption plugins: MSRC4, ARC4,
AESV2, and SecureVNC. More info at: http://www.uvnc.com/features/encryption.html
IMPORTANT: The UltraVNC DSM MSRC4, ARC4, and AESV2 implementations contain
unfixed errors that could allow an eavesdropper to recover the session
key or traffic easily. They often do not provide strong encryption, but
only provide basic obscurity instead. Do not use them with critical data.
The newer SecureVNC Plugin does not suffer from these problems.
See the bottom of this help text for how to use symmetric encryption with
Non-UltraVNC servers (for example, x11vnc 0.9.5 or later). This mode does not
suffer the shortcomings of the UltraVNC MSRC4, ARC4, and AESV2 implementations.
You will need to specify the corresponding UltraVNC encryption key (created
by you using an UltraVNC server or viewer). It is usually called 'rc4.key'
(for MSRC4), 'arc4.key' (for ARC4), and 'aesv2.key' (for AESV2). Specify the
path to it or Browse for it. Also, specify which type of plugin it is (or use
'guess' to have it guess via the before mentioned filenames).
The choice "UVNC SC" enables a special workaround for use with UltraVNC Single
Click and the MSRC4 plugin. It may not be needed on recent SC (e.g. from
~2009 and later; select "MSRC4" for these newer ones.)
You can also specify pw=my-password instead of a keyfile. Use single quotes
pw='....' if the password contains shell meta-characters `!$&*(){}[]|;<>?
Use the literal string 'pw=VNCPASSWD' to have the VNC password that you
entered into the 'VNC Password:' be used for the pw=...
SSL and SSH tunnels do not apply in this mode (any settings are ignored.)
Proxying works in this mode, as well as Reverse Connections (Listen)
The choice "SecureVNC" refers to the SecureVNC Plugin using 128 bit AES or
ARC4 with 2048 bit RSA key exchange described here:
http://adamwalling.com/SecureVNC
Note in its default mode SecureVNC is *Vulnerable* to Man-In-The-Middle attacks
(encryption but no server authentication) so do not use it with critical data.
In SecureVNC mode you do not need to supply a 'Ultra DSM Keyfile'. However,
if you DO supply a keyfile filename (recommended) if that file does not exist
you will be prompted if you want to save the UltraVNC server's RSA key in it.
The key's MD5 checksum is displayed so that you can verify that the key is
trusted. One way to print out the SecureVNC public key MD5 checksum is:
openssl rsa -inform DER -outform DER -pubout -in ./Server_SecureVNC.pkey | dd bs=1 skip=24 | md5sum
Then on subsequent connections, if you continue to specify this filename, the
SecureVNCPlugin server's RSA key will be checked against the file's contents
and if they differ the connection will be dropped.
NOTE, However, if the SecureVNC keyfile ends in the string 'ClientAuth.pkey'
then its contents are used for SecureVNC's normal Client Authentication dialog
(you need to use Windows SecureVNCPlugin to generate this file on the server
side, it is usually called "Viewer_ClientAuth.pkey", and then safely copy it
to the viewer side.) If you want to do BOTH Client Auth and server RSA key
storing (recommended), have the keyfile end in 'ClientAuth.pkey.rsa'; that way
the file will be used for storing the server RSA key and then the '.rsa' is
trimmed off and the remainder used for the SecureVNC Client Auth data filename.
Note that despite its intentions, Client Authentication in the FIRST release of
SecureVNC is still susceptible to Man-In-The-Middle attacks. Even when that
is fixed, SecureVNC Client Authentication is still susceptible to "spoofing"
attacks where the viewer user may be tricked into revealing his VNC or MS-Logon
password if his connection is intercepted. It is recommended you verify and
save the Server key (see above) in addition to using Client Authentication.
UltraVNC DSM encryption modes are currently experimental because unfortunately
the UltraVNC DSM plugin also modifies the RFB protocol(!), and so the SSVNC
vncviewer had to be modified to support it. The tight, zlib, and some minor
encodings currently do not work in this mode and are disabled.
Note that this mode also requires the utility tool named 'ultravnc_dsm_helper'
that should be included in your SSVNC kit.
Select 'Non-Ultra DSM' to use symmetric encryption to a Non-UltraVNC server via
a supported symmetric key cipher. x11vnc supports symmetric encryption via,
e.g., "x11vnc -enc aesv2:./my.key". Extra ciphers are enabled for this mode
(e.g. blowfish and 3des). 'UVNC SC' and SecureVNC do not apply in this mode.
Note for the Non-Ultra DSM case it will also work with any VNC Viewer
(i.e. selected by Options -> Advanced -> Change VNC Viewer) not only the
supplied SSVNC vncviewer.
For experts: You can also set the random salt size and initialization vector
size in Salt,IV for example "8,16". See the x11vnc and 'ultravnc_dsm_helper
-help' documentation for more info on this.
============================================================================
Private SSH KnownHosts file Dialog:
Private SSH KnownHosts file:
On Unix in SSH mode, let the user specify a non-default
ssh known_hosts file to be used only by the current profile.
This is the UserKnownHostsFile ssh option and is described in the
ssh_config(1) man page. This is useful to avoid proxy 'localhost'
SSH key collisions.
Normally one should simply let ssh use its default file
~/.ssh/known_hosts for tracking SSH keys. The only problem with
that happens when multiple SSVNC connections use localhost tunnel
port redirections. These make ssh connect to 'localhost' on some
port (where the proxy is listening.) Then the different keys
from the multiple ssh servers collide when ssh saves them under
'localhost' in ~/.ssh/known_hosts.
So if you are using a proxy with SSVNC or doing a "double SSH
gateway" your ssh will connect to a proxy port on localhost, and you
should set a private KnownHosts file for that connection profile.
This is secure and avoids man-in-the-middle attack (as long as
you actually verify the initial save of the SSH key!)
The default file location will be:
~/.vnc/ssh_known_hosts/profile-name.known
but you can choose any place you like. It must of course be
unique and not shared with another ssh connection otherwise they
both may complain about the key for 'localhost' changing, etc.
============================================================================
SSH Local Port Protections Dialog:
See the discussion of "Untrusted Local Users" in the main 'Help'
panel for info about users who are able to log into the workstation
you run SSVNC on and might try to use your encrypted tunnel to gain
access to the remote VNC machine.
On Unix, for SSH tunnels we have an LD_PRELOAD hack (lim_accept.so)
that will limit ssh from accepting any local redirection connections
after the first one or after 35 seconds, whichever comes first.
The first SSH port redirection connection is intended to be the one
that tunnels your VNC Viewer to reach the remote server.
You can adjust these defaults LIM_ACCEPT=1 LIM_ACCEPT_TIME=35 by
setting those env. vars. to different values.
Note that there is still a window of a few seconds the Untrusted
Local User can try to connect before your VNC Viewer does. So this
method is far from perfect. But once your VNC session is established,
he should be blocked out. Test to make sure blocking is taking place.
Do not use this option if you are doing SSH Service redirections
'Additional Port Redirections (via SSH)' that redirect a local port
to the remote server via ssh -L.
Note that if the shared object "lim_accept.so" cannot be found,
this option has no effect. Watch the output in the terminal for
the "SSVNC_LIM_ACCEPT_PRELOAD" setting.
============================================================================
Multiple LISTEN Connections Dialog:
Set this option to allow SSVNC (when in LISTEN / Reverse connections
mode) to allow multiple VNC servers to connect at the same time and
so display each of their desktops on your screen at the same time.
This option only applies on Unix or MaOSX when using the supplied
SSVNC vncviewer. If you specify your own VNC Viewer it has no effect.
On Windows (only the stock TightVNC viewer is provided) it has no
effect. On MacOSX if the COTVNC viewer is used it has no effect.
Rationale: To play it safe, the Unix vncviewer provided by SSVNC
(ssvncviewer) only allows one LISTEN reverse connection at a time.
This is to prohibit malicious people on the network from depositing
as many desktops on your screen as he likes, even if you are already
connected to VNC server you desire.
For example, perhaps the malicious user could trick you into typing
a password into the desktop he displays on your screen.
This protection is not perfect, because the malicious user could
try to reverse connect to you before the correct VNC server reverse
connects to you. This is even more of a problem if you keep your
SSVNC viewer in LISTEN mode but unconnected for long periods of time.
Pay careful attention in this case if you are to supplying sensitive
information to the remote desktop.
Enable 'Multiple LISTEN Connections' if you want to disable the default
protection in the Unix SSVNC vncviewer; i.e. allow multiple reverse
connections simultaneously (all vnc viewers we know of do this by default)
For more control, do not select 'Multiple LISTEN Connections', but
rather set the env. var SSVNC_MULTIPLE_LISTEN=MAX:n to limit the number
of simultaneous reverse connections to "n"
============================================================================
Use XGrabServer (for fullscreen) Dialog:
On Unix, some Window managers and some Desktops make it difficult for the
SSVNC Unix VNC viewer to go into full screen mode (F9) and/or return.
Sometimes one can go into full screen mode, but then your keystrokes or
Mouse actions do not get through. This can leave you trapped because you
cannot inject input (F9 again) to get out of full screen mode. (Tip:
press Ctrl-Alt-F2 for a console login shell; then kill your vncviewer
process, e.g. pkill vncviewer; then Alt-F7 to get back to your desktop)
We have seen this in some very old Window managers (e.g. fvwm2 circa
1998) and some very new Desktops (e.g. GNOME circa 2008). We try
to work around the problem on recent desktops by using the NEW_WM
interface, but if you use Fullscreen, you may need to use this option.
The default for the SSVNC Unix VNC viewer is '-grabkbd' mode where it will
try to exclusively grab the keyboard. This often works correctly.
However if Fullscreen is not working properly, try setting this
'Use XGrabServer' option to enable '-graball' mode where it tries to grab
the entire X server. This usually works, but can be a bit flakey.
Sometimes toggling F9 a few times gets lets the vncviewer fill the whole
screen. Sometimes tapping F9 very quickly gets it to snap in. If GNOME
(or whatever desktop) is still showing its taskbars, it is recommended
you toggle F9 until it isn't. Otherwise, it is not clear who gets the input.
Best of luck.