Hay una habilidad que separa al administrador que resuelve incidencias del que las escala: no necesitar internet para saber qué hace un comando. Linux viene con su propia documentación instalada, escrita por quienes desarrollaron cada herramienta, actualizada con la versión exacta que tienes delante y disponible aunque el servidor esté aislado en una red sin salida.

Esa última parte no es un supuesto teórico. Un servidor de producción bien configurado suele estar detrás de un cortafuegos que no permite navegación. Un entorno bancario o sanitario puede estar en una red completamente separada. Y cuando hay una incidencia grave, lo primero que se corta es el acceso externo. Si tu método de trabajo es «lo busco», en ese momento te quedas sin método.

Esta lección te enseña el método alternativo. Al terminarla sabrás leer una página de manual entera —incluida esa notación con corchetes y barras que parece jeroglífica—, buscar un comando cuando no recuerdas su nombre, y saber en cuál de las cinco fuentes de documentación distintas está la respuesta que necesitas. Es, probablemente, la lección más rentable del módulo.

1. Las cinco fuentes de documentación de un sistema Linux
2. man: el manual del sistema
3. Cómo se lee la notación del SYNOPSIS
4. Las secciones del manual y por qué existen
5. Buscar en el manual: whatis, apropos y man -k
6. Navegar con less dentro de man
7. --help: el resumen rápido
8. info: la documentación extensa de GNU
9. help: los builtins de Bash y por qué man cd no funciona
10. Documentación local en /usr/share/doc
11. tldr y cheat: el complemento, no el sustituto
12. Códigos de salida y $?: saber si algo ha fallado
13. Estrategia de búsqueda cuando no sabes ni el nombre

Antes de entrar en detalle, el mapa. En srv-tramontana conviven cinco fuentes distintas, y elegir mal te hace perder tiempo:

Y una sexta, opcional, que hay que situar bien: tldr, que da ejemplos prácticos pero no es documentación oficial y no es exhaustiva.

La regla operativa: --help para recordar, man para entender, info para profundizar, /usr/share/doc para configurar.

man (de manual) muestra la página de documentación oficial de un comando, un archivo de configuración, una llamada al sistema o un formato de fichero.

Se abre a pantalla completa en un paginador. Se sale con q.

Las páginas de manual siguen una estructura estandarizada desde los años setenta. Conocerla te permite saltar directamente a lo que buscas en vez de leer de arriba abajo:

Dos consejos que cambian cómo se usa man:

• Empieza por EXAMPLES si existe. No todas las páginas lo tienen (las de GNU suelen no tenerlo), pero cuando está, resuelve la duda en treinta segundos.
• Termina por SEE ALSO cuando te has equivocado de comando. Es la lista de herramientas relacionadas escrita por quien mejor conoce el dominio.

Un ejemplo real de lectura selectiva. Necesitas saber qué archivos usa el servicio SSH:

Dentro, pulsas /FILES y Enter: saltas directamente a la lista de archivos, sin leer las trescientas líneas anteriores. Volveremos a esta técnica en el apartado 6.

El SYNOPSIS es la parte que más gente se salta y la que más información contiene. Está escrito en una notación formal con reglas fijas:

Veámoslo aplicado. El SYNOPSIS de cp:

Esa página te está diciendo tres cosas que no aparecen escritas en prosa en ningún sitio:

1. Hay tres formas válidas de invocar cp, no una. Cada línea es una forma completa.
2. En la primera, ORIGEN y DESTINO van sin corchetes: son obligatorios. cp sin argumentos falla.
3. En la segunda, ORIGEN... lleva puntos suspensivos y el último argumento se llama DIRECTORIO: puedes copiar varios archivos de golpe, pero entonces el destino tiene que ser un directorio. Eso explica un error que verás en la lección 02-04.

Otro ejemplo, man 5 crontab frente a man 1 crontab:

Aquí [-l | -r | -e] te dice que listar, borrar y editar son excluyentes: no puedes pedir dos a la vez. Está toda la lógica del comando en una línea.

Ejercicio mental que deberías hacerte siempre: antes de leer OPTIONS, lee el SYNOPSIS y pregúntate cuántas formas de invocación hay y qué es obligatorio. Muchas veces la respuesta ya está ahí.

El manual está dividido en ocho secciones numeradas. La razón es que un mismo nombre puede referirse a cosas distintas: passwd es un comando y un archivo de configuración; printf es un comando y una función de C.

