lapspot

Script para criação de ponto de acesso Wi-Fi com bridge de rede no Linux

---

Sumário

• Visão Geral
• Como Funciona
• Pré-requisitos
• Configuração
• Uso
• Variáveis de Ambiente
• Logs e Depuração
• Solução de Problemas
• Referências

---

Visão Geral

O lapspot automatiza a criação de um ponto de acesso Wi-Fi no Linux utilizando hostapd e uma bridge de rede (br0). Ele conecta a interface Wi-Fi e a interface Ethernet em uma bridge, permitindo que dispositivos conectados ao AP compartilhem a mesma rede da interface com fio.

---

Como Funciona

[ Dispositivo cliente ]
        │ Wi-Fi (AP)
        ▼
  [ Interface wl* ] ──┐
                      ├──▶ [ Bridge br0 ] ──▶ [ Gateway / Rede ]
  [ Interface eth* ] ─┘

1. O NetworkManager é temporariamente desativado para as interfaces envolvidas
2. Os módulos em lib/ e config/ são carregados automaticamente por scripts/setup.sh na ordem: logger --> defaults --> settings --> validators --> utils --> core
3. Uma bridge (br0 por padrão) é criada e a interface Ethernet é adicionada a ela
4. O hostapd sobe o ponto de acesso Wi-Fi e adiciona automaticamente a interface wireless à bridge
5. Regras de firewall e IP forwarding são configurados
6. Ao parar, tudo é restaurado ao estado original
7. Os módulos em lib/ e config/ são carregados automaticamente por scripts/setup.sh na ordem: logger → defaults → settings → validators → utils → core

---

Pré-requisitos

Dependências obrigatórias

Ferramenta	Descrição
hostapd	Daemon para criação do ponto de acesso
ip	Gerenciamento de interfaces de rede
nmcli	Interface de linha de comando do NetworkManager
iptables	Configuração de regras de firewall

Instalação das dependências

Utilize o gerenciador de pacotes da sua distribuição:

Distro	Comando
Debian / Ubuntu	sudo apt install hostapd iproute2 network-manager iptables
Arch Linux	sudo pacman -S hostapd iproute2 networkmanager iptables
Fedora / RHEL	sudo dnf install hostapd iproute NetworkManager iptables
openSUSE	sudo zypper install hostapd iproute2 NetworkManager iptables

Módulos do kernel

O script carrega automaticamente os módulos bridge e br_netfilter, mas é possível verificá-los manualmente:

lsmod | grep -E "bridge|br_netfilter"

---

Configuração

Arquivo .env

Crie um arquivo .env no mesmo diretório do script para sobrescrever as configurações padrão:

# Configurações de rede
BRIDGE=br0
BRIDGE_IP=192.168.0.253
BRIDGE_NETMASK=24
GATEWAY=192.168.0.1

# Configurações do ponto de acesso
SSID=MeuAP
PASSWORD=minha-senha-segura

# Logs
LOG_LEVEL=INFO       # INFO ou DEBUG
ENABLE_LOG=false     # true para gravar logs em arquivo
LOG_DIR=./logs
LOG_FILE=./logs/logging.log

Se o arquivo .env não for encontrado, o script utiliza as configurações padrão definidas internamente.

---

Uso

O script requer privilégios de root.

Instalação em produção

Clone apenas a branch main diretamente em /opt/lapspot/:

sudo git clone --single-branch --branch main \
  https://forge.itamarcampos.com.br/itamcampos/lapspot.git \
  /opt/lapspot

Acesse o diretório e ajuste as permissões do script:

sudo chmod +x /opt/lapspot/scripts/setup.sh

Crie e edite o arquivo .env conforme necessário:

sudo cp .env.example .env
sudo nano /opt/lapspot/.env

Iniciar o ponto de acesso

sudo /opt/lapspot/scripts/setup.sh start

Parar o ponto de acesso

sudo /opt/lapspot/scripts/setup.sh stop

---

Variáveis de Ambiente

Variável	Padrão	Descrição
BRIDGE	br0	Nome da interface bridge
SSID	NDTI2	Nome da rede Wi-Fi (SSID)
PASSWORD	analise-exame	Senha da rede Wi-Fi
BRIDGE_IP	192.168.174.247	IP estático da bridge
BRIDGE_NETMASK	24	Máscara de rede (notação CIDR)
GATEWAY	192.168.174.1	Gateway padrão
LOG_LEVEL	INFO	Nível de log (INFO ou DEBUG)
ENABLE_LOG	false	Habilitar gravação de log em arquivo
LOG_DIR	./logs	Diretório dos arquivos de log
LOG_FILE	./logs/logging.log	Caminho do arquivo de log

---

Logs e Depuração

Níveis de log

O script possui dois níveis de log configuráveis via LOG_LEVEL:

• INFO (padrão) — Exibe mensagens informativas, de sucesso, avisos e erros
• DEBUG — Inclui todas as mensagens acima, além de detalhes internos, status de interfaces, estações conectadas e monitoramento DHCP via tcpdump

Habilitar modo debug

LOG_LEVEL=DEBUG
ENABLE_LOG=true

Exemplo de saída

[2025-05-08 12:00:00] [INFO] ===== INICIANDO PONTO DE ACESSO =====
[2025-05-08 12:00:01] [SUCCESS] Interface Wi-Fi detectada: wlan0
[2025-05-08 12:00:01] [SUCCESS] Interface Ethernet detectada: eth0
[2025-05-08 12:00:03] [SUCCESS] Bridge configurada com sucesso
[2025-05-08 12:00:08] [SUCCESS] hostapd iniciado com sucesso
[2025-05-08 12:00:11] [SUCCESS] ===== PONTO DE ACESSO INICIADO =====

---

Solução de Problemas

hostapd falha ao iniciar

Verifique se a interface Wi-Fi suporta o modo AP:

iw list | grep "Supported interface modes" -A 10

Interface Wi-Fi não é adicionada à bridge

Confirme que o driver da interface é compatível com nl80211 e que o hostapd tem permissão para operar em modo bridge.

Sem conectividade após iniciar o AP

Verifique se o IP forwarding está ativo:

cat /proc/sys/net/ipv4/ip_forward

Em seguida, confira as regras de firewall com a ferramenta disponível na sua distro:

# iptables
sudo iptables -L FORWARD -n -v

# nftables
sudo nft list ruleset

# ufw
sudo ufw status verbose

# firewalld
sudo firewall-cmd --list-all

NetworkManager interfere nas interfaces

O script desativa o gerenciamento automaticamente. Caso persista, verifique manualmente:

nmcli device status

---

Solução de problemas

Para melhor debug, forçe a exibição de cada comando executado antes de executá-lo:

# Altere as flags de debug do bash sem precisar alterar o script:
sudo bash -x /opt/lapspot/scripts/setup.sh start 2>&1 | tee /tmp/debug_output.txt

---

Contribuindo

Contribuições são bem-vindas! Para colaborar, clone o repositório completo (todas as branches):

git clone https://forge.itamarcampos.com.br/itamcampos/lapspot.git
cd lapspot

Crie uma branch para a sua feature ou correção:

git checkout -b minha-feature

Após as alterações, abra um Pull Request apontando para a branch main.

Certifique-se de testar o script localmente antes de submeter. Pull Requests sem testes ou que quebrem o fluxo principal não serão aceitos.

---

Referências

• hostapd - Linux wireless access point daemon
• iproute2 documentation
• Linux Bridge - kernel.org
• NetworkManager CLI (nmcli)

---

_{Feito por itamcampos}