Bloques de Código Shell y Bash en Org Babel
Org Babel proporciona soporte completo para scripting de shell en shells Unix y POSIX: Bash, Zsh, Sh, Fish, Dash, Csh, Ksh y Ash.
Los bloques Shell convierten Org Mode en un cuaderno interactivo de DevOps, runbook y consola de administración de sistemas capaz de ejecución local, procesamiento asíncrono en segundo plano y administración remota de servidores a través de SSH mediante TRAMP.
1. Requisitos y Configuración
1.1 Configuración de Emacs
A diferencia de otros lenguajes Babel que requieren módulos separados, todos los shells se rigen por una única librería Babel (ob-shell). Solo necesitas (shell . t) en tu org-babel-load-languages:
(org-babel-do-load-languages
'org-babel-load-languages
'((emacs-lisp . t)
(shell . t)))
(Nota: Antes de Org 8.2, esto se llamaba sh. Usa shell en todas las versiones modernas de Org).
1.2 Especificando el Shell
Especifica el nombre exacto del binario del shell como etiqueta de lenguaje del bloque (#+BEGIN_SRC <shell>):
# Bash:
#+BEGIN_SRC bash
echo "Ejecutando en $BASH_VERSION"
#+END_SRC
# Zsh:
#+BEGIN_SRC zsh
echo "Ejecutando en Zsh $ZSH_VERSION"
#+END_SRC
# POSIX / Dash (ejecución más rápida y ligera):
#+BEGIN_SRC dash
echo "Ejecutando en dash"
#+END_SRC
# Fish shell:
#+BEGIN_SRC fish
set greeting "Hola desde fish"
echo $greeting
#+END_SRC
El binario del shell especificado debe estar accesible en tu $PATH del sistema.
2. Modos de Ejecución: Aislado, Sesión y Asíncrono
2.1 Subsell Aislado (Predeterminado, :session none)
Cada bloque se ejecuta en un proceso subshell temporal nuevo. Las variables de entorno y los directorios de trabajo no se transfieren:
#+BEGIN_SRC bash :results output
echo "PID: $$"
export WORKSPACE="/tmp/build"
#+END_SRC
#+BEGIN_SRC bash :results output
# $WORKSPACE está vacío aquí porque esto se ejecuta en un nuevo proceso subshell:
echo "PID: $$, WORKSPACE: $WORKSPACE"
#+END_SRC
2.2 Sesiones Interactivas (:session <nombre>)
Se ejecuta dentro de un buffer comint persistente de Emacs (ej. *dev-session*). Las variables, funciones y directorios de trabajo persisten entre múltiples bloques:
#+BEGIN_SRC bash :session *dev-session* :results output
export CLUSTER_ID="prod-east-01"
cd /var/log
#+END_SRC
#+BEGIN_SRC bash :session *dev-session* :results output
# Usa el estado configurado en el bloque anterior:
echo "Desplegando en $CLUSTER_ID desde $(pwd)"
#+END_SRC
#+RESULTS:
: Desplegando en prod-east-01 desde /var/log
2.3 Ejecución Asíncrona No Bloqueante (:async yes)
Los scripts de larga duración (copias de seguridad, compilaciones de contenedores, entrenamiento de modelos) congelan Emacs cuando se ejecutan sincrónicamente. ¡Agrega :async yes para ejecutarlos en segundo plano sin bloquear el editor!
Reglas:
:asyncrequiere:session <nombre>.- Mientras se ejecuta, Babel inserta un token UUID temporal en el bloque
#+RESULTS:. - Una vez que la ejecución finaliza en segundo plano, el UUID se reemplaza automáticamente con la salida estándar del comando.
#+BEGIN_SRC bash :session *bg-job* :async yes :results output
echo "Iniciando copia de seguridad pesada de la base de datos a las $(date)..."
sleep 5
echo "¡Copia de seguridad finalizada exitosamente a las $(date)!"
#+END_SRC
#+RESULTS:
: Iniciando copia de seguridad pesada de la base de datos a las Sun May 18 14:00:00 UTC 2025...
: ¡Copia de seguridad finalizada exitosamente a las Sun May 18 14:00:05 UTC 2025!
Para ejecutar sincrónicamente en una sesión, pasa :async no.
3. Argumentos de Cabecera Específicos de Shell
Org Babel proporciona tres argumentos de cabecera únicos diseñados específicamente para operaciones de shell:
3.1 :stdin <nombre-elemento> (Entrada Estándar)
Enruta elementos Org con nombre (tablas, texto sin formato u otros resultados de bloques de código) al stdin del comando shell:
# Entrada de texto sin formato:
#+NAME: raw_server_payload
{"nodo": "alpha", "nucleos": 8, "estado": "activo"}
# Enruta la carga útil directamente a jq:
#+BEGIN_SRC bash :stdin raw_server_payload :results output
jq -r '.nodo + " tiene " + (.nucleos|tostring) + " nucleos"'
#+END_SRC
#+RESULTS:
: alpha tiene 8 nucleos
(Nota: Los bloques que usan :stdin se evalúan en un subshell temporal, ignorando :session).
3.2 :cmdline <args> (Argumentos de Línea de Comandos)
Pasa argumentos posicionales ($1, $2, $@) al cuerpo del script:
#+BEGIN_SRC bash :cmdline "staging" 8080 :results output
ENV="$1"
PORT="$2"
echo "Iniciando servidor en el puerto $PORT en modo $ENV..."
#+END_SRC
#+RESULTS:
: Iniciando servidor en el puerto 8080 en modo staging...
⚠️ Advertencia de Seguridad: Los argumentos :cmdline se expanden directamente por el shell anfitrión. No pases cadenas no confiables o sin escapar para evitar la inyección de comandos.
3.3 :shebang <directiva> (Scripts Autónomos y Salida Limpia)
Obliga a que el bloque se escriba en un archivo ejecutable temporal y se ejecute a través de su directiva shebang:
#+BEGIN_SRC bash :shebang "#!/usr/bin/env bash" :results output
for i in {1..3}; do
echo "Paso $i"
done
#+END_SRC
Por qué :shebang es esencial:
En bloques :session de varias líneas sin shebang, las líneas se envían línea por línea al shell interactivo, lo que puede producir cadenas de solicitud no deseadas (ej., bash-5.1$ ) en tus resultados. Especificar :shebang o ejecutar sin una sesión produce una salida completamente limpia.
4. Administración Remota de Servidores a través de TRAMP (:dir)
Puedes ejecutar comandos en servidores remotos, máquinas virtuales o contenedores Docker especificando una ruta TRAMP en :dir:
:dir /ssh:<usuario>@<host>:<ruta-remota>
:dir /docker:<id-contenedor>:<ruta>
:dir /sudo::/etc
Ejemplo: Flujo de Trabajo de Administración Remota
# Verifica el uso del disco y la memoria en un servidor remoto:
#+BEGIN_SRC bash :dir /ssh:[email protected]:/tmp :results output
hostname
uptime
df -h / | awk 'NR==2 {print "Uso del Disco Raíz: " $5}'
#+END_SRC
#+RESULTS:
: bastion.example.com
: 14:22:05 up 42 days, 3:18, 1 user, load average: 0.12, 0.08, 0.05
: Uso del Disco Raíz: 48%
Sesiones Remotas
Combina :dir con :session para mantener una conexión SSH activa a través de múltiples bloques sin reconectar en cada paso:
#+BEGIN_SRC bash :dir /ssh:[email protected]:/home/admin :session *remote-bastion* :results output
WORKDIR=$(mktemp -d)
cd "$WORKDIR"
pwd
#+END_SRC
5. Formatos de Resultados y Extracción de Datos Tabulares
5.1 Salida Delimitada por Tabulaciones a Tabla Org (:results output table)
Cuando los comandos shell emiten salida tabular estructurada o separada por tabulaciones, Babel los analiza en tablas Org nativas:
#+BEGIN_SRC bash :results output table
printf "PID\tUsuario\tComando\n"
printf "101\troot\tsystemd\n"
printf "405\tpostgres\tpostgres\n"
printf "892\tnginx\tnginx: worker\n"
#+END_SRC
#+RESULTS:
| PID | Usuario | Comando |
|-----+----------+----------------|
| 101 | root | systemd |
| 405 | postgres | postgres |
| 892 | nginx | nginx: worker |
5.2 Dirigir la Salida a un Enlace de Archivo (:results file :file <ruta>)
#+BEGIN_SRC bash :results file :file reports/sysinfo.txt
uname -a > reports/sysinfo.txt
cat /etc/os-release >> reports/sysinfo.txt
#+END_SRC
#+RESULTS:
[[file:reports/sysinfo.txt]]
6. Paso de Variables y Arreglos de Bash (:var)
6.1 Escalares y Cadenas
#+BEGIN_SRC bash :var port=8000 host="localhost" :results output
echo "Conectando a $host en el puerto $port..."
#+END_SRC
6.2 Arreglos 1D de Bash
Bash admite parámetros de arreglos 1D definidos con sintaxis de lista:
#+BEGIN_SRC bash :results output :var servidores='("web-01" "web-02" "db-01")'
echo "Total de servidores: ${#servidores[@]}"
for s in "${servidores[@]}"; do
echo "Haciendo ping a $s..."
done
#+END_SRC
#+RESULTS:
: Total de servidores: 3
: Haciendo ping a web-01...
: Haciendo ping a web-02...
: Haciendo ping a db-01...
7. Errores Comunes y Mejores Prácticas de Seguridad
| Error | Causa | Solución |
|---|---|---|
| Emacs se cuelga con comandos SSH o ffmpeg | El comando intenta leer stdin del subshell | Redirige stdin explícitamente (</dev/null) o usa ssh -n. |
Caracteres de solicitud bash-5.1$ no deseados en resultados | Eco interactivo línea por línea en :session | Agrega :shebang #!/usr/bin/env bash o evalúa fuera de la sesión. |
| Expansión inadvertida de variables en heredocs | Usar <<EOF permite que el shell expanda $VARS prematuramente | Usa un delimitador entre comillas <<"EOF" para mantener el texto literal y evitar la expansión temprana. |
Sintaxis no POSIX falla en bloques sh | #+BEGIN_SRC sh se asigna a /bin/sh (a menudo dash en Debian/Ubuntu) | Usa #+BEGIN_SRC bash si tu script usa bashismos ([[, ((, arreglos). |
Inyección de comandos a través de :cmdline | Los argumentos del shell se evalúan literalmente | Cita los argumentos cuidadosamente o pasa datos a través de :stdin o :var. |
| La salida del bloque asíncrono no aparece | :async yes requiere una :session activa | Siempre proporciona un :session <nombre> cuando uses :async yes. |
8. Ejemplo Completo de Runbook DevOps
#+TITLE: Runbook de Salud del Servicio de Producción
#+PROPERTY: header-args:bash :session *runbook* :results output
* Paso 1: Configuración de Verificación de Salud
#+NAME: cluster_nodes
| Hostname | Rol |
|-----------------+---------|
| prod-app-01.lan | backend |
| prod-app-02.lan | backend |
| prod-db-01.lan | storage |
* Paso 2: Sondear Nodos del Clúster
#+BEGIN_SRC bash :var nodes=cluster_nodes :colnames yes :results output table
printf "Host\tRol\tEstado\n"
for row in "${nodes[@]}"; do
# Analiza datos de fila separados por tabulaciones/espacios:
host=$(echo "$row" | awk '{print $1}')
role=$(echo "$row" | awk '{print $2}')
# Sonda de ping rápida:
if ping -c 1 -W 1 "$host" > /dev/null 2>&1; then
status="EN LÍNEA"
else
status="FUERA DE LÍNEA"
fi
printf "%s\t%s\t%s\n" "$host" "$role" "$status"
done
#+END_SRC
#+RESULTS:
| Host | Rol | Estado |
|-----------------+---------+-------------|
| prod-app-01.lan | backend | EN LÍNEA |
| prod-app-02.lan | backend | EN LÍNEA |
| prod-db-01.lan | storage | EN LÍNEA |
* Paso 3: Ejecutar Mantenimiento del Servicio de Forma Asíncrona
#+BEGIN_SRC bash :session *runbook* :async yes
echo "Iniciando purga de caché en todos los nodos..."
sleep 4
echo "Purga de caché completada exitosamente."
#+END_SRC