====== Remote Observing ======

  - Preliminaries.
    * Review the [[cso:policy:remote_obs]] policy.
    * Obtain approval from the CSO Manager.
    * Test your [[#Computer configuration]].
    * Make any hardware requests before 15 HST. 
  - [[#Connect to the VNC desktop(s)]] on kilauea.
  - Open the shutter no earlier than one hour after sunset. Prior to opening the shutter: 
    * Check the [[cso:weather:weather|weather]] conditions and forecast. 
    * Check the [[http://cso.caltech.edu/webcams.html|webcams]]
  - [[#After observing]]:
    * Close the shutter no later than before sunrise,
    * Stow the telescope,
    * Turn off the receiver,
    * Exit UIP; and 
    * Exit from your account. Please leave the xterm active.

For sunset and sunrise times, refer to the [[http://aa.usno.navy.mil/data/docs/RS_OneDay.php|USNO]] or [[http://www.esrl.noaa.gov/gmd/grad/solcalc|NOAA]] calculators or to the [[http://www.eao.hawaii.edu/weather|EAO Weather]] page.

In case of problems during, CSO staff are available but can provide remote assistance only. In case of an insuperable malfunction, observations will cease for the night.

===== Supported instruments =====

  * The [[cso:instruments:heterodyne:sidecab_rxb|230 GHz and 460 GHz receivers]] with the [[cso:instruments:heterodyne:ffts1|FFTS1]] and [[cso:instruments:heterodyne:ffts2|FFTS2]] spectrometers
  * [[cso:instruments:music:music]]
  * [[cso:instruments:sharcii:sharcii]]
  * [[http://lennon.astro.northwestern.edu/SHARP|SHARP]]
  * [[cso:instruments:zspec:zspec]]

=== Caveats === 

  * Be sure ZA < 30° when switching receiver bands.

===== Computer configuration =====

Remote observing requires [[wp>ssh]] and a [[wp>VNC]] viewer. Although other configurations may work, we've tested these options:

  * Mac OSX with ScreenSharing, the included viewer. This viewer can scale the virtual desktop to fit the physical screen. Additional connections open in new windows. 
    * On OSX.9, OSX.8, and OSX.6: no difficulties.
    * On OSX.7, there's a minor bug with scaling (workaround: resize the window).
    * On OSX.5, the viewer does not update properly. 
  * Linux
    * SUSE and RedHat with ''vncviewer'' ([[wp>tightvnc]]/[[wp>tigervnc]]). This viewer does not support scaling. Additional connections open in new windows.
    * SUSE and RedHat with [[wp>krdc]]. This viewer supports scaling and tabs. Additional connections open in new windows.
    * Ubuntu with [[wp>vinagre]]. This viewer supports scaling and tabs. Additional connections open in new tabs.
    * Ubuntu with [[wp>remmina]]. This viewer requires [[ssh_vnc|manual]] configuration. This viewer supports scaling and tabs.
  * Windows XP, 7, and 8.1 with [[wp>PuTTY]] and [[wp>TightVNC]] viewer.
  * Other configurations: run the VNC viewer on kilauea with an X window display on the local computer. Performance may suffer.

Although big screen or additional monitor is nice, it is possible to observe using a laptop. 

===== Connect to the VNC desktop(s) =====

  * The virtual remote observing desktops are persistent, so if you are disconnected you can restart the viewer without losing any data. You may also connect multiple viewers from the same or different locations if you want to have an observing party. All viewers can control the telescope, however, so coordination is advised.
  * For security, all connections must use [[wp>Tunneling_protocol#Secure_shell_tunneling|ssh tunnels]]. When you start a VNC viewer on your computer using an ''ssh'' tunnel to ''kilauea'', you'll be prompted for two passwords: first your regular ''kilauea'' password and then the VNC password. Consult staff for passwords.
  * If you have the same username on ''kilauea'' and on your computer, you may omit ''**-l //user//**'' from the commands.
  * The ''ssh'' [[http://www.openbsd.org/cgi-bin/man.cgi?query=ssh|documentation]] is equivocal whether the compression option, ''-C'', is beneficial. So it is worthwhile to try connections both with and without compression to determine what's best.
  * Please test your connection prior to observing. If you encounter any problems, please contact the CSO staff, ideally during regular hours. 

=== Unix (and similar) ===

  * The {{csovnc.pl}} script is the recommended method of connecting to the VNC desktops. If the script fails for some reason, use [[ssh_vnc|manual]] configuration.

  * Download the {{csovnc.pl}} script to a convenient location. Make it executable: \\ ''mycomp> **chmod 755 csovnc.pl** ''
  * Choose the desktop //function// from the table below. 
  * The script sets up the ssh tunnel and opens the VNC viewer: \\ ''mycomp> **csovnc.pl -l //user// //function// **''
  * The script recognizes function names, port numbers, or desktop numbers. For example, the following are equivalent ways to connect to the UIP desktop: \\ ''mycomp> **csovnc.pl -l //user// uip **'' \\ ''mycomp> **csovnc.pl -l //user// 5902 **'' \\ ''mycomp> **csovnc.pl -l //user// 2 **''
  * Some instruments use more than one desktop; run the script again if necessary.
  * On linux, the script tries the ''vncviewer'', ''krdc'', and ''vinagre'' viewers, in that order. To change the order, i. e., to try ''krdc'' before ''vncviewer'', use ''-v'': \\ ''mycomp> **csovnc.pl -v //viewer// -l //user// //function// **''
  * It is also possible to run the viewer on kilauea with an X window display on your local computer. This is also appropriate if you are at the telescope. \\ ''mycomp> **ssh -X //user//@kilauea.caltech.edu **'' \\ '' kilauea> **csovnc.pl //function//**''


=== Windows ===

  * With Windows, [[windows_vnc|manual]] configuration is necessary. 

==== VNC desktops ====

These are the standard desktops. The port assignments are subject to change. The staff will create the appropriate desktops for the different instruments. 

^  Port  ^  Function  ^ Contents  ^
| 5901 | spectro  | spectrometer displays  |
| 5902 | uip  | [[cso:telescope:uip:uip|UIP]], [[cso:telescope:status]], [[cso:telescope:secondary]], [[cso:telescope:orrery]] |
| 5903 | dsos  | [[cso:telescope:dsos:userproc|DSOS]] monitor, xterms  |
| 5906 | bolocam  | [[cso:telescope:uip:uip|UIP]], [[cso:telescope:status]], [[cso:telescope:orrery]], xterms  |
| 5907 | bolocam.ql  | xterms  |
| 5907 | music.daq  | xterms  |
| 5908 | music  | [[cso:telescope:uip:uip|UIP]], [[cso:telescope:status]], [[cso:telescope:orrery]], xterms  |
| 5909 | music.ql  | xterms  |
| 5911 | sharc  | xterms, Sharc IRC  |
| 5912 | sharc.ql | xterm  |
| 5913 | sharc.fridge  | [[cso:instruments:sharcii:cryo|fridge]] monitor, clock, xterm  |
| 5915 | zspec  | xterms  |
| 5916 | zspec.ql | xterm  |

==== VNC problems ====

On occasion, the VNC server may become unresponsive or otherwise behave incorrectly. For example, the keyboard mapping may get confused so everything appears in CAPITALS. If this occurs: 
  - Press the shift lock key. This may permit typing commands normally. 
  - Toggling the shift lock key and changing window focus several times may restore proper function.
  - Stop the VNC client and disconnect. Then connect again. Observations will not be interrupted by this step.
  - If these steps fail to resolve the problem, recreate the VNC desktop. This will interrupt observations. Please consult the staff if this is necessary.
    * Make a separate ssh login \\ ''mycomp> **ssh //user//@kilauea.caltech.edu**''
    * Stop the existing VNC server \\ ''**csovncserver -kill ://N//**''
    * Create a new VNC server \\ ''**csovncserver -type //function//**''
    * The supported VNC server functions can be listed with \\ ''**csovncserver -help**'' \\ Some functions may not function properly if run from the wrong account.


==== Auxiliary software ====

If you wish, start ''orrery'', ''class'', or other software from a regular ssh login. These programs will display regular X windows on your local computer. These X windows are not persistent and will close if you disconnect.

''mycomp>  **ssh -X //user//@kilauea.caltech.edu** '' \\ \\
''kilauea> **orrery & ** '' \\
''kilauea> **cd data_directory** '' \\
''kilauea> **class ** ''


===== After observing =====

  - Close the shutter: \\ ''__uip__> **shutter /close**''
  - Stow the telescope: \\ ''__uip__> **stow**''
  - Turn off the receiver: \\ ''__uip__> **lo /off**''
  - Exit UIP.
  - Exit from your account but please leave the xterm active.