Las tres que usarás constantemente como administrador son 1 (comandos), 5 (archivos de configuración) y 8 (herramientas de root).

Cuando ejecutas man passwd sin número, man te da la primera sección donde encuentre esa página, normalmente la 1:

Pero si lo que quieres es entender el formato del archivo /etc/passwd, esa es otra página completamente distinta:

La cabecera te dice siempre en qué sección estás: PASSWD(1) frente a PASSWD(5). Acostúmbrate a mirar ese número: es la forma de saber si estás leyendo la página correcta.

Para saber en qué secciones existe una página:

man -a te las muestra todas en secuencia: al salir de una con q, pregunta si quieres ver la siguiente.

Dos páginas de la sección 7 que merece la pena que conozcas ya:

Estas dos herramientas resuelven las dos preguntas más frecuentes.

«¿Qué es este comando que acabo de ver en un script?» → whatis (equivalente a man -f), que muestra solo la línea NAME:

«No sé cómo se llama el comando que necesito» → apropos (equivalente a man -k), que busca la palabra en las descripciones de todas las páginas instaladas:

En tres segundos, sin buscador, tienes las tres herramientas que existen para el problema. Esta es la respuesta a la crítica de «la CLI no es descubrible» del apartado 1 de la lección anterior: sí lo es, pero se descubre con apropos, no con menús.

Cuando la búsqueda devuelve demasiado, se afina:

-s 8 restringe a la sección de administración. También puedes limitar la búsqueda al nombre en vez de a la descripción:

-e fuerza coincidencia exacta, útil porque apropos tar devolvería decenas de páginas que contienen «tar» dentro de otras palabras.

Si apropos responde nada apropiado, puede que la base de datos de índices no esté generada. Se regenera con:

man no dibuja nada por sí mismo: envía el texto a un paginador, que en Ubuntu es less. Los atajos que aprendas aquí valen también para ver archivos y logs (lección 02-05), así que son doblemente rentables.

El flujo de trabajo real de alguien con experiencia no es leer la página: es entrar y buscar.

Supón que quieres saber qué hace la opción -h de du. En vez de recorrer la página:

Dentro, escribe /-h y Enter. less salta a la primera aparición; con n avanzas hasta la que está en la sección OPTIONS:

Truco muy útil: para buscar una opción concreta y evitar las decenas de apariciones sueltas de esa letra, busca el patrón con espacios:

El ^ significa «al principio de línea» y las páginas de manual indentan las opciones, así que esto salta directamente a su definición. (Ese ^ es una expresión regular; el tema completo es de la lección 03-02, pero este uso suelto lo puedes adoptar ya.)

Y una advertencia práctica: si estás dentro de man y no sabes cómo salir, es q. Es la pregunta más frecuente de todo el curso.

Casi todos los comandos aceptan --help (o -h) y responden con un resumen en la propia terminal, sin paginador:

Diferencias con man:

Ese último punto tiene una consecuencia práctica: en un contenedor Docker minimalista (Módulo 7) no suele haber páginas de manual instaladas, porque se eliminan para reducir el tamaño de la imagen. Ahí --help es lo único que tienes.

Cuidado con un detalle: en algunos comandos, -h no significa «ayuda». En ls, du y df significa human-readable. Si dudas, usa --help, que es inequívoco.

Y otro: cuando la salida de --help no cabe en pantalla, no la persigas hacia arriba. Envíala al paginador:

Ese | es una tubería; se explica a fondo en la lección 03-04, pero este uso puedes adoptarlo desde hoy.

El proyecto GNU decidió en su día que las páginas de manual eran demasiado limitadas para documentar sus herramientas y creó su propio sistema: Texinfo, que se consulta con info. Está organizado en nodos enlazados, como un libro con capítulos navegables.

Consecuencia práctica que hay que conocer: en las herramientas GNU (ls, cp, mv, tar, grep, sed...), la página de manual es a menudo un resumen y la documentación real está en info. Muchas páginas terminan con una nota explícita:

Navegación básica de info:

Cuándo merece la pena info: cuando man te da la opción pero no el porqué. Por ejemplo, para entender el comportamiento exacto de cp con enlaces simbólicos, o los formatos de date, info explica los casos límite que man solo enumera.

Si info te resulta incómodo (le pasa a mucha gente por su navegación con nodos), tienes una salida:

