Belajar Aria2 - Troubleshooting & Debugging

#Pendahuluan

Di episode 18 kalian membuat aria2 berjalan tanpa pengawasan — dan itulah saat yang paling membutuhkan kemampuan debugging. Download yang gagal di mesin otomasi tidak lagi terlihat di layar; ia hanya meninggalkan jejak di log dan exit code. Episode 19 ini membekali kalian kebiasaan membaca bukti: mengaktifkan log, memahami barisnya, lalu memetakan error yang paling sering muncul — HTTP, TLS, FTP, dan BitTorrent — beserta akar masalah dan solusinya.

Prinsip yang sama berlaku di sini: jangan menebak, lihat log.

#Mengaktifkan Log: --log dan --log-level

aria2 secara default diam ketika berjalan normal. Untuk debugging, aktifkan log ke file:

aria2c --log=/var/log/aria2/aria2.log --log-level=debug \
  https://cdn.example.com/update.iso

Level log menentukan seberapa banyak detail yang direkam:

• debug — paling detail: koneksi, request HTTP, peer BitTorrent, semua terekam.
• info — cukup untuk operasi harian: download dimulai, selesai, dan error utama.
• notice — hanya kejadian penting, cocok untuk produksi.

Level tidak memengaruhi keberadaan error, hanya detailnya. Gunakan info di produksi dan naikkan ke debug hanya ketika ada yang perlu diselidiki — log debug bisa sangat besar dan cepat mengisi disk.

#--show-console-readout dan --summary-interval

Di terminal, aria2 menampilkan console readout — baris progress yang memperbarui diri. Untuk skrip dan daemon, output ini tidak berguna dan justru membanjiri log. Nonaktifkan dengan --show-console-readout=false, dan atur ringkasan berkala:

aria2c --show-console-readout=false --summary-interval=60 \
  --log=/var/log/aria2/aria2.log --log-level=info \
  --input-file=urls.txt

Dengan kombinasi ini terminal tetap tenang sementara semua kejadian tercatat rapi di log. Saat daemon (di episode 20), pengaturan inilah yang membuat log service bisa dibaca manusia.

#Membaca Baris Log

Setiap baris log punya tiga bagian: timestamp, level, dan pesan:

2026-08-03 10:11:12.345 NOTICE - Downloading item: 1
2026-08-03 10:11:14.221 WARN  - Could not connect to 203.0.113.10:443
2026-08-03 10:11:15.077 ERROR - SSL certificate problem: self-signed certificate
2026-08-03 10:11:20.512 NOTICE - Download complete: /srv/downloads/update.iso

Kunci membacanya: cari level ERROR dan WARN terlebih dahulu. Sebuah baris WARN yang diikuti ERROR biasanya menceritakan satu kisah yang sama: koneksi gagal, lalu protokol menyerah. Baca dari level terendah ke tertinggi, dan jangan lupa mencocokkannya dengan exit code dari episode 18.

#Error HTTP: Could not connect

Pesan Could not connect berarti koneksi TCP ke server tidak pernah terbentuk. Penyebabnya berlapis: server mati, port salah, atau firewall membuang paket. Cara membedakannya sederhana — tes koneksi di lapisan yang lebih rendah dengan alat lain:

curl -v --connect-timeout 5 https://cdn.example.com/update.iso -o /dev/null

Jika curl gagal dengan cara yang sama, masalahnya di jaringan atau server, bukan di aria2. Jika curl sukses, bandingkan URL yang kalian berikan ke aria2 — salah skema (http vs https) atau salah port adalah penyebab paling sering dan paling mudah terlewat.

#Error HTTPS: SSL certificate problem

Verifikasi TLS diaktifkan secara default di aria2. Ketika sertifikat server bermasalah — self-signed, kedaluwarsa, atau nama host tidak cocok — kalian akan melihat SSL certificate problem. Jalan pintas yang tampak mudah adalah --check-certificate=false, tapi itu mematikan verifikasi identitas server sepenuhnya.

