Version 1.7 of httpvnc features a new command line interface. I call this interface with its own set of session ids the onetime interface, because any id is good only for one action. In this post I will show how to use it.
Preliminaries
It is very important to note that the cli of httpvnc is NOT intended for use by desktop users directly. Anyone who has access to this interface will be able to control all desktop sessions for every user in their entirety. I am aware that it might be handy to have a cli for desktop users ready and available, and it wouldn't even be rocket science to build one of these now that the basic functionality is available already. However, this will have to wait for a release in the future.
So who has access to the httpvnc cli? Anyone who is in the group httpvncd. For example, you might build your own session management system using Tomcat (Java) running under some user 'tomcat'. In order for your system to be able to use the command line interface, put 'tomcat' in the group 'httpvncd'.
Starting sessions
You can start a session on the shell by using this syntax:
httpvnc create user name type geometry persistent
where the parameters mean:
- user is the name of a user. The user must be in the group httpvnc, otherwise nothing will happen. The desktop created will be running under this user id.
- name is a freely selectable name. Before creating a new session, httpvnc will search for a session that already belongs to this user and has the specified name. If such a session is found, no new session is created, but the existing one is returned.
- type is the type of the desktop. The type may be 'fvwm' for a "standard" fvwm desktop. You may also specify a type of the form 'fvwm:configname', httpvnc will then search for a config file configname in /usr/share/fvwm and ~/.fvwm
- geometry is a geometry string of the form widthxheight (in pixels), e.g. 1024x768. This will be the height of the desktop (if a new one is created).
- persistent is 0 for non-persistent (i.e. the desktop will automatically close on user disconnect) or 1 for persistent (desktop will survive user disconnect and may later be reconnected).
tomcat@ts $ httpvnc create hoefer 'My first desktop' fvwm 1024x768 1 d5403dab-2c93-4e7e-954d-b7679d600178 tomcat@ts $ httpvnc create hoefer 'My first desktop' fvwm 1600x1200 0 d5403dab-2c93-4e7e-954d-b7679d600178 (User connects to desktop using URL 'https://ts:8080/onetime?sid=d5403dab-2c93-4e7e-954d-b7679d600178') tomcat@ts $ httpvnc create hoefer 'My first desktop' fvwm 800x600 0 bf7bcd5e-6ade-4c68-ac56-b6a1c5c3b3f9
Note that the first time the create command is used, a persistent fvwm desktop (using the standard fvwm configuration file) running under the user hoefer with dimensions 1024x768 and the name 'My first desktop' is created. The result is an id that may be used to connect to this desktop. The second call to create returns the same id, because there is already a desktop with name 'My first desktop' under hoefer running, and nobody has connected to the desktop as of yet. So no new desktop is created. The type, geometry and persistence settings have no meaning in this case. After someone connected to the desktop between the second and the third call to "create", the third call to "create" yields another id. This doesn't mean that a new desktop was started (in this case), but the "old" id was used up by the user connect, so a new one was created automatically that can be used once (before another one is created). So as with the second call, the third call also produces a (different) id that refers to one and the same desktop.
Connecting to sessions
Once you have an id, you may connect to the desktop session referred to by this id once using the URL 'https://hostname:port/onetime?sid=id'. The port will usually be 8080, but may differ for your environment (you can set another port to be used on startup by setting the LISTENING_PORT environment variable, refer to the output of
tomcat@ts $ httpvnc help
for further help.
No password must be supplied, no username will be requested. Authentication is provided by the fact that you know this id. After connecting once to this id, it will become invalid and you must create new ids for further connections.
Listing sessions
Sessions may be listed using the 'list' command with this syntax: httpvnc list username
Example:
tomcat@ts $ httpvnc list hoefer bf7bcd5e-6ade-4c68-ac56-b6a1c5c3b3f9:1409668213:My first desktop
The list command produces a list of sessions, one session per line. Each session is an array of values, separated by a colon (:). The first value is the (onetime) session id. You can use this id in order to connect to the session by means of the onetime-URL. The second value is the timestamp taken when the session was created. The third value is the name of the session; as shown before, this name can be used in order to get the session id by means of the create command (although with the 'create' command, a new session will be created should the requested session not exist, while the list command only lists available sessions).
Destroying sessions
Sessions can be destroyed using the onetime id and (for safety reasons) the username the session belongs to (httpvnc destroy username id):
tomcat@ts $ httpvnc destroy hoefer bf7bcd5e-6ade-4c68-ac56-b6a1c5c3b3f9