Hi ha una habilitat que separa l'administrador que resol incidències del que les escala: no necessitar internet per saber què fa una ordre. Linux ve amb la seva pròpia documentació instal·lada, escrita per qui va desenvolupar cada eina, actualitzada amb la versió exacta que tens al davant i disponible encara que el servidor estigui aïllat en una xarxa sense sortida.

Aquesta última part no és un supòsit teòric. Un servidor de producció ben configurat sol estar darrere d'un tallafocs que no permet navegació. Un entorn bancari o sanitari pot ser en una xarxa completament separada. I quan hi ha una incidència greu, el primer que es talla és l'accés extern. Si el teu mètode de treball és «ho busco», en aquell moment et quedes sense mètode.

Aquesta lliçó t'ensenya el mètode alternatiu. En acabar-la sabràs llegir una pàgina de manual sencera —inclosa aquella notació amb claudàtors i barres que sembla jeroglífica—, buscar una ordre quan no en recordes el nom, i saber en quina de les cinc fonts de documentació diferents hi ha la resposta que necessites. És, probablement, la lliçó més rendible del mòdul.

1. Les cinc fonts de documentació d'un sistema Linux
2. man: el manual del sistema
3. Com es llegeix la notació del SYNOPSIS
4. Les seccions del manual i per què existeixen
5. Buscar al manual: whatis, apropos i man -k
6. Navegar amb less dins de man
7. --help: el resum ràpid
8. info: la documentació extensa de GNU
9. help: els builtins de Bash i per què man cd no funciona
10. Documentació local a /usr/share/doc
11. tldr i cheat: el complement, no el substitut
12. Codis de sortida i $?: saber si alguna cosa ha fallat
13. Estratègia de cerca quan no en saps ni el nom

Abans d'entrar en detall, el mapa. A srv-tramontana conviuen cinc fonts diferents, i triar malament et fa perdre temps:

I una sisena, opcional, que cal situar bé: tldr, que dona exemples pràctics però no és documentació oficial i no és exhaustiva.

La regla operativa: --help per recordar, man per entendre, info per aprofundir, /usr/share/doc per configurar.

man (de manual) mostra la pàgina de documentació oficial d'una ordre, un fitxer de configuració, una crida al sistema o un format de fitxer.

S'obre a pantalla completa en un paginador. Se'n surt amb q.

Les pàgines de manual segueixen una estructura estandarditzada des dels anys setanta. Conèixer-la et permet saltar directament al que busques en comptes de llegir de dalt a baix:

Dos consells que canvien com es fa servir man:

• Comença per EXAMPLES si existeix. No totes les pàgines el tenen (les de GNU solen no tenir-lo), però quan hi és, resol el dubte en trenta segons.
• Acaba per SEE ALSO quan t'has equivocat d'ordre. És la llista d'eines relacionades escrita per qui millor coneix el domini.

Un exemple real de lectura selectiva. Necessites saber quins fitxers fa servir el servei SSH:

A dins, prems /FILES i Enter: saltes directament a la llista de fitxers, sense llegir les tres-centes línies anteriors. Tornarem a aquesta tècnica a l'apartat 6.

El SYNOPSIS és la part que més gent es salta i la que més informació conté. Està escrit en una notació formal amb regles fixes:

Vegem-ho aplicat. El SYNOPSIS de cp:

Aquesta pàgina t'està dient tres coses que no apareixen escrites en prosa enlloc:

1. Hi ha tres formes vàlides d'invocar cp, no una. Cada línia és una forma completa.
2. A la primera, SOURCE i DEST van sense claudàtors: són obligatoris. cp sense arguments falla.
3. A la segona, SOURCE... porta punts suspensius i l'últim argument s'anomena DIRECTORY: pots copiar diversos fitxers de cop, però llavors el destí ha de ser un directori. Això explica un error que veuràs a la lliçó 02-04.

Un altre exemple, man 5 crontab enfront de man 1 crontab:

Aquí [-l | -r | -e] et diu que llistar, esborrar i editar són excloents: no pots demanar-ne dues alhora. Hi ha tota la lògica de l'ordre en una línia.

Exercici mental que t'hauries de fer sempre: abans de llegir OPTIONS, llegeix el SYNOPSIS i pregunta't quantes formes d'invocació hi ha i què és obligatori. Moltes vegades la resposta ja hi és.

El manual està dividit en vuit seccions numerades. La raó és que un mateix nom pot referir-se a coses diferents: passwd és una ordre i un fitxer de configuració; printf és una ordre i una funció de C.

