Pular para o conteúdo principal

Guia de Solução de Problemas do OmniUPF

Índice​

  1. Visão Geral
  2. Ferramentas de Diagnóstico
  3. Problemas de Instalação
  4. Problemas de Configuração
  5. Problemas de Associação PFCP
  6. Problemas de Processamento de Pacotes
  7. Problemas com XDP e eBPF
  8. Problemas de Desempenho
  9. Problemas Específicos do Hypervisor
  10. Problemas com NIC e Driver
  11. Falhas na Estabelecimento de Sessão
  12. Problemas de Bufferização

Visão Geral​

Este guia fornece procedimentos sistemáticos de solução de problemas para problemas comuns do OmniUPF. Cada seção inclui sintomas, etapas de diagnóstico, causas raiz e procedimentos de resolução.

Lista de Verificação Rápida de Diagnóstico​

Antes de um diagnóstico mais profundo, verifique:

# 1. Verifique se o OmniUPF está em execução
systemctl status omniupf

# 2. Verifique a associação PFCP
curl http://localhost:8080/api/v1/upf_pipeline

# 3. Verifique se os mapas eBPF estão carregados
ls /sys/fs/bpf/

# 4. Verifique se o programa XDP está anexado
ip link show | grep -i xdp

# 5. Verifique os logs do kernel em busca de erros
dmesg | tail -50
journalctl -u omniupf -n 50

Ferramentas de Diagnóstico​

API REST do OmniUPF​

Verifique o status do UPF:

curl http://localhost:8080/api/v1/upf_status

Verifique as associações PFCP:

curl http://localhost:8080/api/v1/upf_pipeline

Verifique a contagem de sessões:

curl http://localhost:8080/api/v1/sessions | jq 'length'

Verifique a capacidade do mapa eBPF:

curl http://localhost:8080/api/v1/map_info

Verifique as estatísticas de pacotes:

curl http://localhost:8080/api/v1/packet_stats

Verifique as estatísticas do XDP:

curl http://localhost:8080/api/v1/xdp_stats

Inspeção do Mapa eBPF​

Liste todos os mapas eBPF:

ls -lh /sys/fs/bpf/
bpftool map list

Mostre os detalhes do mapa:

bpftool map show
bpftool map dump name pdr_map_downlin

Conte as entradas no mapa:

bpftool map dump name far_map | grep -c "key:"

Inspeção do Programa XDP​

Verifique se o programa XDP está anexado:

ip link show eth0 | grep xdp

Liste todos os programas XDP:

bpftool net list

Mostre os detalhes do programa XDP:

bpftool prog show

Despeje as estatísticas do XDP:

bpftool prog dump xlated name xdp_upf_func

Depuração de Rede​

Capture o tráfego PFCP na N4 (plano de controle):

# PFCP não é processado pelo XDP, tcpdump funciona normalmente
tcpdump -i eth0 -n udp port 8805 -w /tmp/pfcp_traffic.pcap

Capture o tráfego GTP-U na N3 (requer captura fora de banda):

# AVISO: O tcpdump padrão no host UPF NÃO PODE capturar pacotes processados pelo XDP!
# O XDP processa GTP-U antes que a pilha de rede do kernel veja os pacotes.

# Use captura fora de banda em vez disso:
# 1. TAP de Rede entre gNB e UPF
# 2. Espelhamento de porta de switch/SPAN para copiar o tráfego N3
# 3. Espelhamento de porta de switch virtual para VM de analisador

# No host de análise/monitoramento (NÃO no UPF):
# tcpdump -i <mirror_interface> -n udp port 2152 -w /tmp/n3_capture.pcap

# Ou use a API de estatísticas para contagens de pacotes:
curl http://localhost:8080/api/v1/packet_stats
curl http://localhost:8080/api/v1/n3n6_stats

Monitore os contadores de pacotes:

watch -n 1 'ip -s link show eth0'

Verifique a tabela de roteamento:

ip route show
ip route get 10.45.0.100  # Verifique a rota para o IP do UE

Verifique a tabela ARP:

ip neigh show

Problemas de Instalação​

Problema: "sistema de arquivos eBPF não montado"​

Sintomas:

ERRO[0000] falha ao carregar objetos eBPF: monte o sistema de arquivos bpf em /sys/fs/bpf

Causa: sistema de arquivos eBPF não montado

Resolução:

# Monte o sistema de arquivos eBPF
sudo mount bpffs /sys/fs/bpf -t bpf

# Torne persistente (adicione ao /etc/fstab)
echo "bpffs /sys/fs/bpf bpf defaults 0 0" | sudo tee -a /etc/fstab

# Verifique o montado
mount | grep bpf

Problema: Versão do kernel muito antiga​

Sintomas:

ERRO[0000] versão do kernel 5.4.0 é muito antiga, o mínimo requerido é 5.15.0

Causa: versão do kernel Linux abaixo do requisito mínimo

Resolução:

# Verifique a versão do kernel
uname -r

