Manual d’operacions

Aquest capítol tracta el desplegament, la supervisió i el manteniment de lippycat en producció. Inclou la configuració de serveis systemd, les comprovacions d’estat, la gestió de registres, la resposta a incidents i els procediments de manteniment.

Desplegament

Requisits del sistema

Instal·lació del binari

Compileu a partir del codi font:

make build-release

sudo cp bin/lc /usr/local/bin/

sudo chmod +x /usr/local/bin/lc

Atorgueu capacitats de captura per evitar executar-lo com a root:

sudo setcap cap_net_raw,cap_net_admin=eip /usr/local/bin/lc

Creació de la configuració

sudo mkdir -p /etc/lippycat/certs

sudo cp config.yaml /etc/lippycat/

sudo chown root:root /etc/lippycat/config.yaml

sudo chmod 600 /etc/lippycat/config.yaml

Serveis systemd

Captura autònoma (Sniff)

# /etc/systemd/system/lippycat.service
[Unit]
Description=lippycat Network Traffic Capture
After=network.target

[Service]
Type=simple
User=root
ExecStart=/usr/local/bin/lc sniff voip -i eth0 --config /etc/lippycat/config.yaml
Restart=always
RestartSec=5
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Node processador

# /etc/systemd/system/lippycat-processor.service
[Unit]
Description=lippycat Processor Node
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/lc process \
  --listen 0.0.0.0:55555 \
  --tls-cert /etc/lippycat/certs/server.crt \
  --tls-key /etc/lippycat/certs/server.key \
  --per-call-pcap --per-call-pcap-dir /var/capture/calls \
  --filter-file /etc/lippycat/filters.yaml
Restart=always
RestartSec=5
LimitNOFILE=65536
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Node Hunter

# /etc/systemd/system/lippycat-hunter.service
[Unit]
Description=lippycat Hunter Node
After=network.target

[Service]
Type=simple
User=root
ExecStart=/usr/local/bin/lc hunt voip -i eth0 \
  --processor processor.internal:55555 \
  --tls-ca /etc/lippycat/certs/ca.crt
Restart=always
RestartSec=5
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Activació i inici

sudo systemctl daemon-reload

sudo systemctl enable lippycat-processor

sudo systemctl start lippycat-processor

sudo systemctl status lippycat-processor

Comprovacions de l’estat

Transport d’esdeveniments normalitzats

Confirmeu la negociació del mode d’esdeveniments als registres dels nodes, genereu una transacció DNS o HTTP coneguda i localitzeu-la al registre estructurat del processador i a la cronologia d’esdeveniments de la TUI. Configureu alertes per a l’esgotament de l’spool del productor o del WAL del processador, els lots rebutjats, les omissions per compatibilitat i els buits en la seqüència d’esdeveniments. Verifiqueu per separat el PCAP local del Tap quan calgui evidència dels paquets.

La versió 1 de la subscripció TUI comença en un límit de dades en directe i mai no reprodueix un interval de desconnexió. Després d’una interrupció, és normal que hi hagi un buit en reconnectar. És diferent de l’expulsió local, en què l’anell limitat de la TUI elimina una fila antiga que ja havia arribat. La pèrdua durant el transport afecta la completesa de les dades; l’expulsió només afecta la finestra de visualització.

En les actualitzacions graduals, actualitzeu els processadors abans que els productors d’esdeveniments i manteniu el mode de paquets com a base de compatibilitat. Activeu el mecanisme alternatiu només després de comprovar-ne l’impacte en l’amplada de banda i la privadesa. Manteniu desactivades les opcions d’inclusió de camps sensibles i metadades de fitxers tret que siguin necessàries, i protegiu els spools d’esdeveniments, els WAL, els registres i el transport de la TUI com a evidències de captura.

Emmagatzematge i recuperació de l’spool d’esdeveniments

El reenviament fiable d’esdeveniments emmagatzema els lots no confirmats en un directori spool exclusiu. No compartiu mai aquest directori entre processos ni n’editeu els fitxers mentre el procés propietari estigui en execució. El límit de 4 MiB de càrrega útil codificada continua actiu quan es desactiva el límit total de bytes lògics.

El límit configurat i l’estat pendent descriuen els bytes lògics que esperen confirmació. L’ús físic del disc pot ser més alt mentre els fitxers confirmats o expulsats esperen que s’eliminin, de manera que cal supervisar per separat l’espai lliure del sistema de fitxers. La neteja es torna a intentar en iniciar i durant les actualitzacions posteriors de l’spool; els registres retirats no es tornen a enviar.

Si l’emmagatzematge no pot conservar un esdeveniment i la cobertura exacta de la seva pèrdua, el reenviament s’atura en lloc d’informar d’una transmissió correcta. Un error que deixi incerta la durabilitat també bloqueja el reenviament i els canvis de l’spool. Atureu el node afectat i torneu a obrir el mateix directori per recuperar-ne l’últim estat complet. En cas d’errors de propietat, corrupció o recuperació, conserveu tot el directori, corregiu la causa indicada i reinicieu. Aparteu-lo només quan accepteu explícitament que tots els esdeveniments pendents es perdin.

