====== First Login ======

In this exercise you will learn how to login and run commands on our infrastructure.

===== Part I: Login =====

==== Required software ====

As mentioned in the lecture, you absolutely need a //terminal emulator//:

  * on Linux: this can be one of programs Konsole, Gnome Terminal, Terminal, XTerm, ...
  * on Mac OS X/OSX/macOS Sierra: use the pre-installed Terminal application, [[https://www.iterm2.com/|iTerm2]] or the X-Windows terminal from XQuartz (see instructions below)
  * on Windows: use [[http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html|Putty]]

optionally you may want:

  * a X11-Server, to be able to start graphical applications on the server and have the output on your computer:
    * on Linux: it is enough to be logged-in in a graphical environment (Unity, Gnome, KDE, ...)
    * on Mac OS X/OSX/macOS Sierra: you need to install [[https://www.xquartz.org/|XQuartz]]
    * on Microsoft Windows: you need to install [[http://sourceforge.net/projects/xming/files/latest/download|XMing]]
  * a file transfer tool to copy files from/to the server:
    * on Linux: put ''%%sftp://tcopt2.chem.uzh.ch%%'' as the address in your file browser and you should be able to browse your home directory after logging in
    * on Mac OS X/OSX/macOS Sierra: use [[https://cyberduck.io/|Cyberduck]]
    * one Windows: use [[https://winscp.net/|WinSCP]] or [[https://cyberduck.io/|Cyberduck]]
  * a plain text editor to edit input files if you are uncomfortable with using ''vim'', ''nano'' or ''emacs'' via SSH. Please note: It is important that your editor supports Unix line endings. If in doubt, use one of the mentioned editors on the server, or an advanced plain text editor like [[https://atom.io/|Atom]] (plus the [[https://atom.io/packages/line-ending-selector-unix|line-ending-selector-unix]] plugin) or [[https://notepad-plus-plus.org/|Notepad++]] on your local machine.

==== Login using Linux ====

  * Connect to Internet (use VPN when not on the UZH network)
  * Open a terminal (Konsole, xterm or similar)
  * Connect to the server by entering the command: ''ssh -X studentXX@tcopt2.chem.uzh.ch''


==== Login using macOS ====

  * Connect to Internet (use VPN when not on the UZH network)
  * Open a X-Windows terminal in the X11 application if you want to run graphical applications on the server, otherwise use the pre-installed //Terminal// application or an alternative like //iTerm2//
  * Connect to the server by entering the command: ''ssh -X studentXX@tcopt2.chem.uzh.ch''

==== Login using Windows ====

First configure Putty (only required on the first run) as follows:

  - Start the application PuTTY from the Windows menu (in the folder PuTTY)
  - Fill in the //Host Name//: ''tcopt2.chem.uzh.ch''
  - Set //Connection type// to ''SSH''
  - Type ''tcopt2'' as the name of the session below Saved Sessions and save the settings a first time
  - In the Category tree on the left side, select //Connection > Data// and enter the username you have been given in the lecture in the field //Auto-login username//
  - Select the tab ''Connection > SSH > X11'' from the ''Category'' list and enable the option ''Enable X11 Forwarding''
  - Go to //Session// again and 
  - Choose ''Session'' from the ''Category'' list and click ''Save'' again

Then continue as follows to login:

  * Connect to Internet (use VPN when not on the UZH network)
  * Start Xming (optional, only required if you want to run graphical applications on the server)
  * Start Putty
  * Double click the session ''tcopt2'' to start the connection
  * Enter (username and) password as requested


===== Part II: Loading and running a program =====

==== Module loading ====

Since there are numerous applications with different and possibly conflicting requirements, the //module// system is used. This means that only basic commands are available until **explicitly** loaded.

To list all available modules:

<code>
$ module avail
</code>

while using

<code>
$ module list
</code>

gives the list of loaded moules.

To load the CP2K module used in this course, use:

<code>
$ module load cp2k
</code>

When you list the loaded modules again at this point (see command above), you will notice that the list has changed.


Now run the following command to verify that the CP2K executable is available:

<code>
$ cp2k.popt --help
</code>

Which should give you the output

<code>
 cp2k.popt [-c|--check] [-e|--echo] [-h|--help] [--html-manual]
           [-i] <input_file>
           [-mpi-mapping|--mpi-mapping] <method>
           [-o] <output_file>
           [-r|-run] [--xml]

 starts the CP2K program, see <https://www.cp2k.org/>

 The easiest way is cp2k.popt <input_file>

 The following options can be used:

  -i <input_file>   : provides an input file name, if it is the last
                      argument, the -i flag is not needed
  -o <output_file>  : provides an output file name [default: screen]

 These switches skip the simulation, unless [-r|-run] is specified:

  --check, -c       : performs a syntax check of the <input_file>
  --echo, -e        : echos the <input_file>, and make all defaults explicit
                      The input is also checked, but only a failure is reported
  --help, -h        : writes this message
  --html-manual     : writes a HTML reference manual of the CP2K input
                      in the current directory. The file index.html is a good
                      starting point for browsing
  --license         : prints the CP2K license
  --mpi-mapping     : applies a given MPI reordering to CP2K
  --run, -r         : forces a CP2K run regardless of other specified flags
  --version, -v     : prints the CP2K version and the SVN revision number
  --xml             : dumps the whole CP2K input structure as a XML file
                      xml2htm generates a HTML manual from this XML file
</code>

Another program we need for visualization is [[http://www.ks.uiuc.edu/Research/vmd/|VMD]]. Running this remotely is unfortunately error prone which is why you should download it from the link above and install it locally on your machine.

<note tip>The module loading is **not** persistent. You have to reload the modules every time you log back in.</note>


===== Part III: Advanced account configuration =====

==== Make module loading persistent ====

Upon login, the shell (''bash'' in our case) executes a number of files if they exist. One of them is the ''.bashrc''. To prepare it for management using the the ''module'' command, simply execute the following **once**:

<code>
$ echo 'module load ' >> ~/.bashrc
</code>

after that you can add and remove modules to be loaded at startup using ''module initadd'' or ''module initrm''.

To add ''cp2k'', run for example:

<code>
$ module initadd cp2k
</code>

to remove ''cp2k'' again from the list of modules to load:

<code>
$ module initrm cp2k
</code>

Alternatively you can of course simply edit ''.bashrc'' using your favorite editor and add a line like ''module load vmd cp2k'' by yourself.

==== Setup key-based authentication ====

To avoid having to type the password every time you log in (and to increase the security), a public-private key pair can be used for authentication instead. 

=== Instructions for macOS and Linux ===

First generate a key-pair **on your local machine** by running the following in a terminal/shell:

<code>
$ ssh-keygen
</code>

and accept the defaults proposed and do no set a password.

Upload the public key **from your local machine** to tcopt2:

<code>
$ scp ~/.ssh/id_rsa.pub studentXX@tcopt2.chem.uzh.ch:~/
</code>

Now login to ''tcopt2.chem.uzh.ch'' and move the uploaded public key to the right place and set the access permissions correct:

<code>
$ mkdir -p .ssh
$ chmod 0700 .ssh
$ mv id_rsa.pub .ssh/authorized_keys
</code>

When connecting to the server **from your local machine** now, use:

<code>
$ ssh -i ~/.ssh/id_rsa studentXX@tcopt2.chem.uzh.ch
</code>

=== Instructions for Windows using PuTTY ===

First login to the server as above and leave the terminal window open.

Then generate a key-pair **on your local machine** as follows:

  - Start the application //PuTTYgen// which was installed alongside //PuTTY// itself
  - Click on //Generate// to generate a new key (move the mouse to generate randomness, as instructed)
  - Do not set a //Key passphrase//
  - Click on //Save private key// and store the private key as ''condensed_matter.ppk''
  - On the server (in the //PuTTY// terminal window), run the following commands:
    <code>
    $ mkdir -p .ssh
    $ chmod 0700 .ssh
    $ nano -w .ssh/authorized_keys
    </code>
  - Now copy & paste the content in the field //Public key for pasting into OpenSSH authorized_keys file// from //PuTTYgen// into the terminal. Pasting in //PuTTY// is done by a right mouse click.
  - Exit //nano// by using ''CTRL+X'', press ''Y'' to save the file and confirm the name by pressing ''ENTER''
  - Enter ''exit'' to close the connection
  - Close the //PuTTYgen// application

Reconfigure //PuTTY// to use the generate key:

  - Restart //PuTTY//
  - Select the //Session// ''tcopt2'' and press //Load//
  - Select //Connection > SSH > Auth//
  - Use the //Browse...// button in //Authentication parameters// to selected the ''condensed_matter.ppk'' you generated earlier
  - Go back to //Session// and click //Save//, then //Open// to login
  - Now //PuTTY// should directly login (given that you have saved the username as well as described above) without asking for a password

==== Simplify the login ====

The following instructions **apply to OSX and Linux**.

**On your local machine** add the following part to the file ''.ssh/config'' in your home directory:

<code>
Host tcopt2
  HostName tcopt2.chem.uzh.ch
  User studentXX
</code>

after which you will be able to connect to ''tcopt2'' simply by using

<code>
$ ssh tcopt2
</code>

If you have setup key-based authentication as shown above, augment the entry to the following instead, to always use key-based authentication without having to specify ''-i ~/.ssh/id_rsa'' manually:

<code>
Host tcopt2
  HostName tcopt2.chem.uzh.ch
  User studentXX
  IdentityFile ~/.ssh/id_rsa
  IdentitiesOnly yes
  PreferredAuthentications publickey
</code>