# Atualize o kernel (Ubuntu/Debian)
sudo apt update
sudo apt install linux-generic-hwe-22.04
sudo reboot

# Verifique o novo kernel
uname -r  # Deve ser >= 5.15.0

Problema: Dependência libbpf ausente​

Sintomas:

erro ao carregar bibliotecas compartilhadas: libbpf.so.0: não é possível abrir o arquivo de objeto compartilhado

Causa: biblioteca libbpf não instalada

Resolução:

# Instale libbpf (Ubuntu/Debian)
sudo apt update
sudo apt install libbpf-dev

# Verifique a instalação
ldconfig -p | grep libbpf

Problemas de Configuração​

Problema: Arquivo de configuração inválido​

Sintomas:

ERRO[0000] não foi possível ler o arquivo de configuração: erros de deserialização

Causa: erro de sintaxe no arquivo de configuração Elixir

Resolução:

# Verifique a sintaxe do arquivo de configuração
cd /opt/omniupf && bin/upf_ex eval "IO.puts(:ok)"

# Problemas comuns:
# - Faltando aspas em torno de valores de string
# - Sintaxe Elixir incorreta (por exemplo, usando : em vez de =)
# - Strings ou colchetes não fechados

# O arquivo de configuração está em /etc/omniupf/runtime.exs
# Exemplo de sintaxe correta:
# xdp_interfaces = "eth0"
# xdp_attach_mode = "generic"
# api_port = 8080
# pfcp_address = "10.0.0.1"

Problema: Nome da interface não encontrado​

Sintomas:

ERRO[0000] interface eth0 não encontrada

Causa: interface configurada não existe

Resolução:

# Liste todas as interfaces de rede
ip link show

# Verifique o status da interface
ip addr show eth0

# Se a interface tiver um nome diferente, atualize /etc/omniupf/runtime.exs:
# xdp_interfaces = "ens1f0"  # Use o nome real da interface

# Para VMs, verifique o esquema de nomenclatura da interface
ls /sys/class/net/

Problema: Porta já em uso​

Sintomas:

ERRO[0000] falha ao iniciar o servidor API: endereço já em uso

Causa: Porta 8080, 8805 ou 9090 já vinculada por outro processo

Resolução:

# Encontre o processo usando a porta
sudo lsof -i :8080
sudo netstat -tulpn | grep :8080

# Mate o processo conflitante
sudo kill <PID>

# Ou altere a porta do OmniUPF em /etc/omniupf/runtime.exs
# api_port = 8081
# pfcp_port = 8806

Problema: ID de nó PFCP inválido​

Sintomas:

ERRO[0000] pfcp_node_id inválido: deve ser um endereço IPv4 válido

Causa: ID de nó PFCP não é um endereço IPv4 válido

Resolução:

# Em /etc/omniupf/runtime.exs
# Correto: Use o endereço IP (não o nome do host)
node_id = "10.100.50.241"

# Incorreto:
# node_id = "localhost"
# node_id = "upf.example.com"

Problemas de Associação PFCP​

Problema: Nenhuma associação PFCP estabelecida​

Sintomas:

  • A interface da Web mostra "Sem associações"
  • Logs do SMF mostram "Falha na configuração da associação PFCP"

Diagnóstico:

# 1. Verifique se o servidor PFCP está escutando
sudo netstat -ulpn | grep 8805

# 2. Verifique as regras do firewall
sudo iptables -L -n | grep 8805
sudo ufw status

# 3. Capture o tráfego PFCP
tcpdump -i any -n udp port 8805 -vv

# 4. Verifique as associações PFCP via API
curl http://localhost:8080/api/v1/upf_pipeline

Causas Comuns e Resoluções:

Firewall bloqueando PFCP​

Resolução:

# Permita o tráfego PFCP (UDP 8805)
sudo ufw allow 8805/udp
sudo iptables -A INPUT -p udp --dport 8805 -j ACCEPT

ID de nó PFCP incorreto​

Resolução:

# Em /etc/omniupf/runtime.exs, defina o ID do nó para o IP correto da interface N4
node_id = "10.100.50.241"    # Deve corresponder ao IP na rede N4

Rede inacessível ao SMF​

Resolução:

# Teste a conectividade com o SMF
ping <SMF_IP>

# Verifique o roteamento para o SMF
ip route get <SMF_IP>

# Adicione a rota se estiver faltando
sudo ip route add <SMF_NETWORK>/24 via <GATEWAY>

SMF configurado com IP do UPF incorreto​

Resolução:

  • Verifique a configuração do SMF para o endereço do UPF
  • Certifique-se de que o SMF tenha o IP do pfcp_node_id do UPF configurado
  • Verifique se o SMF pode rotear para a rede N4 do UPF

Problema: Falhas de heartbeat PFCP​

Sintomas:

WARN[0030] tempo limite de heartbeat PFCP para associação 10.100.50.10

Diagnóstico:

# Verifique as estatísticas PFCP
curl http://localhost:8080/api/v1/upf_pipeline | jq '.associations[] | {remote_id, uplink_teid_count}'