Abans d’una actualització que canviï l’empremta de la política d’anàlisi d’esdeveniments, buideu els registres pendents de l’spool en mode d’esdeveniments amb la versió anterior i la seva configuració original. Atureu les captures noves, deixeu que es confirmin els lots pendents i comproveu que el recompte pendent arriba a zero abans d’aturar el procés antic. Els registres pendents incompatibles bloquegen intencionadament l’inici amb la política nova; l’aplicació no els descarta ni els reinterpreta silenciosament. Si l’inici informa d’una discrepància de política, conserveu el directori i torneu-lo a obrir amb la versió i configuració anteriors per completar la transmissió.

Comprovació ràpida de l’estat

Comproveu si el servei està en execució:

systemctl is-active lippycat-processor

Comproveu si el processador funciona correctament:

lc show status -P localhost:55555 --tls-ca ca.crt

Comproveu quins Hunters estan connectats:

lc list hunters -P localhost:55555 --tls-ca ca.crt

Script de comprovació diària de l’estat

#!/bin/bash
# daily-health-check.sh

echo "=== lippycat Health Check — $(date) ==="

# Service status
echo "1. Service Status:"
systemctl is-active lippycat-processor
systemctl is-active lippycat-hunter

# Resource usage
echo -e "\n2. Resource Usage:"
ps aux | grep "[l]c " | head -5

# Disk space for PCAP files
echo -e "\n3. PCAP Storage:"
df -h /var/capture/ 2>/dev/null || echo "PCAP directory not configured"

# Processor status (distributed deployments)
echo -e "\n4. Processor Status:"
lc show status -P localhost:55555 --tls-ca /etc/lippycat/certs/ca.crt 2>&1

# Recent errors in logs
echo -e "\n5. Recent Errors (last 24h):"
journalctl -u 'lippycat*' --since "24 hours ago" --priority=err --no-pager -q

echo -e "\n=== Health Check Complete ==="

Supervisió de les connexions dels Hunters

Observeu el nombre de Hunters en temps real:

watch -n 5 'lc show status -P localhost:55555 --tls-ca ca.crt | \
  jq "{total: .total_hunters, healthy: .healthy_hunters}"'

Utilitzeu aquest script per generar alertes quan faltin Hunters:

#!/bin/bash
expected=3
actual=$(lc show status -P localhost:55555 --tls-ca ca.crt 2>/dev/null | \
  jq -r '.healthy_hunters')
if [ "$actual" -lt "$expected" ]; then
    echo "ALERT: Only $actual/$expected hunters connected"
    exit 1
fi

Gestió de registres

lippycat utilitza registres estructurats a stdout/stderr. Quan s’executa sota systemd, els registres van al journal.

Visualització de registres

Seguiu els registres en directe:

journalctl -u lippycat-processor -f

Mostreu els registres de l’última hora:

journalctl -u lippycat-processor --since "1 hour ago"

Mostreu només els errors:

journalctl -u lippycat-processor --priority=err

Mostreu els registres de tots els serveis lippycat:

journalctl -u 'lippycat*' --since today

Rotació de registres

Si es registren dades en fitxers en lloc del journal:

# /etc/logrotate.d/lippycat
/var/log/lippycat/*.log {
    daily
    rotate 30
    compress
    delaycompress
    missingok
    notifempty
    create 644 root root
}

Anàlisi de registres

#!/bin/bash
# Quick error summary from journal
echo "Error Summary (last 24h):"
journalctl -u 'lippycat*' --since "24 hours ago" --priority=err --no-pager | \
  awk '{for(i=5;i<=NF;i++) printf "%s ", $i; print ""}' | \
  sort | uniq -c | sort -nr | head -10

Resposta a incidents

Ús elevat de memòria

Gravetat: crítica; pot provocar una terminació per OOM

1. Comproveu l’ús actual:

   ps aux | grep "[l]c "
   top -p $(pgrep -f "lc.*process")
   

2. Canvieu al mode optimitzat per a memòria:

   sudo systemctl stop lippycat-processor
   # Edit config: tcp_performance_mode: "memory"
   sudo systemctl start lippycat-processor
   

3. Reinicieu d’emergència si la memòria supera els límits:

   sudo systemctl restart lippycat-processor
   

Servei aturat

1. Comproveu l’estat i els registres recents:

   sudo systemctl status lippycat-processor
   journalctl -u lippycat-processor --lines=50
   

2. Intenteu reiniciar:

   sudo systemctl restart lippycat-processor
   sleep 5
   sudo systemctl status lippycat-processor
   

3. Si el reinici falla, proveu una configuració mínima:

   sudo systemctl stop lippycat-processor
   lc process --listen :55555 --insecure  # Minimal, no PCAP, no TLS
   

Desconnexions de Hunters

Els Hunters es reconnecten automàticament amb espera exponencial (vegeu el Capítol 7: Resiliència). Si els Hunters continuen desconnectats:

1. Comproveu l’estat del servei Hunter al node perifèric:

   ssh edge-node systemctl status lippycat-hunter
   

2. Verifiqueu la connectivitat de xarxa:

   ssh edge-node nc -zv processor.internal 55555
   

3. Comproveu si hi ha problemes amb els certificats TLS:

   journalctl -u lippycat-hunter --since "1 hour ago" | grep -i tls
   

Recollida de dades de diagnòstic

#!/bin/bash
# collect-diagnostics.sh
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
DIAG_DIR="/tmp/lippycat_diag_$TIMESTAMP"
mkdir -p "$DIAG_DIR"

echo "Collecting diagnostics..."

# System info
uname -a > "$DIAG_DIR/system.txt"
cat /etc/os-release >> "$DIAG_DIR/system.txt"

# Service status
systemctl status 'lippycat*' > "$DIAG_DIR/services.txt" 2>&1

# Process info
ps aux | grep "[l]c " > "$DIAG_DIR/processes.txt"
free -h > "$DIAG_DIR/memory.txt"
df -h > "$DIAG_DIR/disk.txt"

# Network
ip addr show > "$DIAG_DIR/interfaces.txt"
ss -tlnp | grep 55555 > "$DIAG_DIR/listeners.txt"

# Processor status (if running)
lc show status -P localhost:55555 --tls-ca /etc/lippycat/certs/ca.crt \
  > "$DIAG_DIR/processor_status.json" 2>&1
lc show topology -P localhost:55555 --tls-ca /etc/lippycat/certs/ca.crt \
  > "$DIAG_DIR/topology.json" 2>&1

# Recent logs
journalctl -u 'lippycat*' --since "2 hours ago" > "$DIAG_DIR/logs.txt"

# Configuration (sanitize if needed)
lc show config > "$DIAG_DIR/config.json" 2>&1

# Archive
tar -czf "/tmp/lippycat_diag_$TIMESTAMP.tar.gz" -C /tmp "lippycat_diag_$TIMESTAMP"
rm -rf "$DIAG_DIR"
echo "Saved: /tmp/lippycat_diag_$TIMESTAMP.tar.gz"

Manteniment

Gestió de l’emmagatzematge PCAP

Els fitxers PCAP s’acumulen ràpidament en producció. Configureu una neteja automatitzada:

#!/bin/bash
# pcap-cleanup.sh — run from cron
PCAP_DIR="/var/capture"
RETENTION_DAYS=30

# Remove old PCAP files
find "$PCAP_DIR" -name "*.pcap" -mtime +$RETENTION_DAYS -delete
find "$PCAP_DIR" -name "*.pcap.gz" -mtime +$RETENTION_DAYS -delete

# Remove empty directories
find "$PCAP_DIR" -type d -empty -delete

# Report disk usage
echo "PCAP storage: $(du -sh "$PCAP_DIR" | cut -f1)"

Afegiu-ho a cron:

# Daily PCAP cleanup at 3 AM
0 3 * * * /opt/scripts/pcap-cleanup.sh >> /var/log/pcap-cleanup.log 2>&1

Planificació de capacitat

Estimació de l’ús de disc

Estimació dels recursos del processador

Escaleu horitzontalment amb diversos processadors si un de sol no pot gestionar la càrrega (vegeu el Capítol 6: Topologia amb diversos processadors).

Llista de comprovació de seguretat

Executeu-la mensualment:

• El binari té les capacitats mínimes (getcap /usr/local/bin/lc)
• El fitxer de configuració té permisos restrictius (ls -la /etc/lippycat/config.yaml)
• Els certificats TLS no han caducat (openssl x509 -enddate -noout -in cert.crt)
• LIPPYCAT_PRODUCTION=true està definit (bloqueja --insecure)
• No hi ha Hunters no autoritzats connectats (lc list hunters -P ...)
• Els directoris PCAP tenen els permisos adequats
• Les regles del tallafoc restringeixen el port 55555 als amfitrions autoritzats

Actualització

1. Descarregueu o compileu la versió nova
2. Atureu el servei: sudo systemctl stop lippycat-processor
3. Substituïu el binari: sudo cp lc /usr/local/bin/
4. Restaureu les capacitats: sudo setcap cap_net_raw,cap_net_admin=eip /usr/local/bin/lc
5. Inicieu el servei: sudo systemctl start lippycat-processor
6. Verifiqueu: lc show status -P localhost:55555 --tls-ca ca.crt

Els Hunters es reconnectaran automàticament després que el processador es reiniciï.

Nivells d’escalat