Tutorial criar imagem OpenWRT para roteador com Raspberry Pi

Objetivo

Criar uma imagem de sistema operacional OpenWRT para ser instalado no cartão SD ou memória eMMC no Raspberry Pi, para que funcione como um roteador de rede de internet.

Requisitos Necessários

Raspberry Pi
Adaptador USB para Ethernet no caso de Raspberry Pi comum ou Placa Router Board da DFRobot para Roteador com Raspberry Pi CM4
Fonte de Alimentação USB
2 cabos RJ45 – um para ligar o raspberry no modem e outro para ligar o raspberry no computador ou switch de rede
Cartão micro SD caso utilize um Raspberry Pi sem eMMC

Considerações Iniciais

O objetivo deste tutorial é criar uma imagem de sistema operacional com OpenWRT preparada para funcionar em um Raspberry Pi. Este tutorial serve para qualquer modelo do Raspberry, lembrando de ficar atento à necessidade de drivers adicionas dependendo do dongle USB-Ethernet que estiver utilizando.

Este passo a passo serve também para criar imagens do OpenWRT para Odroid, Nvidia Jester, ZimaBoard, e demais tinker boards. Porém, na etapa de configuração, é necessário selecionar os drivers apropriados.

Para fins de transparência, vou configurar um Raspberry Pi CM4 para funcionar como roteador. Se estiver utilizando um Raspberry Pi CM4 junto com uma placa Router Board da DFRobot, basta seguir a risca este passo a passo.

Necessidades para o setup

Este passo a passo precisa ser realizado em um Sistema Operacional Linux, com um bom poder de processamento, para agilizar o processo de compilação.

Caso não utilize sistema operacional linux, não tem problema, basta instalar uma máquina virtual em seu computador com Mac OS ou Windows. Caso utilize o Windows, também é possível utilizar o WSL, mas necessário remover o compartilhamento de PATH.

Informações gerais caso utilize Máquina Virtual

Se tiver dúvidas em como criar uma máquina virtual, acesse o tutorial: Tutorial Criar Máquina Virtual com Virtualbox

Caso vá utilizar uma máquina virtual, recomendo o setup:
Processamento: pelo menos 4 cores
Armazenamento: 25GB
Memória RAM: pelo menos 2GB

Para fins de curiosidade, após a criação da máquina virtual e posteriormente criação de 4 imagens do OpenWRT (2 completas e 2 para upgrade), a máquina virtual ficou com apenas 1,1GB de espaço em disco disponível. Então o tamanho mínimo de 25GB para espaço em disco é adequado (foto abaixo).
OpenWRT - espaço livre em máquina virtual de 25GB após compilação de imagem do openwrt

Considerações necessárias caso utilize Windows WSL

Durante o processo de compilação, o compartilhamento da variável PATH entre o windows e o WSL pode causar problemas. Desta forma precisamos editar o arquivo /etc/wsl.conf. Dentro do prompt do WSL, execute o comando:

sudo nano /etc/wsl.conf

Agora é necessário inserir o texto no fim do arquivo:

[interop]
appendWindowsPath = false

Agora abra o Windows Power Shell e execute o comando para reiniciar a instância do WSL:

wsl --shutdown

Abra novamente o WSL e digite o comando:

echo $PATH

Terá como saída algo similar ao conteúdo abaixo, o que varia para cada distribuição do linux:

/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/usr/lib/wsl/lib

Tutorial passo a passo para criar imagem do OpenWRT para Raspberry Pi funcionar como roteador

Passo 1

O primeiro passo é estar com seu computador ou máquina virtual com Sistema Operacional Linux em funcionamento. Assim, precisamos atualizar os softwares do sistema, utilizando os comandos:

sudo apt update
sudo apt upgrade

Passo 2

Agora necessário instalar os softwares necessários para o ambiente de criação da imagem do openwrt:

sudo apt install build-essential clang flex bison g++ gawk gcc-multilib g++-multilib gettext git libncurses5-dev libssl-dev python3-distutils rsync unzip zlib1g-dev file wget

Openwrt - criando um ambiente de compilação do código fonte

Passo 3

Precisamos agora fazer o download do openwrt direto do seu repositório do github. Costumo fazer este download dentro da minha pasta de usuário (cd ~). Vamos realizar o clone do projeto com o comando:

git clone https://git.openwrt.org/openwrt/openwrt.git

OpenWRT - realizar download do repositório com git clone

Passo 4

Após o download do projeto, precisamos entrar na pasta criada:

cd openwrt

OpenWRT - entrar na pasta do projeto

Passo 5

Vamos agora verificar as branch’s disponíveis. Lembrando que a branch principal (master) não é uma versão estável do openwrt.

git branch -a

OpenWRT - verificar as branchs disponíveis
OpenWRT - git branch -a, resultado de branchs disponíveis

Passo 6

Vamos ver as versões disponíveis com o comando:

git tag