# Monitore os logs de heartbeat
journalctl -u omniupf -f | grep heartbeat

Causas e Resoluções:

Perda de pacotes na rede​

Resolução:

# Verifique a perda de pacotes para o SMF
ping -c 100 <SMF_IP> | grep loss

# Se a perda for alta, investigue a rede:
# - Verifique o status do link
# - Verifique a saúde do switch/roteador
# - Verifique se há congestionamento

Intervalo de heartbeat muito agressivo​

Resolução:

# Em /etc/omniupf/runtime.exs
heartbeat_interval_ms = 30_000    # Aumente de 5000 para 30000 ms
heartbeat_retries = 5             # Aumente as tentativas
heartbeat_timeout_ms = 10_000     # Aumente o tempo limite

Problemas de Processamento de Pacotes​

Problema: Nenhum pacote fluindo (contadores RX/TX em 0)​

Sintomas:

  • A página de estatísticas mostra 0 pacotes RX/TX
  • UE não consegue estabelecer sessão de dados

Diagnóstico:

# 1. Verifique se o programa XDP está anexado
ip link show eth0 | grep xdp

# 2. Verifique se a interface está ATIVA
ip link show eth0

# 3. Verifique as estatísticas de pacotes (ciente do XDP)
# Nota: tcpdump não pode ver pacotes GTP-U processados pelo XDP
curl http://localhost:8080/api/v1/packet_stats

Resoluções:

Programa XDP não anexado​

Resolução:

# Reinicie o OmniUPF para re-anexar o XDP
sudo systemctl restart omniupf

# Verifique a anexação
ip link show eth0 | grep xdp
bpftool net list

Resolução:

# Ative a interface
sudo ip link set eth0 up

# Verifique o status do link
ethtool eth0 | grep "Link detected"

# Se o link estiver inativo, verifique a conexão física ou a configuração de rede da VM

Interface configurada incorretamente​

Resolução:

# Em /etc/omniupf/runtime.exs
xdp_interfaces = "ens1f0"    # Use o nome real da interface do 'ip link show'

Problema: Pacotes recebidos mas não encaminhados (alta taxa de descarte)​

Sintomas:

  • Contadores RX aumentando, mas contadores TX não
  • Taxa de descarte > 1%

Diagnóstico:

# Verifique as estatísticas de descarte
curl http://localhost:8080/api/v1/xdp_stats | jq '.drop'

# Verifique as estatísticas de rota
curl http://localhost:8080/api/v1/packet_stats | jq '.route_stats'

# Monitore os descartes de pacotes
watch -n 1 'curl -s http://localhost:8080/api/v1/packet_stats | jq ".total_rx, .total_tx, .total_drop"'

Causas Comuns:

Sem correspondência PDR (TEID desconhecido ou IP do UE)​

Resolução:

# Verifique se as sessões existem
curl http://localhost:8080/api/v1/sessions

# Se não houver sessões, verifique:
# - A associação PFCP está estabelecida
# - O SMF criou sessões
# - O estabelecimento da sessão foi bem-sucedido

# Verifique as entradas do mapa PDR
bpftool map dump name pdr_map_teid_ip | grep -c key
bpftool map dump name pdr_map_downlin | grep -c key

Falhas de roteamento​

Resolução:

# Verifique falhas de lookup FIB
curl http://localhost:8080/api/v1/packet_stats | jq '.route_stats'

# Teste o roteamento para o IP do UE
ip route get 10.45.0.100

# Adicione a rota que está faltando
sudo ip route add 10.45.0.0/16 dev eth1  # Roteie o pool do UE para N6

Limitação de taxa QER​

Sintomas:

  • Throughput abaixo do esperado
  • Tráfego limitado a uma taxa específica
  • Contadores de volume URR mostram comportamento de platô
  • Contadores de descarte do XDP aumentando durante picos de tráfego

Diagnóstico:

  1. Verifique o MBR configurado para a sessão:

    # Encontre o ID do QER da sessão
    curl http://localhost:8080/api/v1/pfcp_sessions | jq '.data[] | select(.ue_ip == "10.45.0.1")'

    # Procure a configuração do QER
    curl http://localhost:8080/api/v1/qer_map | jq '.data[] | select(.qer_id == 1)'

  2. Verifique o status do portão:

    # O status do portão deve ser 0 (ABERTO) para uplink e downlink
    curl http://localhost:8080/api/v1/qer_map | jq '.data[] | {qer_id, ul_gate: .ul_gate_status, dl_gate: .dl_gate_status}'

  3. Calcule o throughput real a partir do URR:

    # Consulte os contadores de volume URR em dois pontos no tempo
    curl http://localhost:8080/api/v1/urr_map | jq '.data[] | select(.urr_id == 0)'

    # Calcule o throughput (manual):
    # throughput_kbps = (volume_delta_bytes × 8) / time_delta_seconds / 1000

  4. Compare MBR vs. throughput real:

    • Throughput esperado ≈ 95-98% do MBR (devido à sobrecarga do protocolo)
    • Se o throughput estiver significativamente abaixo do MBR, verifique outros gargalos
    • Se o throughput corresponder exatamente ao MBR, a limitação de taxa está funcionando conforme o esperado

