Cara Menginstal Sertifikat SSL ACME di TrueNAS

Panduan ini menunjukkan cara menginstal Sertifikat SSL ACME di TrueNAS menggunakan host eksternal dan EAB (Pengikatan Akun Eksternal). Sertifikat ini kompatibel dengan TrueNAS CORE dan TrueNAS SCALE.

TrueNAS memiliki dukungan ACME asli, tetapi hanya untuk Let’s Encrypt melalui integrasi DNS-01 bawaannya. Jika Anda ingin menggunakan penyedia ACME komersial (Sectigo, DigiCert, dll) dengan ACME + EAB, Anda harus membuat dan memperbarui sertifikat Anda secara eksternal menggunakan klien ACME seperti acme.sh, lalu menerapkannya ke TrueNAS.

---

Sebelum Anda Mulai

Inilah yang Anda perlukan:

• Nama domain yang mengarah ke IP publik TrueNAS Anda (misalnya, nas.example.com)
• TrueNAS CORE 13.x atau TrueNAS SCALE 23.x+
• Mesin Linux/BSD eksternal, VPS, atau server rumah (untuk menjalankan acme.sh)
• URL Direktori ACME, ID Kunci EAB, dan HMAC EAB dari CA komersial Anda
• Akses SSH ke TrueNAS jika Anda berencana untuk mengotomatiskan sinkronisasi

Catatan: TrueNAS TIDAK mendukung penyedia ACME sembarangan di UI-nya. Semua otomatisasi ACME komersial harus dilakukan di luar TrueNAS.

---

Langkah 1: Instal acme.sh pada Host Eksternal Anda

Mesin ini akan menangani pendaftaran, penerbitan, dan pembaruan akun ACME.

Lari:

curl https://get.acme.sh | sh
source ~/.bashrc
acme.sh --version

Jika versi mencetak dengan benar, Anda baik-baik saja.

---

Langkah 2: Daftarkan Akun ACME Anda dengan CA Komersial Anda (ACME + EAB)

Dasbor CA Anda akan menyediakannya:

• ID Kunci EAB
• Kunci HMAC EAB
• URL Direktori ACME

Daftarkan akun ACME Anda:

acme.sh --register-account \
  --server https://acme.yourca.com/v2/acme \
  --eab-kid YOUR_EAB_KID \
  --eab-hmac-key YOUR_EAB_HMAC_KEY \
  --accountemail [email protected]

Ganti nilai dengan nilai Anda sendiri. Anda hanya menjalankan ini sekali saja.

---

Langkah 3: Menerbitkan Sertifikat (Diperlukan Validasi DNS-01)

TrueNAS hampir selalu berada di belakang NAT, jadi validasi DNS adalah yang paling aman.

Berikut adalah contoh DNS manaul:

acme.sh --issue \
  -d nas.example.com \
  --dns dns_manual \
  --server https://acme.yourca.com/v2/acme

acme.sh akan memberitahu Anda untuk membuat catatan TXT:

_acme-challenge.nas.example.com   TXT   <token>

Buat catatan TXT di manajer DNS Anda dan tunggu penyebarannya.

Periksa penyebaran:

dig TXT _acme-challenge.nas.example.com +short

Setelah token muncul, jalankan kembali perintah yang sama dan acme.sh akan selesai menerbitkan sertifikat. File Anda akan disimpan di ~/.acme.sh/nas.example.com/.

Di dalamnya Anda akan menemukan:

• fullchain.cer: sertifikat server + perantara
• nas.example.com.key: kunci pribadi
• ca.cer: Rantai CA (jika disediakan secara terpisah)

---

Langkah 4: Impor Sertifikat ke TrueNAS

1. Pergi ke TrueNAS UI > Sistem > Sertifikat
2. Klik Tambah dan pilih Impor Sertifikat
3. Unggah file sertifikat Anda dan klik Simpan

Tetapkan sertifikat ke layanan Anda:

• Antarmuka Web
• Layanan SMB / NFS (jika ada)
• API middleware
• Membalikkan proksi atau aplikasi menggunakan HTTPS (TrueNAS SCALE)

---

Langkah 5: Mengotomatiskan Pembaruan dan Penerapan

TrueNAS tidak menarik sertifikat secara otomatis. Anda harus mendorong sertifikat yang telah diperbarui ke TrueNAS.

1. Membuat skrip penerapan

Pada hos ACME eksternal Anda, buat /usr/local/bin/truenas-deploy.sh:

Catatan: Skrip ini hanya berfungsi jika TrueNAS mengizinkan akses SSH dengan pengguna yang diizinkan untuk menjalankan midclt. Skrip ini mengunggah kunci + sertifikat baru ke /tmp/ dan menggantikan sertifikat aktif melalui API TrueNAS. Pastikan jalur dan domain Anda cocok dengan pengaturan acme.sh Anda.