Les tres que faràs servir constantment com a administrador són la 1 (ordres), la 5 (fitxers de configuració) i la 8 (eines de root).

Quan executes man passwd sense número, man et dona la primera secció on trobi aquesta pàgina, normalment la 1:

Però si el que vols és entendre el format del fitxer /etc/passwd, aquesta és una altra pàgina completament diferent:

La capçalera et diu sempre en quina secció ets: PASSWD(1) enfront de PASSWD(5). Acostuma't a mirar aquest número: és la manera de saber si estàs llegint la pàgina correcta.

Per saber en quines seccions existeix una pàgina:

man -a te les mostra totes en seqüència: en sortir d'una amb q, pregunta si vols veure la següent.

Dues pàgines de la secció 7 que val la pena que coneguis ja:

Aquestes dues eines resolen les dues preguntes més freqüents.

«Què és aquesta ordre que acabo de veure en un script?» → whatis (equivalent a man -f), que mostra només la línia NAME:

«No sé com es diu l'ordre que necessito» → apropos (equivalent a man -k), que busca la paraula a les descripcions de totes les pàgines instal·lades:

En tres segons, sense cercador, tens les tres eines que existeixen per al problema. Aquesta és la resposta a la crítica de «la CLI no és descobrible» de l'apartat 1 de la lliçó anterior: sí que ho és, però es descobreix amb apropos, no amb menús.

Quan la cerca retorna massa coses, s'afina:

-s 8 restringeix a la secció d'administració. També pots limitar la cerca al nom en comptes de a la descripció:

-e força coincidència exacta, útil perquè apropos tar retornaria desenes de pàgines que contenen «tar» dins d'altres paraules.

Si apropos respon nothing appropriate, pot ser que la base de dades d'índexs no estigui generada. Es regenera amb:

man no dibuixa res per si mateix: envia el text a un paginador, que a Ubuntu és less. Les dreceres que aprenguis aquí valen també per veure fitxers i registres (lliçó 02-05), així que són doblement rendibles.

El flux de treball real d'algú amb experiència no és llegir la pàgina: és entrar i buscar.

Suposa que vols saber què fa l'opció -h de du. En comptes de recórrer la pàgina:

A dins, escriu /-h i Enter. less salta a la primera aparició; amb n avances fins a la que és a la secció OPTIONS:

Truc molt útil: per buscar una opció concreta i evitar les desenes d'aparicions soltes d'aquella lletra, busca el patró amb espais:

El ^ significa «al principi de línia» i les pàgines de manual sagnen les opcions, així que això salta directament a la seva definició. (Aquell ^ és una expressió regular; el tema complet és de la lliçó 03-02, però aquest ús solt el pots adoptar ja.)

I un advertiment pràctic: si ets dins de man i no saps com sortir-ne, és q. És la pregunta més freqüent de tot el curs.

Gairebé totes les ordres accepten --help (o -h) i responen amb un resum al terminal mateix, sense paginador:

Diferències amb man:

Aquest últim punt té una conseqüència pràctica: en un contenidor Docker minimalista (Mòdul 7) no sol haver-hi pàgines de manual instal·lades, perquè s'eliminen per reduir la mida de la imatge. Allà --help és l'únic que tens.

Compte amb un detall: en algunes ordres, -h no significa «ajuda». A ls, du i df significa human-readable. Si dubtes, fes servir --help, que és inequívoc.

I un altre: quan la sortida de --help no cap a la pantalla, no la persegueixis cap amunt. Envia-la al paginador:

Aquell | és una canonada; s'explica a fons a la lliçó 03-04, però aquest ús el pots adoptar des d'avui.

El projecte GNU va decidir en el seu moment que les pàgines de manual eren massa limitades per documentar les seves eines i va crear el seu propi sistema: Texinfo, que es consulta amb info. Està organitzat en nodes enllaçats, com un llibre amb capítols navegables.

Conseqüència pràctica que cal conèixer: a les eines GNU (ls, cp, mv, tar, grep, sed...), la pàgina de manual és sovint un resum i la documentació real és a info. Moltes pàgines acaben amb una nota explícita:

Navegació bàsica d'info:

Quan val la pena info: quan man et dona l'opció però no el perquè. Per exemple, per entendre el comportament exacte de cp amb enllaços simbòlics, o els formats de date, info explica els casos límit que man només enumera.

Si info et resulta incòmode (li passa a molta gent per la navegació amb nodes), tens una sortida:

Així llegeixes el mateix contingut a less, amb les dreceres que ja coneixes.

Prova això:

L'explicació és a la lliçó anterior: cd no és un programa, és una ordre interna de Bash. No hi ha cap paquet que l'instal·li, així que no hi ha cap pàgina de manual que el documenti. La seva documentació la proporciona el mateix Bash amb el builtin help:

I la llista completa de builtins, que convé mirar un cop a la vida:

L'arbre de decisió complet:

Hi ha un cas intermedi que convé conèixer: man builtins mostra tots els builtins documentats en una sola pàgina, i man bash conté la documentació completa del shell. És una de les pàgines de manual més llargues del sistema (més de cinc mil línies), i per això mateix /paraula és imprescindible allà dins.

Cada paquet instal·lat deixa documentació a /usr/share/doc/<paquet>/. És la font que més s'ignora i la que més vegades conté exactament el que necessites: fitxers de configuració d'exemple.

Què esperar en cada tipus de fitxer:

Molts estan comprimits en .gz. Es llegeixen sense descomprimir-los amb zless o zcat:

README.Debian és especialment valuós perquè documenta les diferències entre l'eina original i com l'empaqueta Ubuntu: rutes canviades, opcions per defecte diferents, integració amb systemd. Això no apareix a la documentació oficial del projecte i és la causa de la meitat de les confusions quan segueixes un tutorial escrit per a una altra distribució.

Quan arribis a configurar serveis al Mòdul 5 i al Mòdul 8, aquesta carpeta serà la teva primera parada abans que qualsevol tutorial.

