====== Remote Access ======

===== ssh, scp =====

<note>**#HUIB: Needs updating if/when other computers are open to the outside as well. In the meantime, mention what the <portal> is.**</note>

To access the Allegro computers from another machine in the Sterrewacht, just use the normal ssh command, with X forwarding if you want to run anything with a GUI or which has other graphical output. E.g. :

<code bash>
ssh [-X] helada
</code>
If you want to access the machines from outside the Sterrewacht, say from your laptop at home, you should ssh in a two-step process: :

<code bash>
ssh -X <username>@<portal>.strw.leidenuniv.nl
ssh -X helada
</code>
You can do this with a single command however:

<code bash>
ssh -tX <username>@<portal>.strw.leidenuniv.nl ssh -tX helada
</code>
You will still have to type your password twice though, unless you have set up password-free operation as described in the following section.

Alternatively you can tunnel to helada, see section ''%%ssh-forwarding%%''.

<note warning>
Some Allegro members are accustomed to use the -Y flag instead of -X. Both flags perform exactly the same function (i.e., they allow you to see graphical output remotely, as well as the standard text-based output), but the -Y flag turns off any security checking. In general this is a bad thing to do. You should use -X by default unless you have a specific problem with this on one of the (nominally at least) trusted Sterrewacht machines.
</note>

==== Quick Login without password ====

In order to allow quick logging into all STRW computers without having to type the passwords all the time, you can use the **ssh-agent**.

=== Preparation ===

To use the quick log in you first have to generate a pair of authentication keys. Simply run: :

<code bash>
$ ssh-keygen
</code>
That command will then ask you where to save the file (hit ENTER for the default directory ''%%~/.ssh%%''). Then you can enter a password (which is optional, but recommended).

You will then have two new files in ''%%~/.ssh%%'':

  * ''%%id_rsa%%'': This is your **private key**. It's permission is set so that only you can see it (''%%-rw-------%%'').
  * ''%%id_rsa.pub%%'': This is your **public key**. That one can also be accessed by others.

In order to have simplified login, you have to add your **public key** to the file ''%%~/.ssh/authorized_keys%%'' by executing this command:

<code bash>
$ cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys
</code>
It should be noted that the ''%%authorized_keys%%'' should have the same permission as the ''%%id_rsa.pub%%''.

To tell the system that you would like to use the simplified login, you have to have an ssh-agent running. This should generally already be the case. You can check:

<code bash>
$ echo $SSH_AGENT_PID
42455
</code>
If not, you should start one by typing:

<code bash>
$ eval `ssh-agent`
</code>
For convenience, you can also add this line to your rc file.

  * **Bash** users can add that line to their ''%%~/.bashrc%%'':<code bash>
[[ -z $SSH_AGENT_PID ]] && eval `ssh-agent | head -2`
</code>
  * **C-Shell** users can add that line to their ''%%~/.cshrc%%'':<code bash>
if ( ! $?SSH_AGENT_PID ) eval `ssh-agent | head -2`
</code>

=== Usage ===

After logging in, you have to hand over the private key to the ssh-agent:

<code bash>
$ ssh-add
</code>
You only have to do that once. You can check if the ssh-agent already has your private key through :

<code bash>
$ ssh-add -L
ssh-rsa fdLKGJLKDGFKLSLLGLKF...
...84ddndkfdfdue8rqF== /home/alma/.ssh/id_rsa
</code>
Or you can remove your key with :

<code bash>
$ ssh-add -D
</code>

<note important>
If you have protected your private key with a password, you have to type it in at the hand-over. But that will only happen once per session.
</note>

===== rsync =====

Rsync'ing to or from the Allegro machines from outside the Sterrewacht has become more complicated since we have had to close off direct SSH access. Any kind of connection now demands a two-hop process: you have to connect first to a non-Allegro Sterrewacht machine, and from there to an Allegro one. This is made immeasurably easier if you have set up password-free SSHing between Sterrewacht machines as described above. In the following instructions I will assume that you have done this.