Untuk endpoint internal yang memang memakai sertifikat sendiri, sempitkan solusinya alih-alih mematikan verifikasi:

aria2c --ca-certificate=/etc/ssl/certs/ca-certificates.crt \
  https://intranet.example.com/update.iso

#Error FTP: File not found dan Login Gagal

FTP punya dua lapisan error: autentikasi dan akses file. 530 Login incorrect berarti kredensial salah; 550 File not found berarti path tidak ditemukan di server. FTP aktif (default) sering gagal di balik NAT karena server mencoba menghubungi kalian kembali — solusinya adalah mode pasif:

aria2c --ftp-pasv=true --ftp-user=arman --ftp-passwd=RAHASIA \
  ftp://files.example.com/distros/update.iso

Jangan pernah meletakkan password di command line untuk pekerjaan rutin — simpan di netrc atau file konfigurasi dengan izin yang ketat, seperti yang dibahas di episode keamanan download.

#Error BitTorrent: Handshake failed

Handshake failed di BitTorrent berarti koneksi TCP ke peer berhasil, tapi pertukaran identitas awal gagal — biasanya karena versi protokol tidak cocok atau peer menolak klien yang tidak dikenal. Ini bukan selalu kegagalan total: dengan banyak peer tersedia, aria2 akan mencoba yang lain. Jika hampir semua peer gagal, periksa enkripsi:

aria2c --bt-min-crypto=plain --bt-require-crypto=false \
  https://example.com/file.torrent

#DHT dan Port yang Terblokir

Ini penyebab paling umum torrent atau magnet "jalan tapi tidak pernah selesai". BitTorrent butuh port TCP dan UDP yang bisa dijangkau dari luar — secara default kisaran 6881 sampai 6999. Jika firewall atau NAT memblokirnya, aria2 hanya bisa berbicara dengan peer yang menjangkau kalian, bukan sebaliknya. Di server Ubuntu:

sudo ufw allow 6881:6999/tcp
sudo ufw allow 6881:6999/udp

Untuk magnet link yang tidak menemukan sumber sama sekali, DHT adalah kuncinya — pastikan --enable-dht=true dan port UDP DHT tidak diblokir. Jangan lupa dht.dat sejak episode BitTorrent: file itu adalah tabungan informasi peer kalian, jadi ia harus persist antar sesi agar DHT "ingat" di mana harus mencari.

#Urutan Diagnosis yang Benar

Ketika sebuah download bermasalah, ikuti tangga yang konsisten:

1. Baca exit code — kategori masalahnya: jaringan (6), DNS (19), autentikasi (24), checksum (32).
2. Baca log — cari baris WARN dan ERROR, baca dari level terendah.
3. Isolasi lapisan — tes dengan curl untuk memisahkan masalah server dari masalah aria2.
4. Periksa lingkungan — firewall, port, NAT, dan proxy (dari episode 12).

Urutan ini mencegah kalian membuang waktu: jika DNS gagal, jangan membuka firewall. Jika SSL gagal, jangan mengubah-ubah opsi BitTorrent. Setiap lapisan memberi petunjuk ke lapisan berikutnya.

#Penutup

Episode 19 membekali kalian perangkat diagnostik lengkap: mengaktifkan log dengan --log dan --log-level, meredam console readout untuk skrip dan daemon, memahami format baris log, memetakan error HTTP, TLS, FTP, dan BitTorrent beserta akar masalahnya, serta membuka port 6881 sampai 6999 untuk peer dan DHT.

Yang paling berharga bukan alatnya, melainkan kebiasaannya: debugging adalah membaca bukti secara berurutan, bukan menebak. Mulai dari exit code, turun ke log, isolasi lapisan, lalu periksa lingkungan.

Di episode 20 berikutnya kita menaikkan semuanya ke level produksi: production-ready setup — daemon, systemd, log rotation, Docker, dan NAS. Sampai jumpa!