tldr (de too long; didn't read) és una col·lecció comunitària d'exemples pràctics. On man tar et dona mil línies, tldr tar et dona les sis invocacions que es fan servir el 95 % de les vegades.

És enormement útil, i cal ser conscient dels seus tres límits:

1. No és exhaustiu. Mostra el que és comú, no el que necessites en un cas rar. I els casos rars són precisament les incidències.
2. No és oficial. L'escriu la comunitat; pot estar desactualitzat respecte a la teva versió.
3. Pot no estar instal·lat, i en un servidor de producció és probable que no ho estigui (i que no l'hi hagis d'instal·lar només per això).

Criteri professional: tldr per arrencar ràpid amb una eina que ja entens; man per decidir alguna cosa que va a producció. Si has d'executar una ordre destructiva o modificar la configuració d'un servei en marxa, la font és el manual.

Recorda de l'apartat 9 de la lliçó anterior: tota ordre retorna un número en acabar. Ara ho mirarem directament, perquè és la informació que et diu si alguna cosa ha funcionat quan l'ordre no ha dit res.

$? guarda el codi de l'última ordre executada. Convenció universal:

Cada ordre pot definir els seus, i aquí és on entra la secció EXIT STATUS del manual:

Buscant /EXIT STATUS:

Això significa que a grep, 1 no és una fallada: significa «no hi ha coincidències». Confondre «no ha trobat res» amb «s'ha trencat» és una font clàssica d'errors en scripts de monitoratge. I l'única manera de saber-ho és llegint aquesta secció del manual.

Compte amb un parany: $? es reescriu amb cada ordre, inclòs l'echo que el mostra.

El segon 0 és el codi de l'echo anterior, que va funcionar perfectament. Consulta $? immediatament, o desa'l en una variable (Mòdul 4).

Aquest és el procediment complet, ordenat, per quan t'enfrontes a un problema sense saber quina eina el resol:

1. Descriu el problema en dues o tres paraules en anglès. «space», «compress», «rename», «monitor processes».
2. apropos amb aquestes paraules, acotant amb -s 1 o -s 8.
3. De la llista, whatis sobre els candidats per descartar ràpid.
4. man sobre el triat: llegeix NAME, SYNOPSIS i salta a EXAMPLES.
5. Si no era el correcte, SEE ALSO d'aquella pàgina sol contenir el que sí que ho és.
6. Si l'ordre existeix però no la saps fer servir, tldr per a una arrencada ràpida, i tornada al manual per als detalls.
7. Si és un fitxer de configuració, man 5 <nom> i /usr/share/doc/<paquet>/examples/.
8. Si és una ordre que no té manual, type et dirà si és un builtin i llavors help.

Un recorregut complet. La Marta Vidal pregunta quant ocupa el directori de l'aplicació:

Dins del manual, /summarize:

I /human:

Resultat, sense sortir del servidor i sense cercador:

Tres ordres i dues cerques dins d'una pàgina. Aquest és el mètode.

No saber sortir de man. És q. Si ets a info, també q. Si has entrat a vim per accident, és :q! (lliçó 02-05).

Llegir la pàgina sencera de dalt a baix. Les pàgines de manual són referència, no tutorials. Entra i busca amb /.

Ignorar el número de secció. Si man passwd et parla de canviar contrasenyes i tu buscaves el format del fitxer, no és que el manual estigui malament: et falta el 5.

Buscar a internet abans que a apropos. El cercador et donarà una resposta escrita per a una altra distribució, una altra versió i un altre any. man documenta exactament el binari que tens instal·lat.

Copiar una ordre d'un fòrum sense llegir-ne les opcions. Abans d'executar alguna cosa que no entens, passa-li les opcions per man. És literalment un minut, i és la diferència entre resoldre una incidència i provocar-ne una altra.

Consell: man -k és el teu cercador local. Acostuma't a provar-lo abans d'obrir el navegador. La primera setmana et semblarà més lent; a partir de la tercera aniràs més ràpid.

Consell: guarda el que aprens. Crea /home/operador/scripts/notes/ i escriu-hi les ordres que has hagut de buscar. La teva pròpia documentació, amb els teus casos, és més ràpida de consultar que qualsevol manual.

Consell: llegeix man 7 hier un cop. És l'FHS del Mòdul 1 explicat pel sistema mateix. Mitja hora ben invertida.

Consell: en un servidor sense pàgines de manual, comprova si estan desactivades abans de donar-les per perdudes. Algunes imatges les exclouen a la configuració d'instal·lació de paquets; com es recuperen és matèria de la lliçó 05-03.

Sense executar les ordres, només llegint-ne les pàgines de manual, respon:

1. mkdir accepta crear diversos directoris en una sola ordre? Com ho saps pel SYNOPSIS?
2. Quantes formes diferents d'invocació té ln?
3. A man 1 tar, són -c, -x i -t compatibles entre si?

En Luis t'escriu: «Necessito quedar-me només amb les últimes 50 línies de /var/log/tramontana/acces.log i no me'n recordo, de l'ordre. A més vull veure-ho actualitzant-se en directe mentre provo l'aplicació. Me'l busques al Google?»

Restricció: srv-tramontana és en una xarxa sense sortida a internet. Resol-ho fent servir només documentació del sistema, i documenta el camí que has seguit (quines ordres de cerca has fet servir i en quin ordre).

La Marta Vidal vol saber què fa exactament la línia 0 3 * * * /home/operador/scripts/backup.sh que apareix a la configuració de tasques programades del servidor anterior, i si el format és fiable.

Fent servir només el manual del sistema, esbrina:

1. En quina secció del manual està documentat el format d'aquell fitxer (no l'ordre).
2. Què significa cadascun dels cinc camps.
3. Quin codi de sortida retorna l'ordre crontab si el fitxer té un error de sintaxi.

Escriu la resposta com un paràgraf breu adreçat a la Marta, que no és tècnica.

Solució 1

Sí que n'accepta diversos. La prova són els punts suspensius després de DIRECTORY: signifiquen «un o més». I com que DIRECTORY va sense claudàtors, almenys un és obligatori. Tota aquesta informació és en una sola línia, sense llegir ni una paraula de prosa.

Quatre formes. Fixa't en la segona: ln TARGET sense nom d'enllaç. Crea l'enllaç al directori actual amb el mateix nom que l'objectiu. És un detall que sorprèn i que només s'aprèn llegint el SYNOPSIS. El faràs servir a la lliçó 02-06.

Estan agrupades sota l'epígraf «Operation mode» (mode d'operació), cosa que indica que se n'elegeix un i només un. La pàgina ho confirma més amunt:

No són compatibles. Intentar tar -cx dona un error del tipus «You may not specify more than one -Acdtrux option». La pista era a l'organització de la pàgina mateixa: quan un manual agrupa opcions sota un epígraf de «mode», solen ser excloents.

Solució 2

Camí seguit.

Primer, buscar al manual per concepte:

Confirmar que és el que sembla:

Anar al manual i buscar-hi dins com fixar el nombre de línies. Dins de man tail, /lines:

I per a la segona part, la de seguir el fitxer en directe, /follow:

Les dues ordres que resolen la petició d'en Luis:

Se surt del mode seguiment amb Ctrl+C.

