كيفية تثبيت شهادة ACME SSL على TrueNAS

يوضح هذا الدليل كيفية تثبيت شهادة ACME SSL على TrueNAS باستخدام مضيف خارجي و EAB (ربط الحساب الخارجي). وهو متوافق مع كل من TrueNAS CORE و TrueNAS SCALE.

يحتوي TrueNAS على دعم ACME الأصلي، ولكن فقط ل Let’s Encrypt من خلال تكامل DNS-01 المدمج فيه. إذا كنت ترغب في استخدام موفر ACME تجاري (Sectigo، DigiCert، إلخ) مع ACME + EAB، فيجب عليك إنشاء شهادتك وتجديدها خارجيًا باستخدام عميل ACME مثل acme.sh، ثم نشرها في TrueNAS.

---

قبل أن تبدأ

إليك ما ستحتاج إليه:

• اسم نطاق يشير إلى عنوان IP العام ل TrueNAS (على سبيل المثال، nas.example.com)
• TrueNAS CORE 13.x أو TrueNAS SCALE 23.x+
• جهاز Linux/BSD خارجي أو خادم خاص افتراضي خاص أو خادم منزلي (لتشغيل acme.sh)
• عنوان URL الخاص بدليل ACME، ومعرف مفتاح EAB، و EAB HMAC من المرجع المصدق (CA) التجاري الخاص بك
• الوصول إلى SSH إلى TrueNAS إذا كنت تخطط لمزامنة تلقائية

ملاحظة: لا يدعم TrueNAS موفري ACME التعسفيين في واجهة المستخدم الخاصة به. يجب أن تتم جميع عمليات أتمتة ACME التجارية خارج TrueNAS.

---

الخطوة 1: تثبيت acme.sh على مضيفك الخارجي

سيتعامل هذا الجهاز مع تسجيل حساب ACME وإصداره وتجديده.

اركض:

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

إذا تمت طباعة النسخة بشكل صحيح، فأنت بخير.

---

الخطوة 2: قم بتسجيل حساب ACME الخاص بك مع المرجع المصدق التجاري الخاص بك (ACME + EAB)

ستوفر لك لوحة معلومات CA الخاصة بك:

• مُعرّف مفتاح EAB
• مفتاح EAB HMAC
• عنوان URL دليل ACME

سجّل حساب ACME الخاص بك:

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]

استبدل القيم بقيمك الخاصة. يمكنك تشغيل هذا مرة واحدة فقط.

---

الخطوة 3: إصدار الشهادة (مطلوب التحقق من صحة DNS-01)

يكون TrueNAS دائمًا خلف NAT، لذا فإن التحقق من صحة DNS هو الأكثر أمانًا.

فيما يلي مثال على نظام أسماء النطاقات المنقولة:

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

سيخبرك acme.sh بإنشاء سجل TXT:

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

قم بإنشاء سجل TXT في مدير DNS الخاص بك وانتظر النشر.

تحقق من الانتشار:

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

بمجرد ظهور الرمز المميز، أعد تشغيل الأمر نفسه وسينتهي acme.sh من إصدار الشهادة. سيتم حفظ ملفاتك في ~/.acme.sh/nas.example.com/.

ستجد في الداخل

• fullchain.cer: شهادة الخادم + شهادة وسيطة
• مفتاح nas.example.com.key: المفتاح الخاص
• CA.cer: سلسلة CA (إذا تم توفيرها بشكل منفصل)

---

الخطوة 4: استيراد الشهادة إلى TrueNAS

1. انتقل إلى: واجهة TrueNAS UI > النظام > الشهادات
2. انقر فوق إضافة وحدد استيراد الشهادة
3. قم بتحميل ملفات الشهادة الخاصة بك وانقر فوق حفظ

قم بتعيين الشهادة لخدماتك:

• واجهة مستخدم الويب
• خدمات SMB / NFS (إن وجدت)
• واجهات برمجة التطبيقات الوسيطة
• البروكسيات العكسية أو التطبيقات التي تستخدم HTTPS (TrueNAS SCALE)

---

الخطوة 5: أتمتة التجديد والنشر التلقائي

لا يقوم TrueNAS بسحب الشهادات تلقائياً. يجب عليك دفع الشهادات المجددة إلى TrueNAS.

1. إنشاء برنامج نصي للنشر

على مضيف ACME الخارجي الخاص بك، قم بإنشاء /usr/local/bin/truenas-deploy.sh:

ملاحظة: لا يعمل هذا البرنامج النصي إلا إذا كان TrueNAS يسمح بالوصول إلى SSH مع مستخدم مسموح له بالتشغيل midclt. يقوم بتحميل المفتاح الجديد + الشهادة الجديدة إلى /tmp/ ويستبدل الشهادة النشطة من خلال واجهة برمجة تطبيقات TrueNAS. تأكد من تطابق المسارات والمجال مع إعداد acme.sh الخاص بك.

#!/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

اجعلها قابلة للتنفيذ:

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

2. إضافة خطاف التجديد

أضف خطاف نشر في acme.sh:

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

أو أضف هذا داخل ~/.acme.sh/deploy/truenas-deploy.sh.

3. دع acme.sh يتعامل مع كل شيء

إليك ما يفعله acme.sh تلقائيًا:

• التحقق من التجديدات اليومية
• تجديد الشهادة
• تشغيل البرنامج النصي للنشر
• دفع الشهادات المحدثة إلى TrueNAS
• يطبق التغييرات بصمت

بمجرد التهيئة، لن تضطر إلى لمس TrueNAS مرة أخرى لتجديد الشهادات.

---

الأسئلة الشائعة

إذا كنت تقوم بإعداد أتمتة ACME على TrueNAS لأول مرة، فإن هذه الإجابات السريعة تغطي المشكلات التي يواجهها المستخدمون في أغلب الأحيان.

هل يمكنني استخدام شهادة واحدة لكل من واجهة TrueNAS GUI والخدمات الأخرى (SMB، NFS، بوابات iSCSI)؟

نعم. بمجرد استيراد الشهادة في النظام > الشهادات، يمكنك تحديد نفس الشهادة لواجهة مستخدم الويب ولأي خدمة تعرض HTTPS (واجهة مستخدم الويب، واجهة برمجة التطبيقات، وربما الوكيل العكسي/AProxy إذا كنت تستخدمه). لا تحتاج إلى شهادات منفصلة لكل خدمة إلا إذا كنت تريد أسماء مضيفين مختلفة.

NAS الخاص بي خلف CGNAT أو NAT المزدوج. هل لا يزال بإمكاني استخدام ACME؟

نعم، ولكن يجب عليك استخدام التحقق من صحة DNS-01. لن يعمل HTTP-01 لأن خادم ACME لا يمكنه الوصول إلى NAS الخاص بك عبر المنفذ 80. باستخدام DNS-01، يتحقق المرجع المصدق (CA) فقط من سجل TXT الخاص بك في _acme-challenge.yourdomain.com، لذلك لا يهتم بمكان وجود NAS في الواقع.

ماذا يحدث إذا قام acme.sh بتجديد الشهادة ولكني نسيت إعادة استيرادها إلى TrueNAS؟

سيستمر TrueNAS في استخدام الشهادة القديمة التي قمت باستيرادها في المرة السابقة. ستبقى الملفات المجددة على مضيفك الخارجي حتى تقوم بتحميلها مرة أخرى (أو يقوم البرنامج النصي/واجهة برمجة التطبيقات بمعالجتها).

سيظل موقعك يعمل، ولكن في النهاية ستبدأ المتصفحات في التحذير من انتهاء صلاحية الشهادة. لهذا السبب يجدر بك إما كتابة نص برمجي لإعادة الاستيراد أو وضع تذكير في مكان قريب من تاريخ انتهاء الصلاحية.

هل يمكنني استخدام شهادة حرف بدل (مثل *.example.com) مع TrueNAS

نعم. طالما أن المفتاح الخاص والشهادة متطابقان، فإن TrueNAS لا يهتم إذا كان حرف البدل أو شهادة أحادية المضيف. لا يزال يتعين عليك إصدار حرف البدل عبر DNS-01 في acme.sh، ثم استيراد fullchain.cer + *.example.com.key إلى TrueNAS. فقط كن حذرًا عند إعادة استخدام هذا المفتاح. تمنح شهادة حرف البدل تحكمًا كاملاً في جميع النطاقات الفرعية التي تغطيها.

---

الكلمات الأخيرة

يمنحك سير العمل هذا طريقة مستقرة وموثوقة لتثبيت شهادة ACME على TrueNAS دون قتال النظام. يتعامل مضيفك الخارجي مع إصدار الشهادة وتجديدها وإدارتها، بينما يتلقى TrueNAS ببساطة عمليات استيراد نظيفة كلما تم تحديث الملفات.

بمجرد تشغيل العملية، يعمل كل شيء بهدوء في الخلفية، ولا تتدخل إلا إذا كنت تريد ضبط البرامج النصية أو تدوير بيانات الاعتماد.