Resolução:

  • Se o MBR for muito baixo: Solicite ao SMF que atualize o QER com um MBR mais alto via Modificação de Sessão PFCP
  • Se o portão estiver fechado: Investigue por que o SMF fechou o portão (política, cota ou erro)
  • Se a limitação de taxa for inesperada: Verifique a configuração da política do SMF e o perfil de QoS

Entendendo a Aplicação do MBR:

O OmniUPF usa um algoritmo de janela deslizante para impor limites de MBR com precisão em nanossegundos no caminho de dados eBPF. Veja o Guia de Gerenciamento de Regras - Mecanismo de Aplicação de MBR para uma explicação detalhada sobre:

  • Como o tamanho do pacote e a taxa determinam decisões de descarte
  • Por que o throughput observado difere do MBR configurado
  • Limitação de taxa por direção (uplink/downlink)
  • Comportamento da janela deslizante de 5ms

Cenários Comuns:

  • Chamadas VoIP caindo: Verifique se o MBR é suficiente para a taxa de bits do codec (G.711 = ~80 kbps)
  • Bufferização de streaming de vídeo: Certifique-se de que o MBR > taxa de bits do vídeo + sobrecarga (1080p = ~5-10 Mbps)
  • Tráfego de pico: Pequenos picos permitidos dentro da janela de 5ms, taxa de tráfego sustentada limitada

Sintomas:

  • Pacotes RX N3, mas nenhum pacote TX N3 (problema de downlink)
  • Pacotes RX N6, mas nenhum pacote TX N6 (problema de uplink)

Diagnóstico:

# Verifique as estatísticas da interface N3/N6 (método ciente do XDP)
curl http://localhost:8080/api/v1/n3n6_stats
curl http://localhost:8080/api/v1/packet_stats

# Nota: O tcpdump padrão não pode capturar tráfego GTP-U processado pelo XDP
# Use a API de estatísticas ou xdpdump para análise de tráfego
# Veja a seção "Captura de Pacotes com XDP" para detalhes

Falha de Uplink (RX N3, sem TX N6):

Causa: Nenhuma ação FAR ou problema de roteamento para N6

Resolução:

# Verifique se o FAR tem ação FORWARD
curl http://localhost:8080/api/v1/sessions | jq '.[].fars[] | select(.applied_action == 2)'

# Verifique se a rota N6 existe
ip route get 8.8.8.8  # Teste a rota para a internet

# Adicione a rota padrão se estiver faltando
sudo ip route add default via <N6_GATEWAY> dev eth1

Falha de Downlink (RX N6, sem TX N3):

Causa: Nenhuma PDR de downlink ou encapsulamento GTP ausente

Resolução:

# Verifique se a PDR de downlink existe para o IP do UE
curl http://localhost:8080/api/v1/sessions | jq '.[].pdrs[] | select(.pdi.ue_ip_address)'

# Verifique se o FAR tem OUTER_HEADER_CREATION
curl http://localhost:8080/api/v1/sessions | jq '.[].fars[] | .outer_header_creation'

# Verifique a acessibilidade do gNB
ping <GNB_N3_IP>

Problemas com XDP e eBPF​

Para configuração detalhada do XDP, seleção de modo e solução de problemas, veja o Guia de Modos XDP.

Problema: Programa XDP falhou ao carregar​

Sintomas:

ERRO[0000] falha ao carregar o programa XDP: argumento inválido

Diagnóstico:

# Verifique o suporte XDP do kernel
grep XDP /boot/config-$(uname -r)

# Deve mostrar:
# CONFIG_XDP_SOCKETS=y
# CONFIG_BPF=y
# CONFIG_BPF_SYSCALL=y

# Verifique dmesg para erro detalhado
dmesg | grep -i bpf

Causas e Resoluções:

Kernel não possui suporte a XDP​

Resolução:

# Recompile o kernel com suporte a XDP ou atualize para um kernel mais recente
# Ubuntu 22.04+ tem XDP habilitado por padrão
sudo apt install linux-generic-hwe-22.04
sudo reboot

Falha de verificação do programa XDP​

Resolução:

# Verifique os logs do OmniUPF em busca de erros de verificação
journalctl -u omniupf | grep verifier

# Problemas comuns:
# - A complexidade do eBPF excede os limites (aumente os limites do kernel)
# - Acesso à memória inválido (bug no código eBPF)

# Aumente o nível de log do verificador eBPF para depuração
sudo sysctl kernel.bpf_stats_enabled=1

Problema: Contagem de abortos do XDP aumentando​

Sintomas:

  • Estatísticas do XDP mostram abortos > 0
  • Aumentando os descartes de pacotes

Diagnóstico:

# Verifique a contagem de abortos do XDP
curl http://localhost:8080/api/v1/xdp_stats | jq '.aborted'