Así lees el mismo contenido en less, con los atajos que ya conoces.

Prueba esto:

La explicación está en la lección anterior: cd no es un programa, es una orden interna de Bash. No hay ningún paquete que lo instale, así que no hay ninguna página de manual que lo documente. Su documentación la proporciona el propio Bash con el builtin help:

Y la lista completa de builtins, que conviene mirar una vez en la vida:

El árbol de decisión completo:

Hay un caso intermedio que conviene conocer: man builtins muestra todos los builtins documentados en una sola página, y man bash contiene la documentación completa del shell. Es una de las páginas de manual más largas del sistema (más de cinco mil líneas), y por eso mismo /palabra es imprescindible ahí dentro.

Cada paquete instalado deja documentación en /usr/share/doc/<paquete>/. Es la fuente que más se ignora y la que más veces contiene exactamente lo que necesitas: ficheros de configuración de ejemplo.

Qué esperar en cada tipo de archivo:

Muchos están comprimidos en .gz. Se leen sin descomprimirlos con zless o zcat:

README.Debian es especialmente valioso porque documenta las diferencias entre la herramienta original y como la empaqueta Ubuntu: rutas cambiadas, opciones por defecto distintas, integración con systemd. Eso no aparece en la documentación oficial del proyecto y es la causa de la mitad de las confusiones cuando sigues un tutorial escrito para otra distribución.

Cuando llegues a configurar servicios en el Módulo 5 y en el Módulo 8, esta carpeta será tu primera parada antes que cualquier tutorial.

