Remote Control Toolkit
From Sun Ray User Group Wiki
Contents |
Overview
The Sun Ray Remote Control Toolkit (RCT) is a community developed set of scripts that take advantage of open source tools. The goal of the Sun Ray RCT is to provide administrators of Sun Ray Servers with a suite of tools that is on par or exceed the remote control capabilities of other multiuser systems such as Citrix or Windows Terminal Server. The following features are available with this version of the Sun Ray RCT.
- Remote control of both normal (i.e. Gnome, CDE) and CAM/Kiosk based sessions
- Can be operated in agent mode where every session is available to be controlled or on demand where a user can make their session available for remote control.
- Sessions by default are shared and can be viewed by many users at the same time, an excellent training tool.
- Users with root privileges can control any session whether or not the agent is running or the user allowed remote control.
- Users with root privileges can also remote control an idle Sun Ray (i.e. one that is not logged in). Should the user forget (or choose) not to log off, the Sun Ray will disconnect (via utdetach) when the remote control session has ended. This will invoke utxlock and the Sun Ray will sit at a lock screen.
- All remote sessions are password protected with two randomly generated 9 character alpha-numeric password. One password is for full control of the session and one is for read only. These passwords are available only to the user and administrators with root privileges.
- Recording of user sessions or your own session is available. Recordings are in in Adobe Flash format and can be played on any device with a flash enabled browser. This is not only a great tool from a quality assurance standpoint, but it is also extremely handy for generating how to's and screen casts.
The core open source programs behind the Sun Ray RCT are x11vnc from Karl Runge, vnc2swf (C Version) from Yusuke Shinyama, and of course VNC itself (using source from both RealVNC and TightVNC). The magic however of the Sun Ray RCT is in the scripting! :)
Demos
- A demo of remote controlling and recording an agent based session using the Sun Ray RCT can be viewed on the ThinkThin blog.
- A demo of remote controlling an idle Sun Ray can be viewed on the ThinkThin blog
Support
Support for the Sun Ray RCT is community driven and is on a best effort basis. The Sun Ray RCT is distributed with the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
Versions
- Current Version is 0.5 which supports SRSS 4.0 only
- Updated for SRSS 4.0 and Kiosk Mode
- Previous Version is 0.4.1 for SRSS versions prior to 4.0
- The most up-to-date source code can be obtained from
svn.sun-rays.org. For detailed information regarding the source code repository you may check the Subversion wiki page.
SVN quick start:
$svn checkout https://svn.sun-rays.org:4443/SUNWutRC/trunk SUNWutRC
Installation
Installation is very simple. However if you choose to use agent mode, only sessions created after installation will be available for remote control. If you are running Kiosk mode or want to control idle sessions, a restart will be necessary.
Shared Memory Concerns
There are shared memory issues with x11vnc (see Sun Ray Gotcha #2) that may arise which may require changes to /etc/system. If these changes are neccesary, they will require a reboot of the server.
Starting with version .02 (non-released) the Sun Ray RCT scripts uses the -onetile option which considerably reduces shared memory requirements. If you have a very large deployment (as measured by number of users per server), you may have to make other changes.
Prerequisite Packages
- Solaris
- Solaris 10
- No prerequisite packages needed
- OpenSolaris - (Solaris Express or Nevada builds)
- The x11vnc binary was built against version 0.9.7 of libssl and libcrypto. You will need to symlink 0.9.8 to the previous version.
- cd /usr/sfw/lib
- ln -s libcrypto.so.0.9.8 libcrypto.so.0.9.7
- ln -s libssl.so.0.9.8 libssl.so.0.9.7
- Linux
- Requires the following packages. These packages may be included with your distribution, or need to be downloaded from another source.
- x11vnc (>=0.8.4)
- vncviewer
- vnc2swf (C version)
Toolkit Installation Steps
- unzip SUNWutRC-*.zip
- cd SUNWutRC-*
- ./install.sh
Toolkit Install Locations
The base install location for the RC Toolkit is as follows:
- 0.5 - /opt/SRSS-Addons/RemoteControl
- 0.4.1 - /opt/SUNWutRC/
In the following instructions, <inst_base> will be used to indicate the install location.
Configuring the Toolkit
The Toolkit is configured automatically during the install process. If you would like to change the mode of operation or turn on/off features use the following command
<inst_base>/sbin/utrcadm
Using the Toolkit
The Sun Ray RC Tookit operates in three modes.
- Agent Mode in which all normal sessions automatically are setup to be remote controlled
- User Initiated mode is enabled individually by each user
- Forced Mode in which an admin user may force the control of any session.
The mode may be change by using the utrcadm commend (see above)
Additionally, all modes have the ability to record the session to a flash video file.
Agent Mode
- From a Sun Ray session
- If you have a session on a Sun Ray Server and the user you would like to remote control also has a session on that Sun Ray Server you have two options for controlling that session:
- Control script - Uses the local VNC viewer to attach to the supplied users session. The view mode (full control or view only) must be specified.
Usage: <inst_base>/Control <username> full|view
- WebControl script - Will display users random session password, and launch a web browser to the remote controllable x11vnc session. The browser conencts to a Java based viewer supplied by x11vnc.
Usage: <inst_base>/WebControl <username>
- Note the password displayed (for Full Control or View Only) and enter it in the authentication box.
- NOTE 1: You will need root permissions on the Server to remote control sessions.
- NOTE 2: Usernames are case-sensitive and must match the prefix of the session files in /tmp/SUNWutRC
- From a Non-Sun Ray Session
- You may remote control any session on any Sun Ray server remotely. As root, use ssh to connect to the server where the target session resides. Each user will have a <username>.agent.settings.vnc file under /tmp/SUNWutRC. This file will give you information to connect via the following methods:
- VNCviewer - Use the vncviewer on your remote system to connect to the VNCDISPLAY identified in the settings file.
- Java enabled Web Browser - Point your browser to the URL identified the the settings file.
- The settings file will also contain both the View Only and Full Control passwords needed to connect.
User Initiated Mode
- Any user can run <inst_base>/StartRC to allow "on demand" remote control or viewing of their session. After the user runs this script, they can supply other users with the connection information along with their Full Control or View Only Password.
- Users can see their passwords by looking at /tmp/SUNWutRC/$USER.agent.settings.vnc Other people that wish to view this session would need to have a VNC Viewer or a Java enabled web browser and point it to the Server and Display that are contained in the settings file.
- This file is secured with 600 perms to the user that ran StartRC. That means only that user and users with root privileges can view that file. When the user is done having others remote control or view their session they can hit CTRL+C to end the agent.
Forced Mode
- Assuming that you have root privileges and the user you want to control is not already running the agent, you can run <inst_base>/admin/remoteuser to remote control any session. This command lists available sessions and allows you to start the VNC server for a particular user. This script may be run locally or remotely over ssh.
# ./remoteuser The following Sun Rays are Logged in ------------------------------------ DISP Token User 2.0 pseudo.00144f7f610d craig 3.0 pseudo.080020d87c84 brad 4.0 pseudo.080020d87cf9 scott Which USER would you like to control? Enter USER NAME [ q to quit]:scott Attempting to remote control scott on Display :4.0 Full Control password is CYT44VfNL View Only password is g7fgyAkbb CTRL+C to stop controlling Display :4.0 *****Please remember to logout***** Should you forget to logout, the session will detach as a security measure The VNC desktop is: tequila:10 Java viewer URL: http://tequila:5810/ PORT=5910
- You can now control the selected session using the following methods:
- VNCviewer - Use the vncviewer to connect to the VNC Desktop identified in the output.
- Java enabled Web Browser - Point your browser to the Java viewer URL identified in the output.
- The script output will also contain both the View Only and Full Control passwords needed to connect.
- NOTE: You should not try to Force Control a session which is already running in Agent Mode. This causes two x11vnc processes to be attached to the same Xserver. This is just needless overhead and will add to confusion should you choose to record the session.
Controlling Idle Sun Rays
In order to remote a control Sun Ray that is idle (i.e. not logged in), Idle Session Control must be enabled. During the install you were given an option to enable it. To enable or disable after installation:
# <inst_base>/sbin/utrcadm -i on|off
- Controlling an idle session
- Use <inst_base>/admin/remotegreet to select the idle session and enable the x11vnc server.
# ./remotegreet The following Sun Rays are not logged in ---------------------------------------- DISP Token User 2 pseudo.080020d87c84 ???? 3 pseudo.00144f6f752b ???? 4 pseudo.00144f7f610d ???? 5 pseudo.080020d87cf9 ???? Which one would you like to control? Enter DISP Number [ q to quit]:2 Attempting to remote control Display :2 Full Control password is 8syFvl9py View Only password is EeBxob7Bn CTRL+C to stop controlling Display :2 *****Please remember to logout***** Should you forget to logout, the session will detach as a security measure The VNC desktop is: tequila:10 Java viewer URL: http://tequila:5810/ PORT=5910
- You can now control the selected session using the following methods:
- VNCviewer - Use the vncviewer to connect to the VNC Desktop identified in the output.
- Java enabled Web Browser - Point your browser to the Java viewer URL identified in the output.
- The script output will also contain both the View Only and Full Control passwords needed to connect.
- NOTE 1: Unlike agent mode, the x11vnc process will end after being remote controlled
- NOTE 2: Upon disconnect of the VNC viewer, /opt/SUNWut/bin/utdetach is ran. Should the person who logged into the remote controlled session forget (or choose not) to logout, the Sun Ray will be locked via utxlock.
Recording Sessions
- Any Remote Control enabled session can be recorded. The session is recorded into a Flash based movie format and can be displayed on any Flash enabled browser. A normal user cannot record another users session.
- Recordings will be stored in /tmp/SUNWutRC/recordings with a user-timestamp file name. There will be an html file and a swf file.
- These files can only be read by root or the user that created the recording. Recordings may be watched by other users if the recording is moved out of /tmp/SUNWutRC/recordings and its permissions are changed accordingly.
- Recording User Sessions
- Agent based sessions can be recorded by running:
# <inst_base>/RecordUser <username>
- Use Ctrl+C to stop the recording.
- Recording Your Session
- Whether Agent based or User Initiated, a user can record their session by running:
# <inst_base>/RecordMe
- Use Ctrl+C to stop the recording.
- If for no other value, this is great for How To's and screencasts.
- Please read the known issues section for why your screen will lock when you finish recording your own session.
- Recording Forced or Idle Sessions
- As of the current version you cannot record a forced (remoteuser) or idle (remotegreet) session. This is due to not being able to get the screen geometry to pass to vnc2swf.
- A workaround is to be on a Sun Ray in either Agent or User Initiated mode and record your session. During this recording you may then remote control the forced or idle session and you actions will be captured.
- This is intended to be fixed in a future release.
Known Issues
- This Toolkit is only in it's first couple of releases, there could be problems
- The 1.6 java plugin sometimes has trouble with the VNC Viewer jar file. If your browser locks up, use an earlier version of the plugin.
- Xscreensaver is troublesome. If it pops up for users when they are working remove the -afteraccept args from <inst_base>/agent/remoteagent and <inst_base>/admin/remoteuser.
- See other workarounds for xscreensaver on the x11vnc Sun Ray Page
- When you attach to your own session to record a movie using RecordMe and you are finished recording, Xscreensaver will be invoked. This is due the -gone argument of the remoteagent script to ensure that if you remote control a locked session, it will re-lock when you disconnect from the session.
- Some of this is kludgey. remoteuser for example...it was done that way since there is more than a likely chance of a matching number(s) from the display number in the token, the IP, or the model.
- There are probably better ways to do some of the scripting, I'm all ears. This is a community tool.
- An earnest attempt has been made at error handling, but the GIGO principle applies
- The included binaries may not work on your system. Work around is to build them yourself and move them into <inst_base>/bin
We need a script repository with version and change control.
To Do
- Protected Web page and associated scripts to list all of the available sessions
- Should work across a Host Group
- Careful about CAM sessions as they'll have duplicate names
- Investigate using ssl to view sessions over
- Figure out best xscreensaver work-around.
- Investigate tight VNC file sharing capabilities
- Add method of stopping User Initiated Control
- Add Launch Menu icons for starting/stoping User Initiated control
- Add possible user notfvication and acceptance of monitoring
- Add Recording application (start/stop etc)
Sun Ray RTC script Listing and Explanation
<inst_base>: Control <== For controlling agent based sessions from a Sun Ray Session using vncviewer RecordUser <== Records an agent based user session to SWF format WebControl <== For controlling agent based sessions from a Sun Ray Session using a Java enabled browser RecordMe <== Records your session. Great for Screencasts. StartRC <== On Demand Remote Control <inst_base>/admin: remotegreet <== Control an idle Sun Ray. Must be root. remoteuser <== Control any logged in Sun Ray user. Must be root. <inst_base>/agent: 1300.SUNWut <== Sample Startup script remoteagent <== The remote control agent <inst_base>/bin: findvncports <== Finds empty ports for display, RFB, and http for remote control randwait <== Perl script to generate a random wait time (0-9 seconds) to run findvncports. record <== The script that's used by RecordMe and RecordUser setpasswd <== Perl script that generates random 9 alpha-numeric passwords for the sessions xss_killer <== script to kill xscreensaver when attaching to a locked session. Flakey <inst_base>/platform: SPARC <== Home for x11vnc, vncviewer, and vnc2swf SPARC binaries x86 <== Home for x11vnc, vncviewer, and vnc2swf x86 binaries <inst_base>/sbin: shm_clear <== Script to clear orphaned shared memory segments utrcadm <== RC Administration script for enabling/disabling features and changing control mode uninstall.sh <== Uninstalls the RC Toolkit <inst_base>/share: x11vnc <== Contains x11vnc web components, home page and java viewer.
Under the Hood
Please see RCT Details for some details on how the Toolkit is put together
Credits
This wouldn't be possible without:
1) Code from Karl Runge, Yusuke Shinyama, and the folks that work on VNC. Say thanks by putting a $ in their PayPal donation bucket
2) You the community for your tireless efforts surrounding Sun Ray.
