====== How to ask for help ======

===== The Help Desk =====
If you need assistance, please go to [[http://users.chpc.ac.za/helpdesk|the support query page]].  However, before you do that, please ensure that you have crucial information available, and include it in your submission.  It is helpful to ask yourself the following question: "What information do I need to provide to the support agent in order for that person to fully understand my difficulty?"  You can also send emails directly to [[helpdesk@chpc.ac.za]].  Using either method, **please** identify yourself with the same email address as the one used when you registered on the CHPC user portal.  This immediately links your query to your information on our user portal, which makes it easier and faster to provide assistance.

===== Please RTFM (Read The Fine Manual) =====
Before submitting the support request, please take a moment to read whatever relevant documentation is available on [[http://wiki.chpc.ac.za|the CHPC Wiki]].  The Wiki is updated as things change and we become aware of existing difficulties, solutions and workarounds.  Please check back often.

===== Asking for help with login problems =====
CHPC users log into the cluster using the secure shell protocol, or ssh.  However, there are many different software clients that can be used for this purpose, such as command line ssh from Linux, Windows or macOS, or applications such as PuTTY, MobaXterm or WinSSH.  Not all of these provide helpful information when things go wrong.  The command line tools can typically be used with additional parameters to provide helpful information.  For example:
<code>
ssh -v jblogs@lengau.chpc.ac.za
</code>
will provide some additional information and 
<code>
ssh -vv jblogs@lengau.chpc.ac.za
</code>
even more.  Simply saying "I cannot log in" does not enable us to help you.  It could be for one of many reasons, such as:
  - Network problems at the user's end
  - Network problems at the CHPC's end
  - Blocked login due to too many failed attempts
  - Forgotten or mis-typed password
  - A problem with the CHPC's login and authentication system
  - A problem with the user's ssh client software

Here are some things that the user can try:
  - Use a different client
  - Get verbose output, as described above, to try and diagnose the problem
  - Check network connectivity
  - Check ssh login to a totally different site, if possible
  - Try the alternative login node, such as ''scp.chpc.ac.za'', or the CHPC's data transfer node ''dtn.chpc.ac.za''



===== Some hints on resolving your difficulty =====
Here are some things to try:
  * Please look at the example job scripts on the [[http://wiki.chpc.ac.za|Wiki]].
  * PBSPro syntax is not identical to PBS.
  * PBSPro requires you to change to the working directory with a ''cd'' command.  There is no -d option.
  * Use ldd to check if the executable can link to the correct libraries.  If it cannot find the libraries, it may be necessary to load the required modules.
  * The environment variables $PBS_O_WORKDIR, $PBS_WORKDIR nor $PBS_JOBDIR may not automatically know what your working directory is.  If you do not set these explicitly, they may have no values.  When in doubt, check.
  * Please put some effort into estimating and requesting a realistic Walltime.  If you ask for much more than you really need, the scheduler will have to wait longer in order to find a large enough gap.
  * Please try repeat a previous calculation which actually worked - please make sure to keep a backup of this previous calculation (please do not overwrite your old results).
  * Please confirm you are submitting to the appropriate queue. Possible queues: http://wiki.chpc.ac.za/quick:start?s[]=smp#queues
  * The error messages in your code's output and the standard error file are very helpful. The first instance of the error or warning is often the most significant one.

===== Information to include in your support query =====
Please include the following information where relevant:
  * **Your CHPC login name**
  * Your affiliation (company, university, institute, etc.)
  * A one-line summary of the project that you are working on
  * **The software that you are using**
  * **The PBS job number of the failed job**
  * **The directory in which your troublesome project is located**
  * **The name of your submit script**
  * **As much relevant error output as you can find**
  * The language in which the code was written
  * The compiler used
  * Which MPI is being used? (OpenMPI, MPICH2, etc ....)
  * Are you using thread-level parallelisation such as OpenMP?
  * Which modules are you loading?
  * When was the code last compiled?
  * Does the code work properly on a single workstation or cluster node?
  * Has it worked before on distributed parallel?
  * Any other relevant information

===== Enabling CHPC staff to log in as you and run jobs =====

Sometimes the only way issues can be resolved is to have someone log in as you.

**Never** give anyone else your password.

What you **can** do is add their ssh keys to your account - which you can remove later. See [[quick:addingkeys|adding ssh keys]] to use this.