OpenWRT - git tag - verificar versões disponíveis

OpenWRT - git tag - verificar versões disponíveis - resultados

Passo 7

A última versão estável disponível na data deste tutorial é a v22.03.4. Então vamos escolher ela para criar nossa imagem do OpenWRT.

git checkout v22.03.4

OpenWRT - git checkout, selecionando a branch e versão a ser utilizada

Passo 8

Agora podemos utilizar o comando para realizar o update das dependências e necessidades desta versão do openwrt:

./scripts/feeds update -a

OpenWRT - realizando a solicitação para verificar updates necessários para as dependências do projeto da versão do openwrt escolhida

Passo 9

Em seguida, precisamos agora instalar os softwares e dependências necessários para esta versão selecionada do openwrt:

./scripts/feeds install -a

OpenWRT - instalar dependências necessárias do projeto

OpenWRT - instalar dependências necessárias do projeto - etapa finalizada

Passo 10

Agora vamos seguir para configurações realizadas pelo menuconfig. Execute o comando para abrir o menu:

make menuconfig

OpenWRT - make menuconfig

Passo 11

Dentro do menu, é necessário definir o Target System. Utilize as setas do teclado e aperte ENTER em cima da opção:

Target System  (...) --->

Agora escolha a opção da família de processador 27xx da Broadcom:

BROADCOM BCM27xx

Passo 12

Após selecionar o Target System, você irá voltar para o menu principal. Agora precisamos definir o processador exato da família BCM27xx pelo subtarget. Navegue pelo menu e selecione primeiro a opção:

Subtarget (...) --->
Dentro do menu do Subtarget, selecione a opção:

BCM2711 boards (64 bit)

Passo 13

Após selecionar o Subtarget, você será redirecionado novamente para tela inicial do menu. Agora precisamos definir aspectos da imagem do openwrt a ser criada. O tipo do sistema de arquivos e o tamanho das partições. Selecione a opção:

Target Images --->

No menu de target images você tem diversas opções. Para fins deste exemplo, vou criar imagem do tipo ext4 e squashfs e a opção de compactar com gzip as imagens.
Não recomendo alterar o tamanho padrão da partição de kernel, a não ser que saiba o que está fazendo.
Se souber o tamanho exato do seu cartão de memória ou memória eMMC, você pode alterar o tamanho da partição de root para que não precise executar a expansão do sistema de arquivos após a instalação. Lembre-se de descontar o tamanho da partição de root, para que o cálculo fique correto.

Após definir as configurações do Target Images, utilize a seta do teclado e selecione a opção EXIT para voltar para tela principal do Menu.

Passo 14

Nestes próximos passos, precisamos instalar 3 drivers principais para o funcionamento:
kmod-r8169
kmod-usb-dwc2
bcm27xx-userland

Porém, há diversas divisões de submenu e pode ficar complicado descobrir em qual submenu está a opção de instalação dos pacotes necessários. O menu tem uma ferramenta de pesquisa que pode ser acionada utilizando a tecla:

Esta tecla é semelhante à opção de pesquisa do editor de texto VI ou VIM.
Caso precise instalar pacotes adicionais para habilitar seu dongle USB, ethernet, ou portas USB, etc; esta opção de busca é recomendada (ela informa o caminho dentro do menu até o driver que buscar, caso encontrado).

Não precisa realizar nenhuma busca neste momento, pode fechar o campo de busca e siga com os passos pelo menu principal.

Passo 15

Para instalar o driver kmod-r8169, precisamos navegar pelo submenu:

Kernel Modules

Em seguida para o submenu:

Network Devices

Encontre a opção:

kmod-r8169 (Realtek RTL-8169 PCI Gigabit Ethernet kernel support)

Para conseguir selecionar esta opção, aperte a tecla de ESPAÇO por 2 vezes. Ela estará selecionada, quando aparecer um asterisco <*> dentro da opção.

Utilize as setas do teclado e selecione a opção EXIT para voltar para o submenu de Kernel Modules.

Passo 16

Ainda dentro do submenu de Kernel Modules, vá na opção:

USB Support --->

Encontre a opção:

kmod-usb-dwc2 DWC2 USB controller drive

Para conseguir selecionar esta opção, aperte a tecla de ESPAÇO por 2 vezes. Ela estará selecionada, quando aparecer um asterisco <*> dentro da opção.

Utilize as setas do teclado e selecione a opção EXIT para voltar para o submenu de Kernel Modules. Depois selecione novamente EXIT para voltar para o menu principal.

Passo 17

Agora precisamos instalar o driver bcm27xx-userland, para ter suporte a família de processadores da Broadcom BCM27xx. Selecione a opção de submenu:

Utilities --->

Encontre a opção:

bcm27xx-userland BCM27xx userland tool

Para conseguir selecionar esta opção, aperte a tecla de ESPAÇO por 2 vezes. Ela estará selecionada, quando aparecer um asterisco <*> dentro da opção.