#!/bin/bash

DOMAIN="nas.example.com"
NAS_USER="root"
NAS_HOST="truenas.local"

CERT_PATH="$HOME/.acme.sh/$DOMAIN"
KEY="$CERT_PATH/$DOMAIN.key"
CERT="$CERT_PATH/fullchain.cer"

scp "$KEY" "$NAS_USER@$NAS_HOST:/tmp/key.key"
scp "$CERT" "$NAS_USER@$NAS_HOST:/tmp/cert.cer"

ssh "$NAS_USER@$NAS_HOST" <<EOF
midclt call certificate.update '{"certificate": "custom", "csr": null, "privatekey": "$(cat /tmp/key.key)", "certificate": "$(cat /tmp/cert.cer)"}'
EOF

Buatlah agar dapat dieksekusi:

chmod +x /usr/local/bin/truenas-deploy.sh

2. Menambahkan pengait pembaruan

Tambahkan hook penyebaran di acme.sh:

acme.sh --deploy-hook truenas-deploy \
  -d nas.example.com

Atau tambahkan ini di dalam ~/.acme.sh/deploy/truenas-deploy.sh.

3. Biarkan acme.sh menangani semuanya

Inilah yang dilakukan acme.sh secara otomatis:

• Memeriksa pembaruan setiap hari
• Memperbarui sertifikat
• Memicu skrip penerapan Anda
• Mendorong sertifikat yang diperbarui ke TrueNAS
• Menerapkan perubahan secara diam-diam

Setelah dikonfigurasi, Anda tidak perlu menyentuh TrueNAS lagi untuk pembaruan sertifikat.

---

Pertanyaan Umum

Jika Anda menyiapkan otomatisasi ACME di TrueNAS untuk pertama kalinya, jawaban singkat ini mencakup masalah yang paling sering dihadapi pengguna.

Dapatkah saya menggunakan satu sertifikat untuk GUI TrueNAS dan layanan lainnya (SMB, NFS, portal iSCSI)?

Ya. Setelah Anda mengimpor sertifikat di System > Certificates, Anda dapat memilih sertifikat yang sama untuk UI web dan layanan apa pun yang mengekspos HTTPS (UI Web, API, mungkin reverse proxy/HAProxy jika Anda menggunakannya). Anda tidak memerlukan sertifikat terpisah untuk setiap layanan kecuali jika Anda menginginkan nama host yang berbeda.

NAS saya berada di belakang CGNAT atau NAT ganda. Masih bisakah saya menggunakan ACME?

Ya, tetapi Anda harus menggunakan validasi DNS-01. HTTP-01 tidak akan berfungsi karena server ACME tidak dapat menjangkau NAS Anda melalui port 80. Dengan DNS-01, CA hanya memeriksa catatan TXT Anda di _acme-challenge.yourdomain.com, jadi tidak peduli di mana letak NAS sebenarnya.

Apa yang terjadi jika acme.sh memperbarui sertifikat tetapi saya lupa mengimpornya kembali ke TrueNAS?

TrueNAS akan terus menggunakan sertifikat lama yang Anda impor terakhir kali. File yang diperbarui berada di host eksternal Anda hingga Anda mengunggahnya lagi (atau skrip/API Anda menanganinya).

Situs Anda akan tetap berfungsi, tetapi pada akhirnya browser akan mulai memperingatkan tentang sertifikat yang kedaluwarsa. Itulah mengapa ada baiknya Anda membuat skrip untuk mengimpor ulang atau memasang pengingat di tempat yang dekat dengan tanggal kedaluwarsa.

Dapatkah saya menggunakan sertifikat wildcard (seperti *.example.com) dengan TrueNAS

Ya. Selama kunci privat dan sertifikat cocok, TrueNAS tidak peduli apakah itu wildcard atau sertifikat hos tunggal. Anda masih harus mengeluarkan wildcard melalui DNS-01 di acme.sh, lalu mengimpor fullchain.cer + *.example.com.key ke TrueNAS. Berhati-hatilah saat Anda menggunakan kembali kunci itu. Sertifikat wildcard memberikan kontrol penuh atas semua subdomain yang dicakupnya.

---

Kata Penutup

Alur kerja ini memberi Anda cara yang stabil dan andal untuk menginstal sertifikat ACME di TrueNAS tanpa mengganggu sistem. Host eksternal Anda menangani penerbitan, pembaruan, dan pengelolaan sertifikat, sementara TrueNAS hanya menerima impor bersih setiap kali file diperbarui.

Setelah prosesnya berjalan, semuanya berjalan dengan tenang di latar belakang, dan Anda hanya perlu masuk jika ingin menyesuaikan skrip atau memutar kredensial.