Merge pull request #296 from hscheid/master

Extend documentation. Add certificates and services.

Author: ddobrigk

docs/gettingstarted/README.md

@@ -5,7 +5,44 @@ title: Getting started
 
 # Getting started
 
-Welcome to the first steps of the analysis framework documentation! Here's a
-list of topics to get you going:
+Welcome to the first steps of the analysis framework documentation!
+
+Let's start with some basics.
+
+## Are you a registered ALICE member?
+Use [this link](https://alisw.cern.ch/check) to check if your CERN account is connected to ALICE. In case you see a message saying that you are not an ALICE member, you need to fix the problem: many services are not accessible if you are not considered an ALICE member.
+
+Drop an email to the ALICE Secretariat, they will help you: <[email protected]>
+
+## Do you have access to lxplus?
+When you have a CERN account you can typically login to lxplus via SSH:
+```bash
+ssh [email protected]
+```
+If, in spite of providing the correct password, you are not allowed to connect, go on your [CERN account management page](https://cern.ch/account). You need to **Sign in** and to select **Resources and Services** like in the picture below:
+
+
+<div align="center">
+<img alt="resources and services" src="../images/ResAndServices.png" width="35%">
+</div>
+
+Then click the big **List Services** button and check if the following services are enabled for you:
+
+<div align="center">
+<img alt="screenshot of services" src="../images/ListOfServices.png" width="35%">
+</div>
+
+You need:
+* LXPLUS and Linux
+* AFS Workspaces
+* EOS/CERNBox
+
+In case some of them are missing, just click on the service to subscribe. For Linux, you may be requested to provide a "group" and a "reason" for requesting the subscription.
+
+* **Group**: `z2` (it corresponds to ALICE)
+* **Reason**: just type something like "new ALICE member", it's enough
+It will take at least two full working hours before you will be able to use the services
+
+Here's a list of further topics that will get you going with our software:
 
 {% include list.liquid all=true %}

docs/gettingstarted/certificate.md

@@ -0,0 +1,99 @@
+---
+sort: 2
+title: Getting a GRID certificate
+---
+
+# Getting a GRID certificate
+
+We will illustrate how to get, renew, register and prepare your digital certificates to use the ALICE Grid services.
+
+## Obtain a digital certificate
+
+Your home institute may provide you with a digital certificate. However, we reccommend you get one from CERN, because the procedure is very easy and automated when you have a CERN account.
+
+* [Generate a new CERN Grid User certificate](https://ca.cern.ch/ca/user/Request.aspx?template=EE2User)
+
+You will be asked whether you want to protect your certificate with a password. Note that in most cases you will not be allowed to import the certificate if you don't specify a password, so please protect it with a password.
+
+**This is not your CERN password. Use a new, arbitrary one.**
+
+Proceed until you get a message saying that your certificate is ready to be downloaded: click on it and a file called `myCertificate.p12` will be downloaded.
+
+## Register your certificate in your browser
+
+There are several ways to add your newly downloaded certificate to your browser, and they depend on the browser and the operating system. We will focus on Firefox as an example.
+
+Open Firefox, go to the **Preferences**, select **Privacy and security** on the left hand menu. Scroll the settings page to the bottom and click on the **Show certificates...** button.
+
+A new window will open: click the **Personal certificates** tab. Click **Import...** and select the `myCertificate.p12` file you have just generated. Type the password you have used in the previous step (this is not your CERN password).
+
+Your newly imported certificate will appear in the list.
+
+## Add the CERN Grid certificates to your browser
+
+In case you navigate to an ALICE HTTPS site and you get a security warning, it is probably because your browser does not have any means to recognize the site as valid.
+
+*Most people ignore security exceptions. **Do not do that, ever.** This is bad, very bad. Someone can steal your data. For real. Without you knowing it.*
+
+Go to [this site](https://cafiles.cern.ch/cafiles/certificates/Grid.aspx), there are two links at the bottom of the page saying "CERN Root/Grid Certification Authority", etc.: with Firefox as your browser, click on both of them, and Firefox will ask you if you want to "trust" them: say "yes" to all questions.
+
+## Test your browser setup
+
+Navigate to the [ALICE Grid monitoring](https://alimonitor.cern.ch/) page. If you have your personal certificate installed, and the CERN Grid certificates installed as well, Firefox should ask you to select a certificate to be used to authenticate to the site.
+
+In case you have many, select the one that identifies you (it should have your full name somewhere) issued by the CERN Grid Certification Authority, and tell Firefox to remember it.
+
+You should be able to see the page without further ado. Next to the address bar, a green lock icon should appear. If you see broken locks, red icons, warnings of various kinds, then there is some kind of security problem and you should repeat the steps above.
+
+## Register your certificate to the ALICE Grid
+
+This operation needs to be performed only once. With Firefox, click on [this link](https://alien.web.cern.ch/content/register-alice-virtual-organization) and follow the guided procedure, after having selected your personal certificate for authenticating.
+
+## Convert your certificate for using the Grid tools
+
+Keep at hand the `myCertificate.p12` file you have previously downloaded. You need to convert it into two files (a "certificate" and a "key") in order to use the ALICE Grid services from the command line.
+
+You will export your certificates to the following directory:
+```bash
+~/.globus
+```
+
+Now export the certificate with the following command (you will be prompted for the export password you have selected when you have generated it):
+```bash
+openssl pkcs12 -clcerts -nokeys -in ~/Downloads/myCertificate.p12 -out ~/.globus/usercert.pem
+```
+
+The result will be a file called `usercert.pem` in your `~/.globus` directory. Note that your input file ending with `.p12` may have a different name and may be stored in a different location.
+
+Time to export the **private key**:
+```bash
+openssl pkcs12 -nocerts -in ~/Downloads/myCertificate.p12 -out ~/.globus/userkey.pem
+chmod 0400 ~/.globus/userkey.pem
+```
+When it says:
+```bash
+Enter Import Password:
+```
+you should provide it with the export password you have entered when you generated it. The next question will be:
+```bash
+Enter PEM pass phrase:
+```
+You should provide it with another password that will be used to protect the private key. You can use the same password as before if you want, but please **do not use your CERN password** (yes, we are stressing this point a **lot**). This question will be asked twice for confirmation.
+
+## Test your certificate
+
+Your certificate will be available to the ALICE Grid command line client.
+
+Enter your ALICE environment and create a "temporary access token":
+```bash
+alienv enter O2Physics/latest
+alien-token-destroy
+alien-token-init YOUR_ALIEN_USERNAME
+```
+
+This assumes you have completed your [installation](https://aliceo2group.github.io/analysis-framework/docs/gettingstarted/installing.html). You do not have either `alienv` or the `alien-token-*` commands available in case you have never done it.
+
+The `alien-token-init` command will ask you for a password. This is the last password you have used when you have converted your `.p12` certificate into two `.pem` files.
+
+### Creating JAliEn and AliEn tokens
+Note that the new JAliEn Grid clients automatically create tokens, while AliEn-ROOT-Legacy (ROOT5) requires running alien-token-init manually. There is alien-token-init for JAliEn, and you can use it to test your credentials or (re)create tokens manually.

docs/gettingstarted/contributingtocode.md

@@ -1,5 +1,5 @@
 ---
-sort: 5
+sort: 6
 title: Contributing to the repository
 ---
 

docs/gettingstarted/contributingtodocs.md

@@ -1,5 +1,5 @@
 ---
-sort: 6
+sort: 7
 title: Editing this documentation
 ---
 

docs/gettingstarted/gitbasics.md

@@ -1,5 +1,5 @@
 ---
-sort: 4
+sort: 5
 title: Git basics
 ---
 

docs/gettingstarted/installing.md

@@ -1,5 +1,5 @@
 ---
-sort: 2
+sort: 3
 title: Installing O2 and O2Physics
 ---
 
@@ -56,7 +56,7 @@ enabled=1
 gpgcheck=0
 EOF
 yum update -y
-yum install -y alice-o2-full-deps 
+yum install -y alice-o2-full-deps
 yum update -y
 yum install -y alibuild
 ```
@@ -162,7 +162,7 @@ sudo apt install -y curl libcurl4-gnutls-dev build-essential gfortran libmysqlcl
 AliBuild, our build tool, is installed as a standard ubuntu package, provided you enable the alisw PPA repository. This is done with:
 
 ```bash
-sudo add-apt-repository ppa:alisw/ppa  
+sudo add-apt-repository ppa:alisw/ppa
 sudo apt update
 sudo apt install python3-alibuild
 ```

docs/gettingstarted/theo2physicsrepo.md

@@ -1,5 +1,5 @@
 ---
-sort: 3
+sort: 4
 title: The O2Physics repository structure
 ---