Statistics
| Branch: | Tag: | Revision:

root / docs / index.rst @ 3b98303f

History | View | Annotate | Download (7.7 kB)

1
.. snf-vncauthproxy documentation master file, created by
2
   sphinx-quickstart on Thu Nov 14 20:47:22 2013.
3
   You can adapt this file completely to your liking, but it should at least
4
   contain the root `toctree` directive.
5

    
6
snf-vncauthproxy's documentation
7
********************************
8

    
9
snf-vncauthproxy is a daemon, which acts as a VNC authentication proxy between
10
a VNC client and server.
11

    
12
snf-vncauthproxy daemon listens on a TCP socket for control messages and sets
13
up one-time port forwardings upon request.
14

    
15
Main features include:
16
  * Lightweight, coroutine-based main loop with gevent
17
  * Supports RFB protocol version 3.8
18
  * IPv4 and IPv6 support
19
  * Configurable timeout for client connections
20

    
21
Its main use is to enable VNC clients to connect to firewalled VNC servers.
22

    
23
It is used by `Synnefo <https://code.grnet.gr/projects/synnefo>`_ to provide
24
users with (VNC) console access to their VMs.
25

    
26
Installation
27
^^^^^^^^^^^^
28

    
29
snf-vncauthproxy is currently packaged only for Debian (stable).
30

    
31
You can find and install the latest version snf-vncauthproxy at Synnefo's apt
32
repository:
33

    
34
| ``http://apt.dev.grnet.gr {release}``
35

    
36
To import the GPG key of the repo, use:
37

    
38
| ``curl https://dev.grnet.gr/files/apt-grnetdev.pub | apt-key add -``
39

    
40
In case you're upgrading from an older snf-vncauthproxy version or it's the
41
first time you're installing snf-vncauthproxy, you will prompted to configure
42
a vncauthproxy user (see below for more information on user management).
43

    
44
Overview
45
^^^^^^^^
46

    
47
snf-vncauthproxy listens on a TCP socket for control (JSON) messages from
48
clients. The format of the control messages is:
49

    
50
.. code-block:: console
51

    
52
     Control request, in JSON:
53
     {
54
         "source_port":
55
             <source port or 0 for automatic allocation>,
56
         "destination_address":
57
             <destination address of backend server>,
58
         "destination_port":
59
             <destination port>
60
         "password":
61
             <the password to use to authenticate clients>
62
         "auth_user":
63
             <user for control connection authentication>,
64
          "auth_password":
65
             <password for control connection authentication>,
66
     }
67

    
68
     The <password> is used for MITM authentication of clients
69
     connecting to <source_port>, who will subsequently be
70
     forwarded to a VNC server listening at
71
     <destination_address>:<destination_port>
72

    
73
     Control reply, in JSON:
74
     {
75
         "source_port": <the allocated source port>
76
         "status": <one of "OK" or "FAILED">
77
     }
78

    
79
snf-vncauthproxy will then spawn a greenlet to handle the incoming control
80
message, establish the connection with the server (RFB handshake) and set up a
81
listening socket for the client to connect (with a configurable timeout).
82

    
83
When the client connects, the greenlet will proxy the traffic between the
84
client and server (reading and writing to the client and server socket when
85
needed).
86

    
87
The handling of control connections, client connections and the actual proxying
88
is implemented using `gevent <http://www.gevent.org/>`_ and greenlets.
89

    
90
Usage
91
^^^^^
92

    
93
The snf-vncauthproxy daemon can be either run manually or managed via its init
94
script.
95

    
96
If you're using the init script, snf-vncauthproxy reads its options from its
97
default file (``DAEMON_OPTS`` parameter in ``/etc/default/vncauthproxy``).
98
Refer to the vncauthproxy help output for a detailed listing and information
99
on all available options:
100

    
101
.. code-block:: console
102

    
103
    # vncauthproxy --help
104

    
105
By default snf-vncauthproxy will listen to ``127.0.0.1:24999`` TCP, for
106
incoming control connections and uses the ``25000-30000`` range for the
107
listening / data sockets.
108

    
109
Version 1.5 replaced Unix domain control sockets with TCP control sockets. This
110
change made it necessary to introduce an authentication file to replace the
111
POSIX file permissions, which protected the domain sockets.
112

    
113
The default path for the auth file is ``/var/lib/vncauthproxy/users``
114
(configurable by the ``--auth-file`` option). Each line in the file represents
115
one user which is allowed to use the control socket and should be in the
116
following format:
117

    
118
.. code-block:: console
119

    
120
    username:$6$salt$hash