# Monitore as estatísticas do XDP
watch -n 1 'curl -s http://localhost:8080/api/v1/xdp_stats'

Causa: o programa eBPF encontrou um erro em tempo de execução

Resolução:

# Verifique os logs do kernel para erros eBPF
dmesg | grep -i bpf

# Reinicie o OmniUPF para recarregar o programa eBPF
sudo systemctl restart omniupf

# Se o problema persistir, ative o registro do eBPF (requer recompilação):
# Compile o OmniUPF com BPF_ENABLE_LOG=1

Problema: Mapa eBPF cheio (capacidade esgotada)​

Sintomas:

  • Estabelecimento de sessão falha
  • Capacidade do mapa em 100%

Diagnóstico:

# Verifique a capacidade do mapa
curl http://localhost:8080/api/v1/map_info | jq '.[] | {map_name, capacity, used, usage_percent}'

# Identifique mapas cheios
curl http://localhost:8080/api/v1/map_info | jq '.[] | select(.usage_percent > 90)'

Mitigação Imediata:

# 1. Identifique sessões obsoletas
curl http://localhost:8080/api/v1/sessions | jq '.[] | {seid, uplink_teid, created_at}'

# 2. Solicite ao SMF que exclua sessões antigas
# (via interface de administração do SMF ou API)

# 3. Monitore a diminuição do uso do mapa
watch -n 5 'curl -s http://localhost:8080/api/v1/map_info | jq ".[] | select(.map_name==\"pdr_map_downlin\") | .usage_percent"'

Resolução a Longo Prazo:

# Em /etc/omniupf/runtime.exs
max_sessions = 200_000    # Aumente de 100_000

# Ou defina tamanhos individuais de mapa
far_map_size = 400_000
qer_map_size = 200_000

Importante: Alterar tamanhos de mapa requer reinício do OmniUPF e limpa todas as sessões existentes.

Problemas de Desempenho​

Problema: Throughput baixo (abaixo do esperado)​

Sintomas:

  • Throughput < 1 Gbps apesar de NIC capaz
  • Alta utilização da CPU

Diagnóstico:

# Verifique a taxa de pacotes
curl http://localhost:8080/api/v1/packet_stats | jq '.total_rx, .total_tx'

# Verifique as estatísticas da NIC
ethtool -S eth0 | grep -i drop

# Verifique o modo XDP
ip link show eth0 | grep xdp

Resoluções:

Usando modo XDP genérico​

Resolução:

# Em /etc/omniupf/runtime.exs
xdp_attach_mode = "native"    # Requer NIC/drivers compatíveis com XDP

Gargalo de núcleo único​

Resolução:

# Habilite RSS (Receive Side Scaling) na NIC
ethtool -L eth0 combined 4  # Use 4 filas RX/TX

# Verifique se o RSS está habilitado
ethtool -l eth0

# Prenda interrupções a CPUs específicas
# Veja /proc/interrupts e use irqbalance ou afinidade manual

Buffer bloat​

Resolução:

Os limites de buffer são gerenciados pelo plano de controle Elixir.
Verifique a configuração do buffer em /etc/omniupf/runtime.exs.

Problema: Alta latência​

Sintomas:

  • Latência de ping > 50ms
  • Degradação da experiência do usuário

Diagnóstico:

# Teste a latência para o UE
ping -c 100 <UE_IP> | grep avg

# Verifique pacotes em buffer
curl http://localhost:8080/api/v1/upf_buffer_info | jq '.total_packets_buffered'

# Verifique o desempenho do cache de rota
curl http://localhost:8080/api/v1/packet_stats | jq '.route_stats'

Resoluções:

Pacotes sendo excessivamente armazenados em buffer​

Resolução:

# Verifique por que os pacotes estão armazenados em buffer
curl http://localhost:8080/api/v1/upf_buffer_info | jq '.buffers[] | {far_id, packet_count, direction}'

# Limpe os buffers se estiverem travados
# (reinicie o OmniUPF ou acione a modificação da sessão PFCP para aplicar FAR)

Latência de lookup FIB​

Resolução:

# Certifique-se de que o cache de rota esteja habilitado (opção de tempo de compilação)
# Compile com BPF_ENABLE_ROUTE_CACHE=1

# Otimize a tabela de roteamento
# Use menos rotas, mais específicas em vez de muitas pequenas rotas

Problema: Descartes de pacotes sob carga​

Sintomas:

  • A taxa de descarte aumenta com o tráfego
  • Erros RX na NIC

Diagnóstico:

# Verifique os erros da NIC
ethtool -S eth0 | grep -E "drop|error|miss"

# Verifique o tamanho do buffer de anel
ethtool -g eth0

# Monitore os descartes em tempo real
watch -n 1 'ethtool -S eth0 | grep -E "drop|miss"'

Resolução:

# Aumente o tamanho do buffer de recepção RX
ethtool -G eth0 rx 4096

# Aumente o tamanho do buffer de transmissão TX
ethtool -G eth0 tx 4096

# Verifique as novas configurações
ethtool -g eth0

