ماذا تفعل هذه الوحدة #
شهادة TLS هي ما يحوّل http:// إلى https://: تشفّر الاتصال بين زوّارك والخادم، وتجعل المتصفّح يعرض القفل بدلًا من تحذير «غير آمن».
تتولّى وحدة tls دورة حياة تلك الشهادة كاملةً باستخدام certbot: تطلبها من Let's Encrypt (سلطة مجانية معترَف بها جيدًا)، وتثبت أن النطاق ملكك عبر تحدّي ACME، وتُثبِّت الشهادة حيث يتوقّعها خادم الويب لديك، وتجدِّدها تلقائيًّا قبل انتهائها — دون أن تضطر إلى التذكّر.
يجب أن يشير نطاقك (مثلًا app.ejemplo.com) عبر DNS إلى عنوان IP لهذا الخادم، ويجب أن يكون المنفذ 80 قابلًا للوصول لتحدّي HTTP-01. وإلا، سيفشل الإصدار عند خطوة التحقق.
المهام الشائعة #
اختر ما تريد فعله. تأتي كل وصفة بالأمر مكتوبًا بالفعل — ما عليك إلا استبدال النطاق والبريد بخاصّتك والضغط على نسخ.
1
أصدِر شهادتي الأولى
احصل على قفل HTTPS لنطاقك في دقيقة.
اتصل عبر SSH بخادمك بالمستخدم ubuntu.
نفّذ الأمر، مستبدلًا نطاقك وبريدك (يُستخدم البريد فقط لتحذيرك إن كان شيء على وشك الانتهاء):
$ sudo imaxe tls issue app.ejemplo.com --email [email protected]انتظر بضع ثوانٍ. سترى تقدّم التحدّي، وفي النهاية تاريخ الانتهاء.
https:// مع القفل. التجديد التلقائي مُفعَّل — لا عليك فعل شيء آخر.2
اطّلِع على الموجودة ومتى تنتهي
تحقّق من حالة شهاداتك بنظرة واحدة.
ملخّص سريع للحالة العامة ومؤقّت التجديد:
$ sudo imaxe tls statusتريد التفصيل نطاقًا نطاقًا، مع الأيام المتبقّية ومسار الـ fullchain؟ استخدم list:
$ sudo imaxe tls list3
افرِض تجديدًا
عادةً ما يكون تلقائيًّا، لكن يمكنك تقديمه إن احتجت.
جدِّد كل الشهادات القريبة من الانتهاء (هذا بالضبط ما يفعله المؤقّت):
$ sudo imaxe tls renewتريد تجربته أولًا دون المساس بالقرص، أو التجديد ولو بقيت أيام؟ أضِف --dry-run أو --force:
$ sudo imaxe tls renew --dry-run
$ sudo imaxe tls renew --force4
ألغِ شهادة
أبطِل شهادة لدى السلطة (مثلًا إن تسرّب المفتاح).
ألغِ شهادة نطاق لدى Let's Encrypt، معطيًا السبب إن كنت تعرفه:
$ sudo imaxe tls revoke app.ejemplo.com --reason keycompromiseissue.5
احذف شهادة من القرص
توقّف عن إدارة نطاق لم تعد تستخدمه.
أزِل الشهادة ومفاتيحها من القرص. ملاحظة: هذا لا يلغيها لدى السلطة — لذلك استخدم revoke أولًا.
$ sudo imaxe tls delete tienda.ejemplo.comimaxe tls list ويتوقّف تجديده التلقائي.المشكلة الأشيع أن الـ DNS لم ينتشر بعد أو أن المنفذ 80 مغلق. انتظر بضع دقائق وأعِد المحاولة. وإن استمرّ، فجرّب وضع الاختبار أولًا بـ --staging (انظر المرجع) كي لا تستنفد حصّة محاولاتك.
صيغة الاستخدام #
imaxe tls <subcomando> [<dominio>...] [--email CORREO] [flags]الأوامر الفرعية التي تمسّ الشهادات تتطلّب صلاحيات root (استخدم sudo) لأنها تكتب في /etc/imaxe/ وتعيد تحميل خدمات النظام. أضِف --json إلى list أو status للحصول على مخرجات مقروءة آليًّا صالحة لكتابة السكربتات.
الأوامر الفرعية #
| الأمر الفرعي | ماذا يفعل | الرايات المعنية |
|---|---|---|
| issue | يصدر شهادة لنطاق واحد أو أكثر، محلًّا تحدّي ACME. | --email, --webroot, --standalone, --staging |
| renew | يجدّد الشهادات القريبة من الانتهاء ويعيد تحميل خادم الويب. مناسب لمؤقّت. | --dry-run, --force |
| list | يسرُد الشهادات المُدارة مع الأيام حتى الانتهاء ومسار الـ fullchain. | --json |
| status | ملخّص: عدد الشهادات، القريبة من الانتهاء، وحالة مؤقّت التجديد. | --json |
| revoke | يلغي شهادة بحسب النطاق لدى السلطة (ACME). | --reason |
| delete | يحذف الشهادة ومفاتيحها من القرص. لا يلغي لدى ACME. | — |
الوسائط والرايات #
| الراية | النوع | الافتراضي | الوصف |
|---|---|---|---|
| <dominio> مطلوب | string… | — | نطاق واحد أو أكثر للشهادة. في issue، الأول هو الأساسي (CN)؛ والبقية SANs. في revoke/delete، النطاق المراد العمل عليه. |
| string | tls.yml | بريد التواصل لحساب ACME. مطلوب في أول issue؛ وبعدها يُعاد استخدام الذي في tls.yml. | |
| --webroot | path | /var/www/html | المجلد الجذر لتحدّي HTTP-01. الطريقة الافتراضية. |
| --standalone | bool | false | يستخدم خادم certbot المدمج بدلًا من webroot. يتطلّب أن يكون المنفذ 80 حرًّا. |
| --staging | bool | false | يستخدم بيئة اختبار Let's Encrypt (لا تُحسب ضمن حدّ المعدّل). لن تكون الشهادة موثوقة. |
| --dry-run | bool | false | في renew، يحاكي التجديد دون المساس بالقرص. |
| --force | bool | false | في renew، يجدّد ولو لم يكن قريبًا من الانتهاء. |
| --reason | enum | unspecified | في revoke: unspecified، keycompromise، superseded، cessationofoperation. |
| --json | bool | false | في list/status، يُصدر النتيجة بصيغة JSON في stdout. |
الملفات والمسارات #
| المسار | المحتوى |
|---|---|
| /etc/imaxe/tls.yml | إعداد الوحدة: البريد الافتراضي، الطريقة (webroot/standalone)، webroot، staging، التجديد التلقائي وخطّاف إعادة التحميل. |
| /etc/letsencrypt/live/<dominio>/ | الشهادة (fullchain.pem) والمفتاح الخاص (privkey.pem) اللذان يديرهما certbot. |
| /var/log/imaxe/tls.log | سجلّ مُهيكَل لكل إصدار وتجديد وإلغاء. |
| imaxe-tls.timer | مؤقّت systemd يُطلِق renew دوريًّا. |
مثال على tls.yml:
email: [email protected]
default_method: webroot
webroot: /var/www/html
staging: false
auto_renew: true
reload_hook: systemctl reload nginxرموز الخروج والسجلّات #
يعيد كل تنفيذ رمزًا يمكنك فحصه بـ echo $? — مفيد للتسلسل في السكربتات:
تابِع السجلّ مباشرةً أثناء تصحيح الأخطاء:
$ sudo journalctl -u imaxe-tls -f
$ sudo tail -f /var/log/imaxe/tls.logأمثلة متقدّمة #
عدّة نطاقات في شهادة واحدة
النطاق الأول هو الأساسي؛ والتالية تُضاف كـ SANs، جميعها في شهادة واحدة:
$ sudo imaxe tls issue ejemplo.com www.ejemplo.com \
--email [email protected]اختبار آمن قبل الإنتاج
تحقّق من السلسلة كاملةً مقابل بيئة الاختبار كي لا تستنفد حصّتك الحقيقية. مع --standalone لا تحتاج خادم ويب مهيّأً:
$ sudo imaxe tls issue app.ejemplo.com \
--email [email protected] --standalone --staging \
|| echo "falló con código $?"حل المشكلات #
| العَرَض | السبب المحتمل | الحل |
|---|---|---|
| يعيد CHALLENGE (الرمز 3) | النطاق لا يُحلّ إلى هذا المضيف أو المنفذ 80 مغلق. | تحقّق من سجلّ A/AAAA وافتح المنفذ 80 في مجموعة الأمان؛ أعِد المحاولة. |
| يعيد RATELIMIT (الرمز 4) | إصدارات كثيرة للنطاق نفسه في أسبوع واحد. | استخدم --staging للاختبار؛ وانتظر تحرّر النافذة. |
| يُحمَّل HTTPS لكن بتحذير | صدرت بـ --staging: الشهادة غير موثوقة. | أعِد الإصدار دون --staging للحصول على شهادة صالحة. |
| يعيد RELOAD (الرمز 5) | يشير reload_hook إلى خدمة غير موجودة. | اضبط reload_hook في tls.yml ونفّذ renew من جديد. |
هل واجهتك مشكلة مع وحدة TLS؟
راسلنا مرفقًا مخرجات «imaxe <module> status --json» وسنرد عليك بسرعة.