121

    
122
The password part of the line (after the colon) is the output of crypt(), using
123
a random 16-char salt with SHA-512.
124

    
125
To manage the authentication file, you can use the vncauthproxy-passwd tool,
126
to easily add, update and delete users:
127

    
128
To add a user:
129

    
130
.. code-block:: console
131

    
132
    # vncauthproxy-passwd /var/lib/vncauthproxy/users user
133

    
134
You will be prompted for a password.
135

    
136
To delete a user:
137

    
138
.. code-block:: console
139

    
140
    # vncauthproxy-passwd -D /var/lib/vncauthproxy/users user
141

    
142
See the help output of the tool for more options:
143

    
144
.. code-block:: console
145

    
146
    # vncauthproxy-passwd -h
147

    
148
.. warning:: The vncauthproxy daemon requires a restart for the changes in the
149
 authentication file to take effect.
150

    
151
.. warning:: After installing snf-vncauthproxy for the fist time, make sure
152
 that you create a valid authentication file and define any users needed. The
153
 vncauthproxy daemon will start but will not be usable if no users are defined
154
 or if no authentication file is present.
155

    
156
Version 1.5 introduced also support for SSL for the control socket. If you
157
enable SSL support (``--enable-ssl`` parameter, disabled by default) you wil
158
have to provide a certficate and key file (``--cert-file`` and ``--key-file``
159
parameters). The default values for certificate and key files are
160
``/var/lib/vncauthrpoxy/{cert,key}.pem`` respectively.
161

    
162
For detailed help on its configuration parameters, either consult its man page
163
or run:
164

    
165
| ``snf-vncauthproxy --help``
166

    
167
on the command line.
168

    
169
snf-vncauthproxy also provides a client which can be used to test from the
170
command line that snf-vncauhtproxy has been deployed correctly. It also
171
provides a method (``request_forwarding``) which can be used fron any Python
172
programm to request forwarding from the snf-vncauthproxy daemon.
173

    
174
See the client's usage / help output and the method's signature for more
175
information on how to use the them
176

    
177
Usage with Synnefo
178
==================
179

    
180
Synnefo (snf-cyclades-app) uses snf-vncauthproxy to provide users (VNC) console
181
access to their VMs.
182

    
183
Synnefo uses `Ganeti <https://code.google.com/p/ganeti/>`_ and KVM for the
184
cluster and VM management. In the common case the Ganeti nodes, running the KVM
185
instances are firewalled, and only the Cyclades (Compute) app server
186
(snf-cyclades-app) is publicly accessible. In order for users to be able to
187
access the VNC console /server (spawned by the KVM instances on the Ganeti
188
nodes), snf-cyclades-app uses snf-vncauthproxy to allow users to connect to the
189
VNC servers and access the VNC consoles of their VMs.
190

    
191
If you're running snf-vncauthproxy on the same host as snf-cyclades-app,
192
you will only need to configure one Synnefo setting. Specifically,
193
the ``CYCLADES_VNCAUTHPROXY_OPTS`` dict in
194
``/etc/synnefo/20-snf-cyclades-app-api.conf`` should be edited to match
195
snf-vncauthproxy configuration (user, password, SSL support, certificate file).
196

    
197
In case you want to deploy snf-vncauthproxy on a different host than
198
snf-cyclades-app, you should make sure that you change the default listening
199
address (and / or port) for snf-vncauthproxy and make sure that
200
snf-cyclades-app can connect to the snf-vncauthproxy on the listening address /
201
port. It's also recommended to enable SSL on the control socket in that case.
202

    
203
Changelog
204
^^^^^^^^^
205

    
206
* v1.5 :ref:`Changelog <Changelog-1.5>`
207

    
208
Upgrade notes
209
^^^^^^^^^^^^^
210

    
211
.. toctree::
212
   :maxdepth: 1
213

    
214
    v1.4 -> v1.5 <upgrade/upgrade-1.5.rst>
215

    
216
Contact
217
^^^^^^^
218

    
219
For questions or bug reports you can contact the Synnefo team at the following
220
mailing lists:
221

    
222
 * Users list: synnefo@googlegroups.com
223
 * Developers list: synnefo-devel@googlegroups.com
224

    
225
License
226
^^^^^^^
227

    
228
snf-vncauthproxy is licensed under GNU Generic Public License version 2
229
(GPLv2), please see LICENSE for the full text.