El matís que aporta la documentació i que no hauria donat una resposta ràpida de cercador: la diferència entre -f i -F. -f segueix el descriptor del fitxer; si logrotate rota el registre a mitjanit i en crea un de nou, tail -f es queda mirant el fitxer antic, ja reanomenat, i deixa de mostrar res sense avisar. -F segueix el nom, així que es reenganxa amb el fitxer nou.

Per seguir un registre de producció que rota, l'opció correcta és tail -F. Això és literalment a la pàgina de manual, i és exactament el tipus de detall que un tutorial de tres línies omet. Hi tornarem a la lliçó 02-05.

El que li contestes a en Luis no és l'ordre: és el mètode. apropos amb dues paraules en anglès, whatis per confirmar i /opció dins del manual. Trenta segons, sense internet.

Solució 3

1. Secció del manual. L'ordre crontab és a la secció 1, però el format del fitxer és a la 5:

2. Els cinc camps. Dins de la pàgina, buscant /field:

Aplicat a 0 3 * * *: minut 0, hora 3, qualsevol dia del mes, qualsevol mes, qualsevol dia de la setmana. És a dir, tots els dies a les 3:00.

3. Codi de sortida davant d'un error de sintaxi. A man 1 crontab, buscant /EXIT:

I a la secció DIAGNOSTICS de la mateixa pàgina s'explica que un fitxer amb errors de sintaxi és rebutjat completament: crontab no instal·la una versió parcial. Aquest matís és l'important per a la Marta, i només apareix llegint la pàgina.

Informe per a la Marta:

Marta, la línia 0 3 * * * /home/operador/scripts/backup.sh és una tasca programada del sistema. Els cinc primers valors són un rellotge: minut 0, hora 3, i els tres asteriscs signifiquen «qualsevol dia, qualsevol mes, qualsevol dia de la setmana». En conjunt: l'script de còpia de seguretat s'executa automàticament cada dia a les 3:00 de la matinada.

Sobre la fiabilitat del format: és l'estàndard d'Unix, fa més de quaranta anys que s'utilitza i està documentat al sistema mateix. Quan s'instal·la una tasca, el programa valida la sintaxi i rebutja el fitxer sencer si hi ha un error, en comptes d'acceptar-lo a mitges. Això vol dir que una tasca mal escrita no s'instal·la, en comptes d'instal·lar-se i executar-se a una hora equivocada.

L'única excepció és que el format diu quan es llança l'script, no garanteix que l'script funcioni. Verificar que la còpia es fa correctament requereix revisar el seu registre d'execució, cosa que et proposo muntar quan tinguem el sistema de monitoratge en marxa.

Tota la informació d'aquest informe va sortir de dues pàgines de manual instal·lades al servidor mateix.

Ja no depens d'un cercador per treballar a Linux.

• Un sistema Linux porta cinc fonts de documentació: man per entendre, --help per recordar, info per aprofundir, help per als builtins i /usr/share/doc per configurar.
• Saps llegir una pàgina de manual saltant al que necessites: EXAMPLES primer quan existeix, FILES per localitzar configuració, EXIT STATUS abans d'escriure scripts i SEE ALSO quan t'has equivocat d'eina.
• Entens la notació del SYNOPSIS: claudàtors per al que és opcional, punts suspensius per al que és repetible, barres per al que és excloent, i diverses línies per a diverses formes d'invocació.
• Coneixes les vuit seccions, i en particular la diferència entre man 1 passwd i man 5 passwd, que és el parany on cau tothom.
• Pots buscar sense saber el nom amb apropos i confirmar amb whatis.
• Et mous dins de less amb /, n, N, g, G i q, dreceres que reaprofitaràs per llegir fitxers i registres.
• Saps per què man cd no existeix i què fer llavors.
• I saps llegir el codi de sortida amb $?, i que un 1 no sempre significa error, com demostra grep.

Tens l'intèrpret i tens el manual. El que falta és el terreny. A la propera lliçó, Navegant pel Sistema de Fitxers, baixaràs a l'arbre que vas conèixer al Mòdul 1 però aquesta vegada per recórrer-lo: pwd i el directori de treball, cd en totes les seves formes incloses les que gairebé ningú no fa servir, ls esmicolat columna a columna, tree, stat amb les seves tres marques de temps, file per saber què és de debò un fitxer, i du/df per mirar quant ocupa /var/log/tramontana. Al final faràs un recorregut complet i documentat de l'arbre de Tramontana Reserves. I quan alguna cosa no et quadri, ja saps on mirar abans de preguntar.