Your should be able to rsync files from an Allegro computer to, e.g., your laptop at home by running the following command on your laptop:

<code bash>
rsync <options, e.g. -av> -e 'ssh <user name>@<portal>.strw.leidenuniv.nl ssh' <allegro machine>:<source dir> <dest dir>
</code>
Here 'portal' can be any non-Allegro Sterrewacht machine (your desktop is a good choice). Note that, with rsync, it is always a good idea to have a dry run first by including 'n' in the list of options. For example, if I want to rsync some files from <source dir> on helada to <dest dir> on my laptop at home, on the laptop I would type :

<code bash>
rsync -avz -e 'ssh ims@quitor.strw.leidenuniv.nl ssh' helada:<source dir> <dest dir>
</code>
(''%%quitor%%'' is my desktop machine.)

An alternative to this is to set up an ssh tunnel as described in section ''%%ssh-forwarding%%''.

===== VNC =====

VNC stands for Virtual Network Computing. It is a way to access the remote machine in such a way that the normal desktop you would have on that remote machine is displayed on your local one. You can, for example, VNC to helada, set jobs running on helada, close the VNC connection, and shut down your local machine (laptop or whatever); when you later reconnect, you will see all the terminals you opened still there, with the jobs in them still going.

There a description of how to connect with VNC in the [[https://helpdesk.strw.leidenuniv.nl/wiki/doku.php?id=vnc|Sterrewacht documentation]], but additional notes are provided here for the convenience of Allegro members.

<note>**#ALEX/ANDRES: Check with VNCGuide (https://trello.com/c/qWxSMNv0/84-vnc-guide-for-allegro) that information is correct.**</note>

VNC requires a server to be running on helada; you can run a viewer on your local machine to connect with that server. Starting and stopping the viewer doesn't affect the server. You can also (it seems) connect from more than one laptop/viewer to the same server.

==== Set up ====

As described in the Sterrewacht documentation, you need a file ''%%xstartup%%'' in a directory ''%%~/.vnc%%'' with one or two basic setup instructions for the VNC server. The major choice here is which desktop manager to select. On helada there actually aren't many choices. The Sterrewacht example invokes ''%%startkde%%'' which, of course, does what it says on the label. About the only other possibility seems to be gnome. To invoke this, replace the line :

<code bash>
startkde &
</code>
in ''%%xstartup%%'' with :

<code bash>
gnome-session &
</code>

<note important>
It seems that the ''%%xstartup%%'' file needs to be executable - i.e. it should have the ''%%x%%'' in its permissions set.
</note>


==== Server ====

To start up the server, log in to helada. You could then just type :

<code bash>
vncserver
</code>
There are some additional flags you could provide to this command however, which are detailed below, so you may want to read a bit further before you try anything.

As the Sterrewacht documentation describes, the first time you run ''%%vncserver%%'', you'll be asked for a password. I'll refer to this as the VNC password to distinguish it from the normal password you need to access the remote machine.

Each time you run ''%%vncserver%%'', you will be provided with a display number. Example output from the command is as follows: :

<code bash>
$ vncserver

New 'helada.strw.leidenuniv.nl:4 (ims)' desktop is helada.strw.leidenuniv.nl:4

Starting applications specified in /home/ims/.vnc/xstartup
Log file is /home/ims/.vnc/helada.strw.leidenuniv.nl:4.log
</code>
In this case the display number is 4. You'll need to know that in order to connect later with the viewer.

As mentioned already, vncserver can take additional arguments. One handy one is ''%%-geometry%%'', which specifies the size of the desktop you see. An example would be :

<code bash>
vncserver -geometry 1200x700
</code>
If you want to shut the server down again, you can type :

<code bash>
vncserver -kill :<display number>
</code>
where 'display number' in the example above is 4. However if you want the server to shut down automatically when you close the viewer, you can add the argument ''%%-autokill%%'' when you first start it up.

==== Viewer ====

As described in the Sterrewacht documentation, there are several different viewers available for the common operating systems. In all cases however, the viewer must connect with the server via what is called an SSH tunnel. This is necessary because VNC itself does not encrypt its data enough to be secure. For some viewers, it is necessary to set up the tunnel explicitly; for others, the viewer itself will take care of this.

Matters are further complicated these days since we have had to close off direct SSH access to the Allegro machines from outside the Sterrewacht. Any kind of connection now demands a two-hop process: you have to connect first to a non-Allegro Sterrewacht machine, and from there to helada. This is made immeasurably easier if you have set up password-free SSHing between Sterrewacht machines as described above. In the following instructions I will assume that you have done this.

The viewer on the Sterrewacht machines (which run either Fedora and RH6) is just called ''%%vncviewer%%''. On ubuntu, an alternative called ''%%xtightvncviewer%%'' is available and can be installed via the command :

<code bash>
sudo apt-get install xtightvncviewer
</code>
For either of these cases, it is not necessary to set up an explicit SSH tunnel. Just start the viewer by typing :

<code bash>
<viewer name> -via <username>@<portal>.strw.leidenuniv.nl helada:<display number>
</code>
Here 'portal' can be any non-Allegro machine (your desktop is a good choice); and 'display number' in the example above was 4. You will be prompted first for your normal password for the remote machine, then your VNC password.

On a Mac the most popular alternatives (as described on the Sterrewacht wiki) are either to use the native Screen Sharing app or to download 'Chicken of the VNC'. In either case, you will need to set up a tunnel in a terminal before you run the viewer (see section ''%%ssh-forwarding%%'' for how to do this).

After you have opened the tunnel, start up Chicken. You will see a GUI with several entry boxes on the right-hand side. For the top one, 'Host', enter 'localhost'. For 'Display', enter the number of your local display (probably 1). 'Password' is your VNC password, not your Sterrewacht one. That's about it - hit 'connect' and it all should work. Please send a mail to <alma@strw.leidenuniv.nl> if it doesn't.

In all cases, Linux or Mac, just kill the VNC desktop window to exit the viewer.

===== SSH tunneling =====

This is a way to move files directly between the Allegro machines and a computer outside the Sterrewacht. Basically what you are doing is telling SSH to funnel data sent to port A on the external machine (e.g. your laptop at home) to port B on the destination machine (e.g. helada).

The basic command (which you type in a terminal window on the external machine) is :

<code bash>
ssh -L [<external machine IP addr>:]<external port>:helada:<allegro port> <username>@<portal>.strw.leidenuniv.nl
</code>
Let's go through the bits and pieces one by one.

  * The external IP address is optional. If you leave it out, the default is ''%%localhost%%''. This is a Good Thing.
  * The external port in general may be any number between 1024 and 65535 (see next subsection).
  * The port used for ssh connections is usually 22 so you could set the allegro port to that.

An example command for me might look like :

<code bash>
ssh -L 1234:helada:22 ims@quitor.strw.leidenuniv.nl
</code>
'quitor' is a Sterrwacht machine (my desktop). (Other possibilities are borgmeren or bernisse.) This command will give you a prompt on quitor, which you probably didn't want, but it does do the port connection. If in a second window you type :

<code bash>
scp -P 1234 <some file on external machine> ims@helada:<destination directory>
</code>
then the file should be copied without needing to copy it first to the intermediate computer quitor. For rsync you would do in this example (in the second window - leave the first alone now) :

<code bash>
rsync <usual flags> -e 'ssh -p 1234' <source on external> ims@helada:<destination directory>
</code>

==== How to choose port numbers ====

For the 'external' port you need something which is not already in use. Port numbers can go up to 65535. The first 1023 are definitely in use. The best way is just to pick something high and random - if it happens to already be in use, you'll get an error, so then just pick another.

For the 'allegro' port it depends what you want to do. Things like scp, rsync use port 22, so this is the one to choose for that. VNC uses 5900 plus whatever display number will be used (see next section).