Problemas Específicos do Hypervisor​

Para instruções passo a passo de configuração do hypervisor, veja o Guia de Modos XDP.

Proxmox: XDP não funcionando na VM​

Sintomas:

  • Não é possível anexar o programa XDP em modo nativo
  • Apenas o modo genérico funciona

Causa: VM usando rede em bridge sem SR-IOV

Resolução:

Opção 1: Usar modo genérico (mais simples)

# Em /etc/omniupf/runtime.exs
xdp_attach_mode = "generic"

Opção 2: Configurar passthrough SR-IOV

# No host Proxmox:
# 1. Ativar IOMMU
nano /etc/default/grub
# Adicionar: intel_iommu=on iommu=pt
update-grub
reboot

# 2. Criar VFs
echo 4 > /sys/class/net/eth0/device/sriov_numvfs

# 3. Atribuir VF à VM na interface do Proxmox
# Hardware → Adicionar → Dispositivo PCI → Selecionar VF

Em /etc/omniupf/runtime.exs:

xdp_interfaces = "ens1f0"    # VF SR-IOV
xdp_attach_mode = "native"

VMware: Modo promíscuo necessário​

Sintomas:

  • Pacotes não recebidos pelo OmniUPF

Causa: vSwitch bloqueando endereços MAC não correspondentes

Resolução:

# Ativar modo promíscuo no vSwitch (no vSphere Client):
# 1. Selecionar vSwitch → Editar Configurações
# 2. Segurança → Modo Promíscuo: Aceitar
# 3. Segurança → Mudanças de Endereço MAC: Aceitar
# 4. Segurança → Transmissões Forjadas: Aceitar

VirtualBox: Desempenho muito baixo​

Sintomas:

  • Throughput < 100 Mbps

Causa: VirtualBox não suporta SR-IOV ou XDP nativo

Resolução:

# Em /etc/omniupf/runtime.exs
xdp_attach_mode = "generic"    # Única opção para VirtualBox

Otimize as configurações do VirtualBox:

  • Use adaptador VirtIO-Net (se disponível)
  • Ative o modo promíscuo "Permitir Tudo"
  • Aloque mais núcleos de CPU para a VM
  • Use rede em bridge em vez de NAT
  • Considere migrar para KVM/Proxmox para melhor desempenho

Problemas de NIC e Driver​

Problema: Driver de NIC não suporta XDP​

Sintomas:

ERRO[0000] falha ao anexar programa XDP: operação não suportada

Diagnóstico:

# Verificar driver de NIC
ethtool -i eth0 | grep driver

# Verificar se o driver suporta XDP
modinfo <driver_name> | grep -i xdp

# Listar interfaces compatíveis com XDP
ip link show | grep -B 1 "xdpgeneric\|xdpdrv\|xdpoffload"

Resolução:

Opção 1: Usar modo genérico

# Em /etc/omniupf/runtime.exs
xdp_attach_mode = "generic"

Opção 2: Atualizar driver de NIC

# Verificar atualizações de driver (Ubuntu)
sudo apt update
sudo apt install linux-modules-extra-$(uname -r)

# Ou instalar driver específico do fornecedor
# Exemplo para Intel:
# Baixar de https://downloadcenter.intel.com/

Opção 3: Substituir NIC

# Usar NIC compatível com XDP:
# - Intel X710, E810
# - Mellanox ConnectX-5, ConnectX-6
# - Broadcom BCM57xxx (driver bnxt_en)

Problema: Driver falha ou causa pânico no kernel​

Sintomas:

  • Pânico no kernel após anexar XDP
  • NIC para de responder

Diagnóstico:

# Verificar logs do kernel
dmesg | tail -100

# Verificar bugs do driver
journalctl -k | grep -E "BUG:|panic:"

Resolução:

# 1. Atualizar kernel e drivers
sudo apt update
sudo apt upgrade
sudo reboot

# 2. Em /etc/omniupf/runtime.exs, desativar offload XDP (usar apenas nativo)
# xdp_attach_mode = "native"

# 3. Usar modo genérico como solução alternativa
# xdp_attach_mode = "generic"

# 4. Relatar bug ao fornecedor da NIC ou equipe do kernel Linux

Problema: Erros intermitentes de SLAAC IPv6 / checksum UDP (generic-XDP + virtio)​

Sintomas:

# UEs IPv6 intermitentemente (~50%) nunca formam um endereço global via SLAAC.
# O RA é emitido pelo UPF, mas nunca é visto pelo RAN.
# No eNB/gNB (ou qualquer host downstream) o contador de erro de checksum UDP do kernel
# aumenta, um por RA descartado:
nstat -az | grep UdpInCsumErrors      # incrementa durante tentativas de SLAAC com falha
  • Afeta apenas SLAAC IPv6 / Anúncios de Roteador — os dados do plano do usuário estão normais.
  • Ocorre apenas quando um SGW-U e PGW-U de um bearer estão em membros de pool diferentes (dividido); um bearer SGW-U+PGW-U na mesma caixa sempre tem sucesso.

