[LOS-324] General revision

16f34d47 · Daniel Abad · 057df4ef · 16f34d47 · 16f34d47 · 16f34d47
Commit 16f34d47 authored 5 years ago by Daniel Abad
--- a/docs/distributions/c8.md
+++ b/docs/distributions/c8.md
+# CentOS 8
+Although not released yet officially at CERN, it will be soon the recommended release, so you can already test it. More details:
+<http://linux.web.cern.ch/linux/centos8/>
+We will update this page in due time.
--- a/docs/distributions/cc7.md
+++ b/docs/distributions/cc7.md
@@ -2,17 +2,15 @@
 ## A bit of history
-CERN CentOS 7 was released in 2014 and will be supported until at least July 2024.
+CERN CentOS 7 was released in 2014 and will be supported until July 2024.
 > CERN Community ENTerprise Operating System 7 is the upstream CentOS 7, built to integrate into the CERN computing environment but it is not a site-specific product: all CERN site customisations are optional and can be deactivated for external users.
 In 2015, CERN began migrating away from the Scientific Linux collaboration to provide the next version (RHEL 7 rebuild).
-For more details please check [Next Linux version @ CERN](http://linux.web.ncern.ch/linux/nextversion.shtml).
 ## Default repositories
-Each Red Hat based distribution is shipped with few default repositories.
+Each Red Hat based distribution is shipped with a few default repositories.
 At CERN you can list them with:
@@ -38,7 +36,7 @@ Additional `-release` rpm packages can be searched with `yum search release`.
 !!! Note ""
    Please note that on a puppet managed node the repositories are managed by the `osrepos` module, and repo files stored in an alternative directory `/etc/yum-puppet.repos.d/`.
-Details about the CERN specific repositories.
+Details about the CERN specific repositories:
 ### The `cernonly` repository

--- a/docs/distributions/slc6.md
+++ b/docs/distributions/slc6.md
 # Scientific Linux CERN 6
+!!! danger ""
+    If you are about to start using Linux at CERN, please do not start with SLC6, as its EOL (End Of Life) is forecasted later this year. If you are new, please start straight away with [CC7](cc7.md). For more info: [OTG0054345](https://cern.service-now.com/service-portal/view-outage.do?n=OTG0054345)
 ## A bit of history
 Scientific Linux CERN 6 was released in 2010 and will be supported until at least Decembrer 2020.
@@ -34,7 +37,7 @@ Additional `-release` rpm packages can be found with `yum search release`. On SL
 > Please note that on a puppet managed node the repositories are managed by the `osrepos` module, and repo files stored in an alternative directory `/etc/yum-puppet.repos.d/`.
-Some details regarding CERN specific repositories.
+Some details regarding CERN specific repositories:
 ### The `cernonly` repository

--- a/docs/distributions/supported.md
+++ b/docs/distributions/supported.md
@@ -2,10 +2,14 @@
 At CERN, two distributions are supported:
-* Scientific Linux CERN 6
 * CERN CentOS 7
+* Scientific Linux CERN 6 (Support ending November 2020)
-Scientific Linux and CentOS are derived from Red Hat Enterprise Linux(RHEL), with Red Hat trademarks removed, thus making it freely available.
+And one is coming soon (Q2 2020):
+* CentOS 8
+Scientific Linux and CentOS are derived from Red Hat Enterprise Linux (RHEL), with Red Hat trademarks removed, thus making it freely available.
 Scientific Linux and CentOS deovelopers use Red Hat's source code to create a final product similar to RHEL.
 The distribution content is provided by Red Hat, no update to any existing package is provided by CERN.

--- a/docs/index.md
+++ b/docs/index.md
 # Linux survival kit guide
-Today, the CERN Linux Support team is responsible for over 50,000 (~35,000 in the Data Centre and ~15,000 across the HEP community and user devices).
+Today, the CERN Linux Support team is responsible for over 50,000 devices (~35,000 in the Data Centre and ~15,000 across the HEP community and user devices).
 Maintaining such a large number of devices and providing support is a challenge: hence the need for an end-user training is very important.
 This training has been designed to give an overview of Linux services and also give users an overview of the different technologies provided by the IT Department.
@@ -9,15 +9,26 @@ Finally, users will get a better understanding about our choices around the supp
 A number of links to more specific CERN trainings will be given when necessary.
-The latest version of the training material will always be found at https://cern.ch/linuxtraining/
+The latest version of the training material will always be found at <https://cern.ch/linuxtraining/>
-Slides for the on site training can be found at https://cern.ch/linuxtraining/slides/. Please note that those slides are not needed to follow this guide by yourself.
 ## What this guide will not do
 * This guide will not mention unsupported distributions. It will focus on the newest supported version at CERN: i.e. _CERN CentOS 7_.
+* This guide is not an introduction to Linux. It is focused of CERN-related features (packages, repositories, filesystems, etc.). If you are new to Linux, you might want to check some of the courses available through the LMS course [UDEMY for CERN](https://lms.cern.ch/ekp/servlet/ekp?PX=N&TEACHREVIEW=N&PTX=&CID=EKP000043153&TX=FORMAT1&LANGUAGE_TAG=en&DECORATEPAGE=N), such as:
+    For absolute beginners:
+    * Linux Mastery: Master the Linux Command Line in 11.5 Hours
+    * Learning Linux Essentials: Taking your first steps in Linux
+    For more experienced users:
+    * CentOS 7 Linux Server: Alternative to Red Hat Enterprise
+    * Linux Academy Red Hat Certified Engineer Prep
 * This guide will not explain how to manage machines or services in the datacentre, please check:
-    * The Official training [Tools for IT Service Managers: Getting started](https://lms.cern.ch/ekp/servlet/ekp?PX=N&TEACHREVIEW=N&PTX=&CID=EKP000041103&TX=FORMAT1&LANGUAGE_TAG=en&DECORATEPAGE=N)
    * <https://cern.ch/clouddocs/>
    * <https://cern.ch/configtraining/>
@@ -29,7 +40,7 @@ To learn more about the Linux kernel and detailed software packages, please chec
 ## Changelog and updates
-* Version 2.0 (September 2019)
+* Version 2.0 (February 2020)
  General revision and migration to mkdocs
 * Version 1.0 (November 2018)

--- a/docs/introduction/permissions.md
+++ b/docs/introduction/permissions.md
@@ -26,3 +26,5 @@ Open <https://openstack.cern.ch>
 ## Try to login to the CERNBOX dashboard
 Open <https://cernbox.cern.ch>
+If you can access these three resources without any issue, you are good to go!
--- a/docs/linux/aims2.md
+++ b/docs/linux/aims2.md
@@ -2,44 +2,39 @@
 ## Introduction
-aims2client is the client-side software for communicating with the Linux Automated Installation Management Service (AIMS2). The client is designed to allow you to register and de-register hosts for PXE installation. You can use the client to register your Kickstart file, Anaconda/Kernel append options and the pxeboot target you wish to use for your installation.
+`aims2client` is the client-side software for communicating with the Linux Automated Installation Management Service (AIMS2). The client is designed to allow you to register and de-register hosts for PXE installation. You can use the client to register your Kickstart file, Anaconda/Kernel append options and the pxeboot target you wish to use for your installation.
-The aims2 client also allows you to interact with the pxeboot media library displaying information about already uploaded images or uploading your own pxeboot media.
+The `aims2client` also allows you to interact with the pxeboot media library displaying information about already uploaded images or uploading your own pxeboot media.
 ## Quickstart aims2client
-Please check the manpage for advanced usage.
+Please check the manpage (`man aims2client`) for advanced usage.
 The [installation documentation](http://linux.web.cern.ch/linux/install/#aims) will guide you in details.
 ### List available images
-{% shell %}
+```
-{% prompt "host ", delimiter="$ ", path="~ " %}
+# aims2client showimg \*
-{% command %}
+[...]
-aims2client showimg \*
-{% info %}
 CC72_X86_64                   ,x86_64 ,N   ,CERN CENTOS 7.2 X86_64
 CC73_X86_64                   ,x86_64 ,Y   ,CERN CENTOS 7.3 X86_64
 CC74_X86_64                   ,x86_64 ,Y   ,CERN CENTOS 7.4 X86_64
 CC7_X86_64                    ,x86_64 ,Y   ,CERN CENTOS 7 X86_64 (LATEST)
-...
+[...]
 RHEL_7_3_X86_64               ,x86_64 ,Y   ,RHEL 7 SERVER UPDATE 3 FOR X86_64
 RHEL_7_4_X86_64               ,x86_64 ,Y   ,RHEL 7 SERVER UPDATE 4 FOR X86_64
-...
+[...]
 SLC69_I386                    ,i386   ,N   ,SCIENTIFIC LINUX CERN 6.9 FOR I386 ARCH
 SLC69_X86_64                  ,x86_64 ,Y   ,SCIENTIFIC LINUX CERN 6.9 FOR X86_64 ARCH
 SLC6X_I386                    ,i386   ,N   ,SCIENTIFIC LINUX CERN 6 LATEST FOR I386 ARCH.
+[...]
-{% endshell %}
+```
 ### View image details
-{% shell %}
+```
-{% prompt "host ", delimiter="$ ", path="~ " %}
-{% command %}
 aims2client showimg CC7_X86_64 --all
-{% info %}
 -------------------------------------------------------------------------------
 Image NAME:                CC7_X86_64
 Architecture:              x86_64
@@ -57,23 +52,19 @@ Image OWNER:               toulevey
 Image uploaded at:         2017/11/09 09:40:48
 Synchronized:              Y
 -------------------------------------------------------------------------------
-{% endshell %}
+```
 ### Add a host and install latest CC7
-{% shell %}
+Say you want to configure kost `berries01` to boot automatically and be configured with a kickstart file `myfruit.ks`. You would achieve so by doing:
-{% prompt "host ", delimiter="$ ", path="~ " %}
-{% command %}
+```
 aims2 addhost berries01 --kickstart myfruit.ks
-{% info %}
+```
-{% endshell %}
-{% shell %}
+And setting the Operating System to `CC7_X86_64` as we saw this image (CERN CentOS 7)  was uploaded to AIMS with this name:
-{% prompt "host ", delimiter="$ ", path="~ " %}
+```
-{% command %}
 aims2 pxeon berries01 CC7_X86_64
-{% info %}
+```
-{% endshell %}
-Please note that you kickstart need to contain a [snippet](http://linux.web.cern.ch/linux/centos7/docs/kickstart-example.ks) to deregister the host, so your installation will not loop.
+Please note that you kickstart needs to contain a [snippet](http://linux.web.cern.ch/linux/centos7/docs/kickstart-example.ks) to deregister the host, so your installation will not loop.
--- a/docs/linux/doc.md
+++ b/docs/linux/doc.md
@@ -10,6 +10,7 @@ It contains up-to-date information about the lifecycle of distributions at CERN
 * [SLC6 (Scientific Linux CERN 6)](https://linux.web.cern.ch/linux/scientific6/)
 * [CC7 (CERN CentOS 7)](https://linux.web.cern.ch/linux/centos7/)
+ * [C8 (CentOS 8)](https://linux.web.cern.ch/linux/centos8/)
 [Weekly updates](https://linux.web.cern.ch/linux/) are documented with links to relevant Red Hat reports if available.
@@ -21,9 +22,10 @@ Red Hat provides documentation for every released product :
 * [RHEL6](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/6/)
 * [RHEL7](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/)
+ * [RHEL8](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/)
 The Red Hat documentation is very useful to deep dive in specific parts of the system and is very well organised around topics (Installation, System administration, tuning, etc...)
 ## Linux support tools / open source tools
-All published work is available under our Gitlab organisation: <https://gitlab.cern.ch/linuxsupport>
+All published work is available under our Gitlab organisation: <https://gitlab.cern.ch/linuxsupport>. Do not hesitate to contribute.
--- a/docs/linux/install.md
+++ b/docs/linux/install.md
 # Installation at CERN
-In a first time with the default installation menu, and then unattended with the help of a kickstart and aims2 tool.
 ## Network database
-To be able to install and use a system at CERN you need to first register it in the network database, also called LanDB.
+To be able to install and use a system at CERN you need to first register it in the network database, also called LanDB:
 Open <https://network.cern.ch>
@@ -20,4 +18,4 @@ In this section a CC7 installation will be performed from the network following
 ## Kickstart CC7 installation
-Next section will guide through aims2 and a unattended kickstart installation of a VM.
+Next section will guide through aims2 and a unattended kickstart installation of a VM. This is a more advanced usecase and requires understanding of tools such as Anaconda Kickstart, PXE booting, etc.
--- a/docs/linux/kerberos.md
+++ b/docs/linux/kerberos.md
+# Kerberos
+Please check <http://linux.web.cern.ch/linux/docs/kerberos-access.shtml>
--- a/docs/linux/kickstart.md
+++ b/docs/linux/kickstart.md
 # What is a kickstart ?
-kickstart is the default method to run unattended installations for Red Hat Entreprise linux and derivatives.
+Kickstart is the default method to run unattended installations for Red Hat Entreprise linux and derivatives.
+!!! note "From RHEL documentation:"
+    Using kickstart, a system administrator can create a single file containing the answers to all the questions that would normally be asked during a typical installation.
 Let's install an additional tool:
-{% shell %}
+```
-{% prompt "host ", delimiter="# ", path="~ " %}
-{% command %}
 yum install pykickstart
-{% info %}
+```
-{% endshell %}
 After installing the package, you can validate a Kickstart file using the following command:
-{% shell %}
+```
-{% prompt "host ", delimiter="$ ", path="~ " %}
-{% command %}
 ksvalidator /path/to/kickstart.ks
-{% info %}
+```
-{% endshell %}
-Let review the default CC7 [kickstart](http://linux.web.cern.ch/linux/centos7/docs/kickstart-example.ks):
+The default CC7 [kickstart](http://linux.web.cern.ch/linux/centos7/docs/kickstart-example.ks):
-{% shell %}
+```
-{% prompt "host ", delimiter="$ ", path="~ " %}
-{% command %}
 cat /path/to/kickstart.ks
-{% info %}
 ##############################################################################
 #
 # Example KickStart file for CC7 installations
@@ -210,7 +203,6 @@ shost=`/bin/hostname -s`
 exit 0
 %end
-{% endshell %}
+```
 Default SLC6 kickstart can be found [here](http://linux.web.cern.ch/linux/scientific6/docs/kickstart-example.ks).
--- a/docs/linux/licenses.md
+++ b/docs/linux/licenses.md
@@ -2,12 +2,12 @@
 ## Red Hat Entreprise Linux
-Official webiste: http://linux.web.cern.ch/linux/rhel/
+Official webiste: <http://linux.web.cern.ch/linux/rhel/>
 For offical usage with applications requiring commercial support, CERN purchased a limited number of Red Hat Enterprise Linux Server licenses.
 A license must be requested through this [SNOW form](https://cern.service-now.com/service-portal/report-ticket.do?name=general-request-Linux&se=linux-desktop).
-Registered systems holding valid Red Hat Enterprise Linux license can be installed using same methods as CC7/SLC6.
+Registered systems holding valid Red Hat Enterprise Linux license can be installed using the same methods as CC7/SLC6.
-Red Hat Entreprise Linux repositories are also mirrored internally and a .repo file need to be copied after the installation.
+Red Hat Entreprise Linux repositories are also mirrored internally and a `.repo` file needs to be copied after the installation.
--- a/docs/linux/locmap.md
+++ b/docs/linux/locmap.md
-# Configuring CERN machine
+# Configuring a CERN machine
 ## CC7
-`locmap` (Local Configuration with Masterless Puppet) helps to configure your machine with Linux support puppet modules.
+A tool called `locmap` (Local Configuration with Masterless Puppet) helps to configure your machine with Linux support puppet modules and is installed by default with the CERN supported distributions.
-`locmap` is installed by default.
 ### Usage
 #### Show information about your machine and associated users
-{% shell %}
+```
-{% prompt "host ", delimiter="# ", path="~ " %}
+$ locmap --info
-{% command %}
-locmap --info
-{% info %}
 --------------
 Configuration:
 --------------
@@ -50,16 +45,14 @@ cern_domain:default
 Users:
 ------
 toulevey     IT-CM-LCS      Primary    31  thomas.oulevey@cern.ch
+```
-{% endshell %}
 #### List available modules:
-{% shell %}
+Here you can see all the different modules you can have configured by locmap. For instance, `afs` and `eosclient` will configure the AFS and EOS filesystems so that you can access them from your machine:
-{% prompt "host ", delimiter="# ", path="~ " %}
-{% command %}
+```
-locmap --list
+$ locmap --list
-{% info %}
 [Available Modules]
 afs            [ enabled]
 cernbox        [ enabled]
@@ -72,30 +65,30 @@ ntp            [ enabled]
 sendmail       [ enabled]
 ssh            [ enabled]
 sudo           [ enabled]
-{% endshell %}
+```
-#### Enable and configure module
-{% shell %}
+#### Enable and configure a module
-{% prompt "host ", delimiter="# ", path="~ " %}
-{% command %}
-locmap --enable afs
-{% info %}
+```
+$ locmap --enable afs
 [INFO] module afs enabled.
+```
-{% endshell %}
+Once enabled, we are able to actually configure AFS in our machine:
+```
-{% shell %}
+$ locmap --configure afs
-{% prompt "host ", delimiter="# ", path="~ " %}
-{% command %}
-locmap --configure afs
-{% info %}
 [INFO    ] Please wait while your system is being configured...
 [INFO    ] The run succeeded with no changes or failures; the system was already in the desired state.
-{% endshell %}
+```
+You can check it by listing the contents of your personal folder:
-## SLC6 (SLC5)
+```
+ls /afs/cern.ch/user/u/username/
+```
+(NOTE: Substitute the u for the initial of your username, and username for your actual username)
+## SLC6 (deprecated in November 2020)
 `lcm` (Local Configuration Manager) is the equivalent of `locmap` on SLC6. It is using Quattor components to configure machines.
@@ -105,11 +98,8 @@ locmap --configure afs
 #### List available components:
-{% shell %}
+```
-{% prompt "host ", delimiter="# ", path="~ " %}
+$ lcm --list
-{% command %}
-lcm --list
-{% info %}
 [INFO] LCM version 0.6 started by root at: Mon Nov 12 11:58:03 2018
@@ -126,15 +116,12 @@ afsclt:        yes
 ntpd:          yes
 ocsagent:      yes
 krb5clt:       yes
-{% endshell %}
+```
-#### Configure one of the component
+#### Configure one of the components
-{% shell %}
+```
-{% prompt "host ", delimiter="# ", path="~ " %}
+$ lcm --configure ntpd
-{% command %}
-lcm --configure ntpd
-{% info %}
 [INFO] LCM version 0.6 started by root at: Mon Nov 12 12:01:51 2018
 [INFO] NCM-NCD version 1.2.23 started by root at: Mon Nov 12 12:01:51 2018
@@ -148,5 +135,4 @@ lcm --configure ntpd
 =========================================================
 [OK]   0 errors, 0 warnings executing configure
-{% endshell %}
+```
--- a/docs/linux/support.md
+++ b/docs/linux/support.md
@@ -5,35 +5,27 @@
 Please have the following information available:
  * Hostname of the machine
-  * Running kernel `uname -a`
+  * Running kernel (you can obtain it running `uname -a`)
  * A specific problem description and its severity, that is, its impact on your operations
  * Additional relevant information about the affected systems: attach logs and error messages.
+  * It is not unlikely that Linux Support will ask you to get access to the machine, in that case:
 ## Grant access to the support team
 At CERN, a tool exists to give temporary access to your machine to the support staff.
-{% shell %}
+```
-{% prompt "host ", delimiter="# ", path="~ " %}
-{% command %}
 yum install cern-linuxsupport-access
-{% info %}
+```
-{% endshell %}
 Enable access:
-{% shell %}
+```
-{% prompt "host ", delimiter="# ", path="~ " %}
+cern-linuxsupport-access enable
-{% command %}
+```
-/usr/sbin/cern-linuxsupport-access enable
-{% info %}
-{% endshell %}
 Disable access:
-{% shell %}
+```
-{% prompt "host ", delimiter="# ", path="~ " %}
+cern-linuxsupport-access disable
-{% command %}
+```
-/usr/sbin/cern-linuxsupport-access disable
-{% info %}
-{% endshell %}
--- a/docs/lxplus/introduction.md
+++ b/docs/lxplus/introduction.md
@@ -13,9 +13,15 @@ It will be used extensively during this course.
 ## Lxplus access
-### From linux
+### From Linux
-Most Linux distributions have an ssh client installed.
+Most Linux distributions have an SSH client installed.
+    ssh yourlogin@lxplus.cern.ch
+### From Mac
+Mac has a native SSH client included in the Terminal, so just open it and:
    ssh yourlogin@lxplus.cern.ch

--- a/docs/others/faq.md
+++ b/docs/others/faq.md
@@ -2,21 +2,22 @@
 ## Can you upgrade package X to version Y.Z ?
-As mentioned in the introduction, Scientific Linux and CentOS are a rebuild made from Red Hat Entreprise Linux.
+As mentioned in the introduction, `Scientific Linux` and `CentOS` are rebuilds made from Red Hat Entreprise Linux.
-We therefore do not upgrade package with our own.
+We therefore do not upgrade packages on our own.
-If your package does not exists at all in the offering, we could propose it upstream to EPEL, or in our internal CERN/CERNONLY repository.
+If your package does not exist in the CERN offering, we could propose it upstream to EPEL, or include it in our internal CERN/CERNONLY repository.
 You can contact us for further information.
-## Why should I mirror my software repository on linuxsoft and not use company X repository ?
+## Why should I mirror my software repository on `linuxsoft` and not use `company X` repository ?
-Some company may not exist in 5 years. Many machines at CERN do not have and should not have full Internet access.
+A random company may not exist in 5 years.
-By requesting a mirror, you make sure your deployement will be consitent even if a repository disapear.
+Many machines at CERN do not have and should not have full Internet access.
+By requesting a mirror, you make sure your deployement will be consitent even if a repository disappears.
 ## The version of package X.Y-Z is vulnerable to a security issue.
-Please note that Red Hat backports security fixes on older version, so the package NAME-VERSION-RELEASE is not relevant.
+Please note that Red Hat backports security fixes on older versions, so the package NAME-VERSION-RELEASE is not relevant.
-A better way to check if a CVE has been fixed is to use `rpm -q --changelog <package>` and read/ grep the content.
+A better way to check if a CVE has been fixed is to use `rpm -q --changelog <package>` and read/grep the content.
 ## Why not switching to ubuntu/arch/gentoo/alpine/mint/elementary/fedora/tails/openSUSE ?
-Red Hat derived distributions are the official WLCG distributions and by their longer lifecycle (> 10 years) allow Linux support to provide a effective support to scientists for a full LHC run.
+Red Hat derived distributions are the official WLCG distributions and having a long lifecycle (> 10 years) allows Linux Support to provide a effective support to scientists for a full LHC run.
--- a/docs/pkg/rpm.md
+++ b/docs/pkg/rpm.md
 # Red Hat Package Manager (RPM)
+RPM is a free an open-source package management system. Check [Wikipedia](https://en.wikipedia.org/wiki/RPM_Package_Manager) for a longer description.
 ## Query
-Query all installed packages on your system
+Query all installed packages on your system:
-{% shell %}
-{% prompt "host ", delimiter="# ", path="~ " %}
+```
-{% command %}
+$ rpm -qa
-rpm -qa
+```
-{% info %}
-{% endshell %}
+You might want to grep for a certain string (e.g. "openstack" in this case) to get all related packages:
-Show installed package information
+```
-{% shell %}
+$ rpm -qa | grep openstack
-{% prompt "host ", delimiter="# ", path="~ " %}
+python2-openstacksdk-0.36.1-1.el7.noarch
-{% command %}
+python-openstackclient-lang-4.0.0-1.el7.noarch
+python2-openstackclient-4.0.0-1.el7.noarch
+```
+In order to show information regarding an installed package:
+```
 rpm -qi iptables
-{% info %}
 Name        : iptables
 Version     : 1.4.21
 Release     : 24.1.el7_5
@@ -37,37 +44,28 @@ Description :
 The iptables utility controls the network packet filtering code in the
 Linux kernel. If you need to set up firewalls and/or IP masquerading,
 you should install this package.
-{% endshell %}
+```
-Check installed kernel versions
+Check installed kernel versions:
-{% shell %}
+```
-{% prompt "host ", delimiter="# ", path="~ " %}
+$ rpm -q kernel
-{% command %}
-rpm -q kernel
-{% info %}
 kernel-3.10.0-862.11.6.el7.x86_64
 kernel-3.10.0-862.14.4.el7.x86_64
-{% endshell %}
+```
-Check if a file is part of a package
+Check if a file is part of a package:
-{% shell %}
+```
-{% prompt "host ", delimiter="# ", path="~ " %}
+$ rpm -qf /etc/sysconfig/
-{% command %}
-rpm -qf /etc/sysconfig/
-{% info %}
 iptables-1.4.21-24.1.el7_5.x86_64
-{% endshell %}
+```
 ## Verify
 Verifying a package compares information about the installed files in the package with information about the
 files taken from the package metadata stored in the rpm database.
-{% shell %}
+```
-{% prompt "host ", delimiter="# ", path="~ " %}
+$rpm -V iptables
-{% command %}
-rpm -V iptables
-{% info %}
 ..?......  c /etc/sysconfig/ip6tables-config
 ..?......  c /etc/sysconfig/iptables-config
@@ -81,24 +79,18 @@ Help:
    G Group ownership differs
    T mTime differs
    P caPabilities differ
-    (? in any position : couldn't check)
+```
-{% endshell %}
+This might be useful, for instance, if you want to check whether you have modified some of the default files installed along a package.
 ## Install a single package
-{% shell %}
+```
-{% prompt "host ", delimiter="# ", path="~ " %}
-{% command %}
 rpm -i myrpm.rpm
-{% info %}
+```
-{% endshell %}
 ## Remove a single package
-{% shell %}
+```
-{% prompt "host ", delimiter="# ", path="~ " %}
-{% command %}
 rpm -e myrpm
-{% info %}
+```
-{% endshell %}
--- a/docs/pkg/tools.md
+++ b/docs/pkg/tools.md
@@ -2,68 +2,50 @@
 ## yumdowloader
-`yumdownloader` is part of yum-utils package
+`yumdownloader` is part of the `yum-utils` package:
-{% shell %}
-{% prompt "host ", delimiter="# ", path="~ " %}
+```
-{% command %}
 yum install yum-utils
-{% info %}
+```
-{% endshell %}
 ### Download an rpm
-{% shell %}
+```
-{% prompt "host ", delimiter="# ", path="~ " %}
-{% command %}
 yumdownloader wget
-{% info %}
+```
-{% endshell %}
 ### Download the rpm source package
-{% shell %}
+```
-{% prompt "host ", delimiter="# ", path="~ " %}
-{% command %}
 yumdownloader --source wget
-{% info %}
+```
-{% endshell %}
 ## db_recover
-`db_recover` is part of yum-utils package
+`db_recover` is part of the `libdb-utils` package:
-{% shell %}
-{% prompt "host ", delimiter="# ", path="~ " %}
+```
-{% command %}
 yum install libdb-utils
-{% info %}
+```
-{% endshell %}
 ### Recover the /var/lib/rpm database
-After a crash, recovery of the rpmdb may be needed.
+After a crash, recovery of the rpmdb may be needed:
-{% shell %}
-{% prompt "host ", delimiter="# ", path="~ " %}
+```
-{% command %}
 /usr/bin/db_recover -h /var/lib/rpm
-{% info %}
+```
-{% endshell %}
 ## repoquery
-`repoquery` is part of yum-utils package
+`repoquery` is part of yum-utils package:
-{% shell %}
-{% prompt "host ", delimiter="# ", path="~ " %}
+```
-{% command %}
 yum install yum-utils
-{% info %}
+```
-{% endshell %}
 ### Query a remote repository without installing it
-{% shell %}
+```
-{% prompt "host ", delimiter="# ", path="~ " %}
+repoquery --repofrompath=repotmp,https://linuxsoft.cern.ch/cern/slc5X/x86_64/yum/os/ --repoid=repotmp -qa
-{% command %}
+```
-repoquery  --repofrompath=repotmp,https://linuxsoft.cern.ch/cern/slc5X/x86_64/yum/os/ --repoid=repotmp -qa
-{% info %}
-{% endshell %}
--- a/docs/pkg/yum.md
+++ b/docs/pkg/yum.md
 # Yellowdog Updater Modified (YUM)
-## Clean yum cache
+YUM, similarly to RPM, is a command-line package-management utility. It is different, and better, in that it allows for automatic updates and package and dependency management. Yum works with software repositories that allow for the updates, yet runs RPM underneath.
-YUM uses a cache to speed-up his operations, when you first logs on the machine it is a good idea to clear it.
+## YUM Basics
-{% shell %}
+### Cleaning the  yum cache
-{% prompt "host ", delimiter="# ", path="~ " %}
-{% command %}
+YUM uses a cache to speed-up its operations, it is always a good idea to "clean" whenever you first log in to a machine:
+```
 yum clean all
-{% info %}
+```
-{% endshell %}
-## Query
+### Retrieve information about your packages
-Query packages available on your system
+In order to query packages available on your system:
-{% shell %}
+```
-{% prompt "host ", delimiter="# ", path="~ " %}
-{% command %}
 yum list
-{% info %}
+```
-{% endshell %}
+Check installed kernel versions:
-Check installed kernel versions
+```
-{% shell %}
+$ yum list kernel
-{% prompt "host ", delimiter="# ", path="~ " %}
-{% command %}
-yum list kernel
-{% info %}
 kernel-3.10.0-862.11.6.el7.x86_64
 kernel-3.10.0-862.14.4.el7.x86_64
-{% endshell %}
+```
-Check if a file is part of an available package
+Check if a file is part of an available package:
-{% shell %}
+```
-{% prompt "host ", delimiter="# ", path="~ " %}
-{% command %}
 yum provides /usr/bin/korgac
-{% info %}
 Loaded plugins: changelog, fastestmirror, kernel-module, langpacks, protectbase, tsflags, versionlock
 Loading mirror speeds from cached hostfile
@@ -46,22 +38,75 @@ Loading mirror speeds from cached hostfile
 Repo        : @cr-testing
 Matched from:
 Filename    : /usr/bin/korgac
-{% endshell %}
+```
-## Install a package
+### Install a package
-{% shell %}
+```
-{% prompt "host ", delimiter="# ", path="~ " %}
-{% command %}
 yum install wget
-{% info %}
+```
-{% endshell %}
-## Remove a package
+### Remove a package
-{% shell %}
+```
-{% prompt "host ", delimiter="# ", path="~ " %}
-{% command %}
 yum remove wget
-{% info %}
+```
-{% endshell %}
+### Update all the installed packages in your system
+```
+yum update
+```
+## YUM repositories
+The above commands are very similar to the ones shown in [RPM 101](./rpm.md). However, the true power of yum is managing packages through repositories.
+A repository is a storage location where packages are stored, and thus can be retrieved and installed.
+An example is the [CC7 CERN repository](http://linuxsoft.cern.ch/centos/7/updates/x86_64/Packages/), where one can find all CERN-related packages maintained by us.
+Although the recommended way of configuring software repositories is using puppet (through the [CERN central configuration management service](https://gitlab.cern.ch/ai/it-puppet-module-osrepos/blob/master/code/README.md)) one might need to perform certain operations by hand:
+Check the list of enabled repositories:
+```
+yum repolist
+```
+This will show the enabled repositories that YUM will be aware of in that system. If trying to install a certain package it is not found, you might want to add additional repositories where that packaged might be stored. CentOS default repositories are very minimal as it is a system meant for servers, so for instance not many GUI packages are in the default repositories.
+YUM repositories are just files under `/etc/yum.repos.d` (if your system is not puppet managed), with a similar format:
+```
+cat /etc/yum.repos.d/cernbox.repo
+[cernbox]
+name=CERNBOX2.0 client repository (EOS backend)
+baseurl=http://cernbox.cern.ch/cernbox/doc/Linux/repo/CentOS_7
+enabled=1
+gpgcheck=1
+repo_gpgcheck=0
+gpgkey=http://cernbox.cern.ch/cernbox/doc/Linux/repo/CentOS_7/repodata/repomd.xml.key
+```
+You can also check all configured repositories in your system (even if not enabled) running:
+```
+yum repolist all
+```
+And to enable a repository, you can do it either:
+For the command you are running (temporarily):
+```
+yum --enablerepo=docker-ce-test/x86_64 install docker
+```
+Or permanently editing the corresponding `.repo` file, changing the `enabled=` param to `1`:
+```
+$ cat /etc/yum.repos.d/docker-ce.repo
+[docker-ce-test]
+[...]
+enabled=1
+[...]
+```
--- a/docs/services/containers.md
+++ b/docs/services/containers.md
 # Containers
-Official documentation : http://linux.web.cern.ch/linux/docs/dockerimages.shtml
+Official documentation : <http://linux.web.cern.ch/linux/docs/dockerimages.shtml>
-Linux support provides container, images are updated every 8 weeks.
+Linux support provides container, images are updated on a regularly basis.
 These images are built with koji.
 ## Docker hub
-Official image can be downloaded at https://hub.docker.com/u/cern/
+Official images can be downloaded from <https://hub.docker.com/u/cern/>
 ## CERN gitlab registry
 A local copy in gitlab can be also used:
- * https://gitlab.cern.ch/linuxsupport/slc6-base/container_registry
+ * <https://gitlab.cern.ch/linuxsupport/c8-base/container_registry>
- * https://gitlab.cern.ch/linuxsupport/slc5-base/container_registry
+ * <https://gitlab.cern.ch/linuxsupport/cc7-base/container_registry>
- * https://gitlab.cern.ch/linuxsupport/cc7-base/container_registry
+ * <https://gitlab.cern.ch/linuxsupport/slc6-base/container_registry>