tldr (de too long; didn't read) es una colección comunitaria de ejemplos prácticos. Donde man tar te da mil líneas, tldr tar te da las seis invocaciones que se usan el 95 % de las veces.

Es enormemente útil, y hay que ser consciente de sus tres límites:

1. No es exhaustivo. Muestra lo común, no lo que necesitas en un caso raro. Y los casos raros son precisamente las incidencias.
2. No es oficial. Lo escribe la comunidad; puede estar desactualizado respecto a tu versión.
3. Puede no estar instalado, y en un servidor de producción es probable que no lo esté (y que no debas instalarlo solo para eso).

Criterio profesional: tldr para arrancar rápido con una herramienta que ya entiendes; man para decidir algo que va a producción. Si vas a ejecutar un comando destructivo o a modificar una configuración de un servicio en marcha, la fuente es el manual.

Recuerda del apartado 9 de la lección anterior: todo comando devuelve un número al terminar. Ahora vamos a mirarlo directamente, porque es la información que te dice si algo funcionó cuando el comando no dijo nada.

$? guarda el código del último comando ejecutado. Convención universal:

Cada comando puede definir los suyos, y ahí es donde entra la sección EXIT STATUS del manual:

Buscando /EXIT STATUS:

Eso significa que en grep, 1 no es un fallo: significa «no hay coincidencias». Confundir «no encontró nada» con «se rompió» es una fuente clásica de bugs en scripts de monitorización. Y la única forma de saberlo es leyendo esa sección del manual.

Cuidado con una trampa: $? se reescribe con cada comando, incluido el echo que lo muestra.

El segundo 0 es el código del echo anterior, que funcionó perfectamente. Consulta $? inmediatamente, o guárdalo en una variable (Módulo 4).

Este es el procedimiento completo, ordenado, para cuando te enfrentas a un problema sin saber qué herramienta lo resuelve:

1. Describe el problema en dos o tres palabras en inglés. «space», «compress», «rename», «monitor processes».
2. apropos con esas palabras, acotando con -s 1 o -s 8.
3. De la lista, whatis sobre los candidatos para descartar rápido.
4. man sobre el elegido: lee NAME, SYNOPSIS y salta a EXAMPLES.
5. Si no era el correcto, SEE ALSO de esa página suele contener el que sí lo es.
6. Si el comando existe pero no sabes usarlo, tldr para un arranque rápido, y vuelta al manual para los detalles.
7. Si es un archivo de configuración, man 5 <nombre> y /usr/share/doc/<paquete>/examples/.
8. Si es una orden que no tiene manual, type te dirá si es un builtin y entonces help.

Un recorrido completo. Marta Vidal pregunta cuánto ocupa el directorio de la aplicación:

Dentro del manual, /summarize:

Y /human:

Resultado, sin salir del servidor y sin buscador:

Tres comandos y dos búsquedas dentro de una página. Ese es el método.

No saber salir de man. Es q. Si estás en info, también q. Si has entrado en vim por accidente, es :q! (lección 02-05).

Leer la página entera de arriba abajo. Las páginas de manual son referencia, no tutoriales. Entra y busca con /.

Ignorar el número de sección. Si man passwd te habla de cambiar contraseñas y tú buscabas el formato del archivo, no es que el manual esté mal: te falta el 5.

Buscar en internet antes que en apropos. El buscador te dará una respuesta escrita para otra distribución, otra versión y otro año. man documenta exactamente el binario que tienes instalado.

Copiar un comando de un foro sin leer sus opciones. Antes de ejecutar algo que no entiendes, pásale las opciones por man. Es literalmente un minuto, y es la diferencia entre resolver una incidencia y provocar otra.

Consejo: man -k es tu buscador local. Acostúmbrate a probarlo antes de abrir el navegador. La primera semana te parecerá más lento; a partir de la tercera irás más rápido.

Consejo: guarda lo que aprendes. Crea /home/operador/scripts/notas/ y escribe ahí los comandos que has necesitado buscar. Tu propia documentación, con tus casos, es más rápida de consultar que cualquier manual.

Consejo: lee man 7 hier una vez. Es el FHS del Módulo 1 contado por el propio sistema. Media hora bien invertida.

Consejo: en un servidor sin páginas de manual, comprueba si están desactivadas antes de darlas por perdidas. Algunas imágenes las excluyen en la configuración de instalación de paquetes; cómo se recuperan es materia de la lección 05-03.

Sin ejecutar los comandos, solo leyendo sus páginas de manual, responde:

1. ¿mkdir acepta crear varios directorios en una sola orden? ¿Cómo lo sabes por el SYNOPSIS?
2. ¿Cuántas formas distintas de invocación tiene ln?
3. En man 1 tar, ¿son -c, -x y -t compatibles entre sí?

Luis te escribe: «Necesito quedarme solo con las últimas 50 líneas de /var/log/tramontana/acceso.log y no me acuerdo del comando. Además quiero verlo actualizándose en vivo mientras pruebo la aplicación. ¿Me lo buscas en Google?»

Restricción: srv-tramontana está en una red sin salida a internet. Resuélvelo usando solo documentación del sistema, y documenta el camino que has seguido (qué comandos de búsqueda usaste y en qué orden).

Marta Vidal quiere saber qué hace exactamente la línea 0 3 * * * /home/operador/scripts/backup.sh que aparece en la configuración de tareas programadas del servidor anterior, y si el formato es fiable.

Usando solo el manual del sistema, averigua:

1. En qué sección del manual está documentado el formato de ese archivo (no el comando).
2. Qué significa cada uno de los cinco campos.
3. Qué código de salida devuelve el comando crontab si el archivo tiene un error de sintaxis.

Escribe la respuesta como un párrafo breve dirigido a Marta, que no es técnica.

Solución 1

Sí acepta varios. La prueba está en los puntos suspensivos tras DIRECTORIO: significan «uno o más». Y como DIRECTORIO va sin corchetes, al menos uno es obligatorio. Toda esa información está en una sola línea, sin leer una palabra de prosa.

Cuatro formas. Fíjate en la segunda: ln OBJETIVO sin nombre de enlace. Crea el enlace en el directorio actual con el mismo nombre que el objetivo. Es un detalle que sorprende y que solo se aprende leyendo el SYNOPSIS. Lo usarás en la lección 02-06.

Están agrupadas bajo el epígrafe «Operation mode» (modo de operación), lo que indica que se elige uno y solo uno. La página lo confirma más arriba:

No son compatibles. Intentar tar -cx da un error de tipo «You may not specify more than one -Acdtrux option». La pista estaba en la organización de la propia página: cuando un manual agrupa opciones bajo un epígrafe de «modo», suelen ser excluyentes.

Solución 2

Camino seguido.

Primero, buscar en el manual por concepto:

Confirmar que es lo que parece:

Ir al manual y buscar dentro cómo fijar el número de líneas. Dentro de man tail, /lines:

Y para la segunda parte, la de seguir el archivo en vivo, /follow:

Los dos comandos que resuelven la petición de Luis:

Se sale del modo seguimiento con Ctrl+C.

El matiz que aporta la documentación y que no habría dado una respuesta rápida de buscador: la diferencia entre -f y -F. -f sigue el descriptor del archivo; si logrotate rota el log a medianoche y crea uno nuevo, tail -f se queda mirando el archivo antiguo, ya renombrado, y deja de mostrar nada sin avisar. -F sigue el nombre, así que reengancha con el archivo nuevo.

Para seguir un log de producción que rota, la opción correcta es tail -F. Eso está literalmente en la página de manual, y es exactamente el tipo de detalle que un tutorial de tres líneas omite. Volveremos a ello en la lección 02-05.

Lo que le contestas a Luis no es el comando: es el método. apropos con dos palabras en inglés, whatis para confirmar y /opción dentro del manual. Treinta segundos, sin internet.

Solución 3

1. Sección del manual. El comando crontab está en la sección 1, pero el formato del archivo está en la 5:

2. Los cinco campos. Dentro de la página, buscando /field:

Aplicado a 0 3 * * *: minuto 0, hora 3, cualquier día del mes, cualquier mes, cualquier día de la semana. Es decir, todos los días a las 3:00.

3. Código de salida ante un error de sintaxis. En man 1 crontab, buscando /EXIT:

Y en la sección DIAGNOSTICS de la misma página se explica que un archivo con errores de sintaxis es rechazado por completo: crontab no instala una versión parcial. Ese matiz es el importante para Marta, y solo aparece leyendo la página.

Informe para Marta:

Marta, la línea 0 3 * * * /home/operador/scripts/backup.sh es una tarea programada del sistema. Los cinco primeros valores son un reloj: minuto 0, hora 3, y los tres asteriscos significan «cualquier día, cualquier mes, cualquier día de la semana». En conjunto: el script de copia de seguridad se ejecuta automáticamente todos los días a las 3:00 de la madrugada.

Sobre la fiabilidad del formato: es el estándar de Unix, lleva más de cuarenta años en uso y está documentado en el propio sistema. Cuando se instala una tarea, el programa valida la sintaxis y rechaza el archivo entero si hay un error, en lugar de aceptarlo a medias. Eso significa que una tarea mal escrita no se instala, en vez de instalarse y ejecutarse a una hora equivocada.

La única salvedad es que el formato dice cuándo se lanza el script, no garantiza que el script funcione. Verificar que la copia se hace correctamente requiere revisar su registro de ejecución, algo que te propongo montar cuando tengamos el sistema de monitorización en marcha.

Toda la información de este informe salió de dos páginas de manual instaladas en el propio servidor.

Ya no dependes de un buscador para trabajar en Linux.

• Un sistema Linux trae cinco fuentes de documentación: man para entender, --help para recordar, info para profundizar, help para los builtins y /usr/share/doc para configurar.
• Sabes leer una página de manual saltando a lo que necesitas: EXAMPLES primero cuando existe, FILES para localizar configuración, EXIT STATUS antes de scriptear y SEE ALSO cuando te has equivocado de herramienta.
• Entiendes la notación del SYNOPSIS: corchetes para lo opcional, puntos suspensivos para lo repetible, barras para lo excluyente, y varias líneas para varias formas de invocación.
• Conoces las ocho secciones, y en particular la diferencia entre man 1 passwd y man 5 passwd, que es la trampa donde cae todo el mundo.
• Puedes buscar sin saber el nombre con apropos y confirmar con whatis.
• Te mueves dentro de less con /, n, N, g, G y q, atajos que reutilizarás para leer archivos y logs.
• Sabes por qué man cd no existe y qué hacer entonces.
• Y sabes leer el código de salida con $?, y que un 1 no siempre significa error, como demuestra grep.

Tienes el intérprete y tienes el manual. Lo que falta es el terreno. En la próxima lección, Navegando el Sistema de Archivos, bajarás al árbol que conociste en el Módulo 1 pero esta vez para recorrerlo: pwd y el directorio de trabajo, cd en todas sus formas incluidas las que casi nadie usa, ls desmenuzado columna a columna, tree, stat con sus tres marcas de tiempo, file para saber qué es de verdad un archivo, y du/df para mirar cuánto ocupa /var/log/tramontana. Al final harás un recorrido completo y documentado del árbol de Tramontana Reservas. Y cuando algo no te cuadre, ya sabes dónde mirar antes de preguntar.