Causa: O Anúncio de Roteador é gerado em espaço do usuário (plano de controle), então seu buffer de socket é marcado para offload de checksum TX (CHECKSUM_PARTIAL; a NIC do datapath tem tx-checksum-ip-generic: on). Em um datapath XDP em modo genérico, o pacote encaminhado é um skb do kernel: quando um membro SGW-U de pool dividido retransmite esse RA, ele reescreve o IP externo + TEID e zera udp->check, mas o skb mantém o csum_start/csum_offset de offload agora obsoleto. Na saída, a NIC (virtio) recalcula o checksum UDP sobre o pacote modificado a partir desse offset obsoleto, produzindo um checksum errado, e o receptor o descarta. O tráfego do plano do usuário XDP nativo não é afetado porque é construído em eBPF com CHECKSUM_NONE (um checksum zero genuíno), então a NIC nunca o recalcula — razão pela qual apenas o SLAAC falha. Modos XDP nativo/offload não enfrentam isso (sem skb, sem recalculo de offload); é específico para modo genérico em uma NIC com offload de checksum (por exemplo, virtio).

Resolução:

# Desativar offload de checksum TX nas NIC(s) do datapath para que o kernel calcule o
# checksum UDP inline (corretamente) para pacotes de controle originados em espaço do usuário. O XDP
# plano de dados contorna o caminho de checksum do kernel, então a taxa de encaminhamento não é afetada.
ethtool -K <n3_iface> tx off
ethtool -K <n6_iface> tx off

# Verificar (deve ler "off"):
ethtool -k <n3_iface> | awk '/^tx-checksumming/{print}'

# Re-testar: SLAAC agora deve ter sucesso para cada bearer e UdpInCsumErrors deve permanecer estável.

Torne isso persistente em sua implantação (por exemplo, na unidade de inicialização da NIC do datapath) para que sobreviva a reinicializações. Onde a NIC suporta, o modo XDP nativo (xdp_attach_mode: native) também evita o problema completamente.

Falhas na Estabelecimento de Sessão​

Problema: Falha na estabelecimento de sessão​

Sintomas:

  • SMF relata falha na estabelecimento de sessão
  • UE não consegue estabelecer sessão PDU

Veja Referência de Códigos de Causa PFCP para cenários comuns de falha e resoluções.

Diagnóstico:

# Verificar logs do OmniUPF para erros de sessão
journalctl -u omniupf | grep -i "session establishment"

# Verificar contagem de sessões PFCP
curl http://localhost:8080/api/v1/sessions | jq 'length'

# Capturar tráfego PFCP durante a estabelecimento de sessão
tcpdump -i any -n udp port 8805 -w /tmp/pfcp_session.pcap

Causas Comuns:

Capacidade do mapa cheia​

Resolução:

# Verificar uso do mapa
curl http://localhost:8080/api/v1/map_info | jq '.[] | select(.usage_percent > 90)'

# Aumentar capacidade (veja seção de mapa eBPF cheia acima)

Parâmetros PDR/FAR inválidos​

Resolução:

# Verificar logs do OmniUPF para erros de validação
journalctl -u omniupf | grep -E "invalid|error" | tail -20

# Problemas comuns:
# - Endereço IP UE inválido (0.0.0.0 ou duplicado)
# - TEID inválido (0 ou duplicado)
# - FAR ausente para PDR
# - Ação FAR inválida

# Verificar configuração do SMF e parâmetros da sessão

Recurso não suportado (UEIP/FTUP)​

Resolução:

# Em /etc/omniupf/runtime.exs
feature_ueip = true
ueip_pool = "10.60.0.0/16"

feature_ftup = true
teid_pool_start = 1
teid_pool_end = 100_000

Problemas de Buffer​

Problema: Pacotes presos no buffer​

Sintomas:

  • Contagem de pacotes em buffer aumentando
  • Pacotes não entregues após a transferência

Diagnóstico:

# Verificar estatísticas do buffer
curl http://localhost:8080/api/v1/upf_buffer_info

# Verificar buffers FAR individuais
curl http://localhost:8080/api/v1/upf_buffer_info | jq '.buffers[] | {far_id, packet_count, oldest_packet_ms}'

# Monitorar tamanho do buffer
watch -n 5 'curl -s http://localhost:8080/api/v1/upf_buffer_info | jq ".total_packets_buffered"'

Causas & Resoluções:

FAR nunca atualizado para FORWARD​

Causa: SMF nunca enviou Modificação de Sessão PFCP para aplicar FAR

Resolução:

# Verificar status do FAR
curl http://localhost:8080/api/v1/sessions | jq '.[].fars[] | {far_id, applied_action}'

# Ação BUFF = 1 (buffering)
# Ação FORW = 2 (forwarding)

# Se preso no estado BUFF, solicitar ao SMF que:
# - Envie Solicitação de Modificação de Sessão PFCP
# - Atualize FAR com ação FORW

TTL do buffer expirado​

