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 de XDP e eBPF
  8. Problemas de Desempenho
  9. Problemas Específicos de Hypervisor
  10. Problemas de 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 uma solu�o de problemas mais profunda, 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 de 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 do switch/SPAN para copiar o tráfego N3
# 3. Espelhamento de porta do 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

# Faça 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 YAML no arquivo de configuração

Resolução:

# Valide a sintaxe YAML
cat config.yml | python3 -c "import yaml, sys; yaml.safe_load(sys.stdin)"

# Problemas comuns:
# - Indentação incorreta (use espaços, não tabs)
# - Dois pontos ausentes após chaves
# - Strings não entre aspas com caracteres especiais
# - Itens de lista sem hífens

# Exemplo de YAML correto:
cat > config.yml <<EOF
interface_name: [eth0]
xdp_attach_mode: generic
api_address: :8080
pfcp_address: :8805
EOF

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 config.yml:
interface_name: [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 na configuração
api_address: :8081
pfcp_address: :8806
metrics_address: :9091

Problema: ID do nó PFCP inválido​

Sintomas:

ERRO[0000] id do nó pfcp inválido: deve ser um endereço IPv4 válido

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

Resolução:

# Correto: Use endereço IP (não nome de host)
pfcp_node_id: 10.100.50.241

# Incorreto:
# pfcp_node_id: localhost
# pfcp_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 do nó PFCP errado​

Resolução:

# Defina o ID do nó PFCP para o IP correto da interface N4
pfcp_node_id: 10.100.50.241  # Deve corresponder ao IP na rede N4

Rede inacessível para o SMF​

Resolução:

# Teste a conectividade com o SMF
ping <SMF_IP>

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

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

SMF configurado com IP do UPF errado​

Resolução:

  • Verifique a configuração do SMF para o endereço do UPF
  • Certifique-se de que o SMF tem o IP 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:

# Aumente o intervalo de heartbeat
heartbeat_interval: 30  # Aumente de 5 para 30 segundos
heartbeat_retries: 5    # Aumente as tentativas
heartbeat_timeout: 10   # 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:

# Atualize config.yml com a interface correta
interface_name: [ens1f0]  # Use o nome real da interface do 'ip link show'

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

Sintomas:

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

Diagnóstico:

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

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

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

Causas Comuns:

Nenhuma 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 consulta 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 ausente
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 menor que o esperado
  • Tráfego limitado a uma taxa específica
  • Contadores de volume URR mostram comportamento de platô
  • Contadores de perda 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 como 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 de política do SMF e o perfil QoS

Entendendo a Aplicação do MBR:

O OmniUPF usa um algoritmo de janela deslizante para aplicar 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 perda
  • 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 ausente
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 CRIAÇÃO_DE_CABEÇALHO_EXTERNO
curl http://localhost:8080/api/v1/sessions | jq '.[].fars[] | .outer_header_creation'

# Verifique a acessibilidade do gNB
ping <GNB_N3_IP>

Problemas de XDP e eBPF​

Para configuração detalhada de 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 sem suporte a XDP​

Resolução:

# Recompile o kernel com suporte a XDP ou atualize para um kernel mais novo
# 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 verificador
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
  • Aumento das perdas 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: programa eBPF encontrou erro em tempo de execução

Resolução:

# Verifique os logs do kernel em busca de erros eBPF
dmesg | grep -i bpf

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

# Se o problema persistir, ative o log 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:

# Aumente a capacidade do mapa em config.yml
max_sessions: 200000  # Aumente de 100000

# Ou defina tamanhos individuais de mapa
pdr_map_size: 400000
far_map_size: 400000
qer_map_size: 200000

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:

# Mude para o modo nativo para melhor desempenho
xdp_attach_mode: native  # Requer NIC/drivers compatíveis com XDP

Gargalo de núcleo único​

Resolução:

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

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

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

Buffer bloat​

Resolução:

# Reduza os limites de buffer para diminuir a latência
buffer_max_packets: 5000
buffer_packet_ttl: 15

Problema: Latência alta​

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 bufferizados
curl http://localhost:8080/api/v1/upf_buffer_info | jq '.total_packets_buffered'

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

Resoluções:

Pacotes sendo bufferizados excessivamente​

Resolução:

# Verifique por que os pacotes estão bufferizados
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 consulta FIB​

Resolução:

# Certifique-se de que o cache de roteamento está 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: Perda de pacotes sob carga​

Sintomas:

  • Taxa de perda aumenta com o tráfego
  • Erros RX na NIC

Diagnóstico:

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

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

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

Resolução:

# Aumente o tamanho do buffer de anel RX
ethtool -G eth0 rx 4096

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

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

Problemas Específicos de Hypervisor​

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

Proxmox: XDP não funciona na VM​

Sintomas:

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

Causa: VM usando rede em ponte sem SR-IOV

Resolução:

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

xdp_attach_mode: generic

Opção 2: Configure o passthrough SR-IOV

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

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

# 3. Atribua VF à VM na interface do Proxmox
# Hardware → Adicionar → Dispositivo PCI → Selecione VF

# Na VM:
interface_name: [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:

# Habilite o modo promíscuo no vSwitch (no vSphere Client):
# 1. Selecione 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:

# Use o modo genérico (única opção)
xdp_attach_mode: generic

# Otimize as configurações do VirtualBox:
# - Use adaptador VirtIO-Net (se disponível)
# - Habilite o modo promíscuo "Permitir Tudo"
# - Aloque mais núcleos de CPU para a VM
# - Use rede em ponte em vez de NAT

# Considere migrar para KVM/Proxmox para melhor desempenho

Problemas de NIC e Driver​

Problema: Driver NIC não suporta XDP​

Sintomas:

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

Diagnóstico:

# Verifique o driver da NIC
ethtool -i eth0 | grep driver

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

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

Resolução:

Opção 1: Use o modo genérico

xdp_attach_mode: generic

Opção 2: Atualize o driver da NIC

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

# Ou instale o driver específico do fornecedor
# Exemplo para Intel:
# Baixe de https://downloadcenter.intel.com/

Opção 3: Substitua a NIC

# Use 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:

# Verifique os logs do kernel
dmesg | tail -100

# Verifique bugs no driver
journalctl -k | grep -E "BUG:|panic:"

Resolução:

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

# 2. Desative o offload do XDP (use apenas nativo)
xdp_attach_mode: native

# 3. Use o modo genérico como solução alternativa
xdp_attach_mode: generic

# 4. Relate o bug ao fornecedor da NIC ou à equipe do kernel Linux

Falhas na Estabelecimento de Sessão​

Problema: Estabelecimento de sessão falha​

Sintomas:

  • SMF relata falha no 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:

# Verifique os logs do OmniUPF em busca de erros de sessão
journalctl -u omniupf | grep -i "estabelecimento de sessão"

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

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

Causas Comuns:

Capacidade do mapa cheia​

Resolução:

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

# Aumente a capacidade (veja a seção sobre mapa eBPF cheio acima)

Parâmetros PDR/FAR inválidos​

Resolução:

# Verifique os logs do OmniUPF em busca de erros de validação
journalctl -u omniupf | grep -E "inválido|erro" | tail -20

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

# Verifique a configuração do SMF e os parâmetros da sessão

Recurso não suportado (UEIP/FTUP)​

Resolução:

# Habilite recursos necessários, se necessário
feature_ueip: true  # Alocação de IP do UE pelo UPF
ueip_pool: 10.60.0.0/16

feature_ftup: true  # Alocação de F-TEID pelo UPF
teid_pool: 100000

Problemas de Bufferização​

Problema: Pacotes presos no buffer​

Sintomas:

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

Diagnóstico:

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

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

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

Causas e Resoluções:

FAR nunca atualizado para FORWARD​

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

Resolução:

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

# Ação BUFF = 1 (bufferização)
# Ação FORW = 2 (encaminhamento)

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

TTL do buffer expirado​

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

Resolução:

# Aumente o TTL do buffer
buffer_packet_ttl: 60  # Aumente de 30 para 60 segundos

Overflow do buffer​

Causa: Muitos pacotes bufferizados por FAR

Resolução:

# Aumente os limites de buffer
buffer_max_packets: 20000  # Por FAR
buffer_max_total: 200000   # Limite global

Depuração Avançada​

Habilitar Registro de Depuração​

logging_level: debug  # trace | debug | info | warn | error
# Reinicie o OmniUPF com registro de depuração
sudo systemctl restart omniupf

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

Rastreamento do Programa eBPF​

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

# Rastreie 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 de Captura de Pacotes do XDP:

O XDP processa pacotes antes da pilha de rede do kernel, portanto, 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: Use a 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: Capture o 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 do switch para capturar tráfego
# Exemplos:
# - TAP físico entre gNB e UPF
# - Espelhamento/mirror de porta 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:

# Use um TAP de rede ou configure o 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 ao Gi1/0/24:
tcpdump -i eth0 -n udp port 2152 -w /tmp/n3_capture.pcap

Ambiente Virtual (VMware, KVM, etc.):

# Configure o espelhamento de porta do switch virtual para enviar tráfego do UPF para a VM de analisador
# Exemplo: bridge Linux com tcpdump em VM diferente
# No hypervisor, espelhe a interface N3 do UPF para a interface do analisador

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

Por que a 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 no hardware
  • O tcpdump baseado em host vê pacotes APÓS o processamento do 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. Colete 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. Relate o 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
    • Etapas para reproduzir

Documentação Relacionada​

Última atualização em