Skip to main content

Documentação Completa — Instalação e Configuração do qBittorrent-nox como Serviço no Linux Server | Utorrent | Servidor

  • Documentação Completa — Instalação e Configuração do qBittorrent-nox como Serviço no Linux Server | Utorrent | Servidor

Este documento descreve todo o processo:

  • Instalação do qBittorrent-nox
  • Configuração da Web UI
  • Criação de serviço systemd
  • Correção de erro de HOME (/nonexistent)
  • Configuração de túnel SSH via PuTTY
  • Procedimentos de validação e troubleshooting

Distribuição considerada: Ubuntu/Debian Server.

1. Instalação do qBittorrent (modo headless)​

Atualizar repositórios:

sudo apt update

Instalar versão sem interface gráfica:

sudo apt install qbittorrent-nox -y

Verificar instalação:

qbittorrent-nox --version

2. Primeira execução (gera configuração)​

Execute manualmente para gerar arquivos de configuração:

qbittorrent-nox

Na primeira execução ele exibirá:

Interrompa com:

Ctrl + C

3. Configuração da Web UI​

Arquivo de configuração:

nano ~/.config/qBittorrent/qBittorrent.conf

Dentro da seção [Preferences], configure:

WebUI\Address=127.0.0.1
WebUI\Port=7040
WebUI\Username=admin
WebUI\Password_ha1=@ByteArray(...)

Observações:

  • 127.0.0.1 impede exposição pública
  • Porta 7040 foi usada no exemplo
  • A senha é armazenada como hash automaticamente após primeira execução

Salvar e sair.

4. Criar usuário dedicado para rodar como serviço​

Criar usuário system:

sudo adduser --system --group qbittorrent

Criar diretório HOME adequado:

sudo mkdir -p /home/qbittorrent
sudo chown -R qbittorrent:qbittorrent /home/qbittorrent

Corrigir HOME do usuário (evita erro /nonexistent):

sudo usermod -d /home/qbittorrent qbittorrent

Confirmar:

getent passwd qbittorrent

O HOME deve aparecer como:

/home/qbittorrent

5. Criar serviço systemd​

Criar arquivo:

sudo nano /etc/systemd/system/qbittorrent.service

Conteúdo:

[Unit]
Description=qBittorrent Command Line Client
After=network.target

[Service]
Type=simple
User=qbittorrent
Group=qbittorrent
Environment="HOME=/home/qbittorrent"
ExecStart=/usr/bin/qbittorrent-nox --webui-port=7040
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Salvar.

6. Ativar e iniciar serviço​

sudo systemctl daemon-reload
sudo systemctl enable qbittorrent
sudo systemctl start qbittorrent

Verificar status:

sudo systemctl status qbittorrent

Deve retornar:

Active: active (running)

7. Verificações Técnicas​

Verificar porta ativa:

ss -tulpn | grep 7040

Testar internamente:

curl http://127.0.0.1:7040

Se retornar HTML → Web UI funcionando.

8. Configuração do Túnel SSH via PuTTY (Windows)​

Objetivo: acessar Web UI remotamente de forma segura.

8.1 Configuração da sessão​

Em PuTTY:

Session:

  • Host Name: IP_DO_SERVIDOR
  • Port: 22
  • Connection Type: SSH

8.2 Criar túnel​

Vá em:

Connection → SSH → Tunnels

Preencher:

  • Source port: 7040
  • Destination: 127.0.0.1:7040
  • Marcar: Local
  • Marcar: Auto
  • Clicar: Add

Deve aparecer:

L7040  127.0.0.1:7040

8.3 Conectar​

Voltar em Session → Open.

Enquanto a sessão SSH estiver aberta, o túnel estará ativo.

9. Acesso pelo Navegador​

No computador local:

http://localhost:7040

Nunca usar o IP do servidor nesse caso.

10. Firewall (se aplicável)​

Liberar porta SSH apenas:

sudo ufw allow 22/tcp

Não é necessário liberar a porta 7040 se estiver usando túnel SSH e WebUI\Address=127.0.0.1.

11. Erro Resolvido Durante Processo​

Erro encontrado:

Could not create required directory '/nonexistent/.cache/qBittorrent'

Causa:

Usuário system criado com HOME /nonexistent.

Correção aplicada:

  • Criado /home/qbittorrent
  • Alterado HOME via usermod
  • Definido Environment="HOME=/home/qbittorrent" no systemd

12. Comandos Úteis de Manutenção​

Reiniciar serviço:

sudo systemctl restart qbittorrent

Parar:

sudo systemctl stop qbittorrent

Ver logs:

sudo journalctl -u qbittorrent -n 50 --no-pager

Ver status:

sudo systemctl status qbittorrent

13. Teste Após Reboot​

Reiniciar servidor:

sudo reboot

Após subir:

sudo systemctl status qbittorrent

Se estiver active (running), configuração está persistente.

Arquitetura Final​

  • qBittorrent rodando como serviço systemd
  • Executando como usuário isolado
  • Web UI escutando apenas em 127.0.0.1
  • Acesso externo exclusivamente via túnel SSH
  • Inicialização automática no boot
  • Reinício automático em caso de falha

Este documento cobre integralmente o processo desde instalação até operação segura em produção.