Causa: Pacotes expiraram antes da atualização do FAR

Resolução: O TTL do buffer é gerenciado pelo plano de controle Elixir. Verifique a configuração do buffer em /etc/omniupf/runtime.exs.

Overflow do buffer​

Causa: Muitos pacotes em buffer por FAR

Resolução: Os limites do buffer são gerenciados pelo plano de controle Elixir. Verifique a configuração do buffer em /etc/omniupf/runtime.exs.

Depuração Avançada​

Ativar Registro de Depuração​

# Em /etc/omniupf/runtime.exs
log_level = :debug    # :debug | :info | :warning | :error
# Reiniciar OmniUPF com registro de depuração
sudo systemctl restart omniupf

# Monitorar logs em tempo real
journalctl -u omniupf -f --output cat

Rastreamento de Programa eBPF​

# Rastrear execução do programa eBPF (requer bpftrace)
sudo bpftrace -e 'tracepoint:xdp:* { @[probe] = count(); }'

# Rastrear operações de mapa
sudo bpftrace -e 'tracepoint:bpf:bpf_map_lookup_elem { printf("%s\n", str(args->map_name)); }'

Captura de Pacotes com XDP​

Entendendo as Limitações da Captura de Pacotes XDP:

O XDP processa pacotes antes da pilha de rede do kernel, então o tcpdump padrão não pode ver o tráfego processado pelo XDP. Pacotes GTP-U (porta UDP 2152) na N3 são processados pelo XDP e não aparecerão no tcpdump no host UPF.

Métodos Recomendados para Análise de Tráfego:

# Método 1: Usar API de estatísticas para monitoramento (RECOMENDADO)
curl http://localhost:8080/api/v1/xdp_stats
curl http://localhost:8080/api/v1/packet_stats | jq
curl http://localhost:8080/api/v1/n3n6_stats

# Método 2: Capturar tráfego PFCP (não afetado pelo XDP)
tcpdump -i any -n udp port 8805 -w /tmp/pfcp.pcap

# Método 3: Captura de pacotes fora de banda (RECOMENDADO para GTP-U)
# Use TAP de rede ou espelhamento de porta de switch para capturar tráfego
# Exemplos:
# - TAP físico entre gNB e UPF
# - Porta de espelhamento do switch copiando tráfego N3 para analisador
# - Espelhamento de porta de switch virtual no hypervisor
#
# No host de captura (NÃO no UPF):
# tcpdump -i <mirror_interface> -n udp port 2152 -w /tmp/n3_mirror.pcap

Exemplos de Configuração de Captura Fora de Banda:

Rede Física:

# Usar um TAP de rede ou configurar espelhamento de porta do switch
# Exemplo: configuração SPAN de switch Cisco
(config)# monitor session 1 source interface Gi1/0/1
(config)# monitor session 1 destination interface Gi1/0/24

# No host de monitoramento conectado a Gi1/0/24:
tcpdump -i eth0 -n udp port 2152 -w /tmp/n3_capture.pcap

Ambiente Virtual (VMware, KVM, etc.):

# Configurar espelhamento de porta de switch virtual para enviar tráfego UPF para VM analisadora
# Exemplo: ponte Linux com tcpdump em VM diferente
# No hypervisor, espelhar a interface N3 do UPF para a interface do analisador

# Na VM analisadora:
tcpdump -i eth1 -n udp port 2152 -w /tmp/n3_virtual.pcap

Por que Captura Fora de Banda é Necessária:

  • O XDP contorna completamente a pilha de rede do kernel
  • Pacotes são processados no driver da NIC ou hardware
  • O tcpdump baseado em host vê pacotes DEPOIS do processamento XDP (tarde demais)
  • A captura fora de banda vê o tráfego bruto antes do processamento do UPF

O que você PODE Capturar no Host UPF:

  • ✅ Tráfego PFCP (UDP 8805) - plano de controle, não processado pelo XDP
  • ✅ Respostas da API e métricas
  • ❌ Tráfego GTP-U (UDP 2152) - plano de dados, processado pelo XDP

Obtendo Ajuda​

Se os passos de solução de problemas não resolverem seu problema:

  1. Coletar informações de diagnóstico:

    # Informações do sistema
    uname -a
    cat /etc/os-release

    # Informações do OmniUPF
    curl http://localhost:8080/api/v1/upf_status
    curl http://localhost:8080/api/v1/map_info
    curl http://localhost:8080/api/v1/packet_stats

    # Logs
    journalctl -u omniupf --since "1 hour ago" > /tmp/omniupf.log
    dmesg > /tmp/dmesg.log

    # Informações de rede
    ip addr > /tmp/network.txt
    ip route >> /tmp/network.txt
    ethtool eth0 >> /tmp/network.txt

  2. Relatar problema com:

    • Versão do OmniUPF
    • Versão do kernel Linux
    • Diagrama de topologia de rede
    • Arquivo de configuração (redigir informações sensíveis)
    • Trechos de log relevantes
    • Passos para reproduzir

Documentação Relacionada​

Última atualização em