Depois selecione novamente para voltar para o menu principal.

Passo 18

No menu principal, procure e selecione a opção:

LuCI --->

Dentro do menu de LuCI, encontre e ative as 2 opções abaixo:

luci          LuCI interface with Uhttpd as Webserver (default)
luci-ssl      LuCI with HTTPS support (WolfSSL as SSL backend)

Para conseguir selecionar estas opções, aperte a tecla de ESPAÇO por 2 vezes em cada uma. Ela estará selecionada, quando aparecer um asterisco <*> dentro de cada opção.

Com as setas do teclado caminhe até a opção EXIT para voltar para o menu principal.

Passo 19

Caso não vá instalar mais nenhum driver de sua preferência, selecione novamente EXIT para fechar o menuconfig.

Irá aparecer a opção de salvar as configurações selecionadas. Selecione a opção:

< YES >

Passo 20

Caso apareça algum erro ao fechar o menuconfig, tente identificar qual pacote ou software está com problema. No meu caso específico, apareceu erro no pacote apinger. Um erro incomum, pois não selecionei para instalar o mesmo.

Para resolver este erro, apenas apaguei o arquivo do mesmo:

rm openwrt/package/feeds/luci/luci-app-apinger

Provavelmente quando executar este tutorial o erro acima já estará corrigido no repositório, pois verifiquei a ISSUE aberta no github para solucionar o problema.

OpenWRT - erro pacote apinger não encontrado, necessário deletar o arquivo para evitar erro de compilação

Passo 21 – Configurações Opcionais

Agora vamos apresentar algumas configurações opcionais:

Alterar banner de login

Caso queira realizar modificações cosméticas, basta alterar o arquivo:

nano package/base-files/files/etc/banner

Habilitar UART

O UART vem desabilitado por padrão, para habilitar, basta editar o arquivo:

nano target/linux/bcm27xx/image/config.txt

E inserir o texto, logo abaixo do campo “Place your custom settings here.”

enable_uart=1

OpenWRT - editar arquivo para habilitar UART

OpenWRT - UART habilitado no config.txt

Carregar arquivos de configuração sobre login, rede, firewall, dhcp, etc

Esta etapa NÃO É RECOMENDADA para uso geral. O ideal é deixar o openwrt gerar os arquivos e posteriormente realizar as modificações manualmente. Uma justificativa, é que o openwrt pode sofrer atualizações que alterem o layout destes arquivos, o que pode causar problemas na instalação. Mas para fins de automação da geração das imagens, com certeza é uma opção interessante.

Caso queira realizar esta etapa, é necessário criar a estrutura de diretórios:

mkdir files
mkdir files/etc
mkdir files/etc/config

Agora edite os arquivos de configuração e preencha com as configurações que possui. Uma dica para esta etapa é já ter o openwrt configurado em outro roteador e copiar e colar suas configurações. Em todo caso, os principais arquivos para editar são:

nano files/etc/config/dhcp
nano files/etc/config/firewall
nano files/etc/config/network
nano files/etc/config/wireless
nano files/etc/passwd
nano files/etc/shadow

Passo 22 – Compilar

Com todas as modificações desejadas já realizadas, vamos agora executar o comando make para iniciar a compilação do código fonte.

O comando make defconfig é útil pare verificar dependências faltantes. O comando make download irá realizar o download de todas as dependências antes de inicializar a compilação.

Lembrando que a opção -j (do comando make -j4) define o número de cores a serem utilizadas no processo. Como estou com 4 cores, utilizo -j4, para agilizar o processo. Utilize os comandos para iniciar o processo de compilação:

make defconfig
make download
make -j4

O processo é bem demorado, aguarde de forma paciente.
Openwrt - realizar make para compilar código fonte
Openwrt - código fonte compilado sem erros

Caso tenha erros durante a compilação, é possível utilizar as opção V=s ou V=sc junto com o make -j4.

Passo 23 – Arquivos de imagem criados

Após o término do processo de compilação, é possível verificar os arquivos criados na pasta:

ls bin/targets/bcm27xx/bcm2711

Neste exemplo foram criados 4 arquivos, baseados no OpenWRT v22.03.4.

OpenWRT - arquivos de imagem de instalação criados

Downloads – Arquivos de firmware para download Openwrt Raspberry Pi 4

Download firmware baseado na versão OpenWRT v22.03.4

Versão configurada exatamente igual os passos do tutorial.

Download firmware baseado na versão OpenWRT v23.05.4

Nesta versão o diretório /var é definido como persistente.

Lembrando que você deve escolher qual sistema de arquivos quer utilizar em seu raspberry. Utilizo o ext4 para caso geral, quando instalo outros pacotes no raspberry (servidor LAMP). Se o raspberry for dedicado para funcionar como um roteador, a partição squashfs é a opção recomendada, por preservar sistema de arquivos para o padrão de fábrica após reset/boot.