لنأخذ شركة صغيرة تخزن منتجات مبردة، ركبت في غرفة التبريد جهازاً يقيس الحرارة كل ثانيتين ويرسلها إلى سيرفر في المكتب، وعلى السيرفر خدمة تحفظ القراءات ولوحة يتابعها الفريق. وبعد أسابيع من العمل بدأت الأسئلة الصعبة تظهر واحداً بعد الآخر: الكهرباء انقطعت عن غرفة التبريد عشر دقائق، فهل يعرف أحد أن الجهاز توقف أم أن اللوحة ما زالت تعرض آخر رقم جيد؟ وأعيد تشغيل السيرفر لتحديث أمني، فأين ذهبت القراءات التي أرسلها الجهاز في تلك الدقيقة؟ وأحد الموظفين ركب جهازاً ثانياً للغرفة الثانية ونسخ إليه برنامج الجهاز الأول كما هو، فلماذا بدأ الجهازان يختفيان ويظهران كل ثانية؟ وأحد الزملاء سأل السؤال الذي يجب أن يسأله الجميع: من يستطيع أن يرسل إلى الجهاز أمر «أطفئ الضاغط»؟
وكل هذه الأسئلة إجاباتها في مكان واحد، هو الوسيط Broker الذي تمر به كل الرسائل، وفي البروتوكول الذي يتكلمه، وهو MQTT. وفي مقال إنترنت الأشياء من الحساس إلى لوحة المتابعة، أول مقال في هذه السلسلة، بنينا المسار كاملاً ورأينا أن إعدادين في المستقبل حولا 137 قراءة مفقودة إلى صفر، وفي هذا المقال سوف نأخذ الوسيط وحده ونفهمه من الداخل مع Mosquitto، فنرى كل ميزة في البروتوكول بمخرج حقيقي من الأدوات mosquitto_pub وmosquitto_sub، ثم نغلق الوسيط بالتشفير وكلمات المرور والصلاحيات. والمواضيع في السلسلة:
- إنترنت الأشياء IoT من الحساس إلى لوحة المتابعة.
- بروتوكول MQTT مع Mosquitto (الموضوع الحالي).
- Home Assistant مع ESPHome: أجهزة وأتمتة على سيرفرك.
- لوحات المتابعة لإنترنت الأشياء مع Node-RED وGrafana.
- تحديث الأجهزة عن بعد OTA دون أن تتعطل.
- أمن إنترنت الأشياء: الأجهزة التي ينساها الجميع.
وسوف نناقش في هذا المقال ما يلي:
- لماذا Mosquitto، وما الذي تغير في الإصدار 2.1 الذي صدر هذا العام.
- ما يحدث في الاتصال نفسه: اسم الكلاينت والجلسة ومدة keepalive، وكيف تقرؤها من سجل الوسيط.
- المواضيع Topics والمرشحات Wildcards، ومواضيع
$SYSالتي يراقب بها الوسيط نفسه. - مستويات التسليم QoS الثلاثة برسائلها الحقيقية، ولماذا وصلت رسالة QoS 2 على أنها QoS 0.
- الرسالة المحفوظة Retained والوصية Last Will، وثلاث طرق لاختفاء الجهاز وأيها يرسل الوصية.
- الجلسة الدائمة Persistent Session، وتجربة «ماذا يحدث إذا أعيد تشغيل الوسيط؟» مع الحفظ وبدونه.
- ميزات MQTT 5: الاشتراك المشترك Shared Subscription وانتهاء صلاحية الرسالة ورموز السبب Reason Codes، ومشكلة جهازين باسم واحد.
- الأمان: TLS بشهادة من سلطة خاصة بك، وكلمات المرور والصلاحيات بإضافات Mosquitto 2.1، ومشكلتان واجهتانا في التشغيل.
- Mosquitto في الإنتاج، والأخطاء الشائعة، وقائمة تحقق.
لماذا Mosquitto؟ وما الجديد في 2.1؟
Mosquitto وسيط MQTT مفتوح المصدر من مؤسسة Eclipse، مكتوب بلغة C، ويأتي معه الكلاينتان mosquitto_pub وmosquitto_sub ومكتبة libmosquitto، ويقول ملف الرخصة في مستودعه إنه مرخص برخصة مزدوجة EPL-2.0 أو EDL-1.0، والأخيرة هي نفسها BSD-3-Clause، أي أنك تستطيع أن تستخدمه في منتج تجاري دون أن تنشر كودك. والسبب في شهرته أنه صغير جداً، فالـ Docker Image الرسمي eclipse-mosquitto:2.1.2-alpine حجمه قرابة 13 ميجابايت، ويعمل على Raspberry Pi وعلى سيرفر كبير بالإعداد نفسه، ويكفي لمئات أو آلاف الأجهزة في شركة صغيرة أو متوسطة. وهناك وسطاء آخرون مفتوحو المصدر مثل EMQX وVerneMQ وNanoMQ، وكلها تتكلم MQTT نفسه، فالأجهزة لا تعرف ولا تهتم أي وسيط على الطرف الآخر، وما تتعلمه هنا عن البروتوكول ينتقل معك إلى أي منها.
وفي 29 يناير 2026 صدر الإصدار 2.1.0، ثم 2.1.1 و2.1.2 في فبراير، وفي سجل التغييرات عدة أشياء تهمك إذا كنت تنقل إعداداً قديماً:
- الخياران
password_fileوacl_fileأصبحا قديمين Deprecated لصالح إضافتين Plugins بالكود نفسه، وسوف يحذفان في الإصدار 3.0، وكذلكper_listener_settingsلصالح خيارات خاصة بكل منفذ مثلlistener_allow_anonymous، وهذا ما سوف نستخدمه في قسم الأمان. - الحد الافتراضي لحجم الرسالة
max_packet_sizeأصبح 2,000,000 بايت بعد أن كان حد البروتوكول 256 ميجابايت، فإذا كانت أجهزتك ترسل ملفات أو صوراً فعليك أن ترفعه بنفسك. - أضيف الخيار
--test-configالذي يفحص ملف الإعداد قبل التشغيل، وأصبح الوسيط يكتب في السجل إصدار البروتوكول والتشفير الذي اتفق عليه كل كلاينت، وأضيف إرسال DISCONNECT بالسبب «session taken over» لكلاينت MQTT 5 الذي يدخل غيره باسمه، وسوف نرى الثلاثة في المختبر.
المختبر Lab: الوسيط وأدوات الكلاينت
سوف نبدأ بوسيط دون أي حماية حتى نرى البروتوكول نفسه، ثم نغلقه في آخر المقال. وكل شيء يعمل على شبكة Docker خاصة اسمها iot-mq-net، دون أي منفذ منشور على جهازك، والكلاينت نفسه Container مؤقت من الـ Image نفسه. والإعداد الأول mosquitto-open.conf:
# Step 1: the broker with no security, to see the protocol itself. Reachable only inside iot-mq-net.
listener 1883
allow_anonymous true
persistence true
persistence_location /mosquitto/data/
log_dest stdout
log_type all
connection_messages trueوالخيار log_type all يجعل الوسيط يكتب كل رسالة يرسلها ويستقبلها، وهذا مفيد جداً للتعلم وغير مناسب للإنتاج لأنه يملأ السجل بسرعة. والتشغيل وفحص الإعداد كما يلي:
docker network create iot-mq-net
docker run -d --name iot-mq --network iot-mq-net \
-v "$PWD/mosquitto-open.conf:/mosquitto/config/mosquitto.conf:ro" \
-v iot-mq-data:/mosquitto/data eclipse-mosquitto:2.1.2-alpine
docker run --rm eclipse-mosquitto:2.1.2-alpine mosquitto --test-config -c /mosquitto/config/mosquitto.conf
# a shortcut for the client commands in the rest of the article
cli() { docker run --rm --network iot-mq-net eclipse-mosquitto:2.1.2-alpine "$@"; }والمخرج:
1793923471: Configuration file is OK.
1793923471: mosquitto version 2.1.2 terminatingولاحظ أن الفحص بدأ الوسيط وأنهاه مباشرة دون أن يفتح أي منفذ، فهو آمن على سيرفر يعمل فيه وسيط آخر. والدالة cli اختصار فقط، حتى يكون كل أمر في المقال Container كلاينت مستقلاً على الشبكة نفسها، كما يكون الجهاز الحقيقي على الشبكة.
الاتصال CONNECT: اسم الكلاينت والجلسة ومدة keepalive
كل شيء في MQTT يبدأ برسالة CONNECT يرسلها الكلاينت بعد أن يفتح اتصال TCP، وفيها أهم القرارات التي تحدد سلوكه كله: اسم الكلاينت Client ID الذي يعرفه به الوسيط، وعلامة الجلسة النظيفة Clean Session التي تقول هل ينسى الوسيط كل شيء عنه عند انقطاعه، ومدة keepalive التي يعد بأن يرسل خلالها شيئاً ولو إشارة حياة، والوصية Last Will إن وجدت، واسم المستخدم وكلمة المرور. ويرد الوسيط بـ CONNACK فيه رمز النتيجة. والوسيط يكتب هذه القرارات في سجله مع كل اتصال، كما في هذا السطر من المختبر:
1793924024: New client connected from 172.18.0.3:44438 as auto-2C8D383F-C056-E392-9854-392830458DB9 (p5, c1, k60, u'room1-temp').والقوسان فيهما أربع معلومات: p5 إصدار البروتوكول، وهنا 5 أي MQTT 5.0، و4 تعني 3.1.1 بحسب رقم الإصدار داخل البروتوكول نفسه، وc1 جلسة نظيفة وc0 جلسة دائمة، وk60 مدة keepalive بالثواني وهي القيمة الافتراضية في أدوات Mosquitto، وu'room1-temp' اسم المستخدم. ولاحظ اسم الكلاينت نفسه: لم نعطه اسماً، فأعطاه الوسيط اسماً عشوائياً يبدأ بـ auto-، وهذا مقبول لأداة تجرب أمراً واحداً، ولكنه خطأ في جهاز حقيقي أو خدمة، لأن الاسم هو الذي يربط الكلاينت بجلسته، والاسم العشوائي يعني جلسة جديدة مع كل اتصال.
أما keepalive فتحدد متى يعرف الوسيط أن الكلاينت اختفى، وتقول مواصفة MQTT 5.0 إن الوسيط يجب أن يغلق الاتصال إذا لم يصله أي شيء من الكلاينت خلال مرة ونصف مدة keepalive. وهذا يعني أن جهازاً بـ keepalive قيمتها 60 ثانية قد يبقى «متصلاً» في نظر الوسيط دقيقة ونصفاً بعد أن انقطعت عنه الكهرباء، والقيمة القصيرة تكشف الانقطاع بسرعة ولكنها تكلف إشارات حياة أكثر، وهذا قرار يعتمد على البطارية والشبكة، وسوف نرى أثره بالثواني في تجربة الوصية.
المواضيع Topics مع المرشحات Wildcards
اسم الموضوع نص مقسم بالشرطة المائلة / إلى مستويات، والوسيط لا يحتاج أن تنشئه مسبقاً، فأول رسالة عليه تكفي. والمشترك يكتب مرشحاً Topic Filter قد يحتوي رمزين: + بدل مستوى واحد، و# بدل هذا المستوى وكل ما بعده، ولا يأتي إلا في آخر المرشح. والصورة التالية تبين ثلاثة مشتركين بمرشحات مختلفة وما يصل لكل منهم:

والوسيط يرفض المرشح غير الصحيح من البداية، كما حدث عندما جربنا وضع # في وسط المرشح:
-- coldstore/#/telemetry
Error: Invalid subscription topic 'coldstore/#/telemetry', are all '+' and '#' wildcards correct?وهناك فرع خاص من المواضيع يبدأ بـ $SYS، ينشر فيه Mosquitto معلومات عن نفسه كل فترة، مثل عدد الكلاينتات المتصلة وعدد الرسائل المحفوظة وإصداره، ولا يصل إلى المرشح # العادي حتى لا يختلط بمواضيع التطبيق، وإنما تشترك فيه باسمه:
cli mosquitto_sub -h iot-mq -v -t '$SYS/broker/retained messages/count' \
-t '$SYS/broker/clients/connected' -t '$SYS/broker/version' -C 3$SYS/broker/retained messages/count 57
$SYS/broker/clients/connected 1
$SYS/broker/version mosquitto version 2.1.2والرقم 57 للرسائل المحفوظة قد يبدو كبيراً ونحن لم نحفظ إلا ثلاثاً، والسبب أن مواضيع $SYS نفسها محفوظة، فكل مشترك جديد يجد آخر قيمة لها فوراً. وهذه المواضيع هي أسهل طريقة لمراقبة الوسيط من Prometheus أو أي أداة أخرى، وقد شرحنا المراقبة بالمقاييس في مقال Prometheus مع Grafana.
مستويات التسليم QoS: ثلاثة وعود مختلفة
مستوى التسليم Quality of Service، واختصاراً QoS، هو الوعد الذي يتفق عليه طرفان حول رسالة واحدة: هل يكفي أن ترسلها، أم يجب أن يتأكد المرسل أنها وصلت، أم يجب أن تصل مرة واحدة بالضبط؟ ولكل مستوى رسائل إضافية يتبادلها الطرفان، والأفضل أن تراها بعينك. لذلك شغلنا مشتركاً بمستوى 2 مع الخيار -d الذي يطبع كل رسالة بروتوكول، ثم نشرنا القراءة نفسها ثلاث مرات بالمستويات الثلاثة:
docker run -d --name iot-mq-sub --network iot-mq-net eclipse-mosquitto:2.1.2-alpine \
mosquitto_sub -h iot-mq -d -v -q 2 -i sub-dashboard -t 'coldstore/#'
for q in 0 1 2; do
cli mosquitto_pub -h iot-mq -d -i room1-temp -q $q -t coldstore/store1/room1-temp/telemetry -m "{\"seq\":$((10+q)),\"temp_c\":4.1}"
doneوالمخرج من جهة الناشر:
== QoS 0
Client room1-temp sending CONNECT
Client room1-temp received CONNACK (0)
Client room1-temp sending PUBLISH (d0, q0, r0, m1, 'coldstore/store1/room1-temp/telemetry', ... (23 bytes))
Client room1-temp sending DISCONNECT
== QoS 1
Client room1-temp sending CONNECT
Client room1-temp received CONNACK (0)
Client room1-temp sending PUBLISH (d0, q1, r0, m1, 'coldstore/store1/room1-temp/telemetry', ... (23 bytes))
Client room1-temp received PUBACK (Mid: 1, RC:0)
Client room1-temp sending DISCONNECT
== QoS 2
Client room1-temp sending CONNECT
Client room1-temp received CONNACK (0)
Client room1-temp sending PUBLISH (d0, q2, r0, m1, 'coldstore/store1/room1-temp/telemetry', ... (23 bytes))
Client room1-temp received PUBREC (Mid: 1)
Client room1-temp sending PUBREL (m1)
Client room1-temp received PUBCOMP (Mid: 1, RC:0)
Client room1-temp sending DISCONNECTومن جهة المشترك:
Client sub-dashboard sending SUBSCRIBE (Mid: 1, Topic: coldstore/#, QoS: 2, Options: 0x00)
Client sub-dashboard received SUBACK
Subscribed (mid: 1): 2
Client sub-dashboard received PUBLISH (d0, q0, r0, m0, 'coldstore/store1/room1-temp/telemetry', ... (23 bytes))
coldstore/store1/room1-temp/telemetry {"seq":10,"temp_c":4.1}
Client sub-dashboard received PUBLISH (d0, q1, r0, m1, 'coldstore/store1/room1-temp/telemetry', ... (23 bytes))
Client sub-dashboard sending PUBACK (m1, rc0)
coldstore/store1/room1-temp/telemetry {"seq":11,"temp_c":4.1}
Client sub-dashboard received PUBLISH (d0, q2, r0, m2, 'coldstore/store1/room1-temp/telemetry', ... (23 bytes))
Client sub-dashboard sending PUBREC (m2, rc0)
Client sub-dashboard received PUBREL (Mid: 2)
Client sub-dashboard sending PUBCOMP (m2)
coldstore/store1/room1-temp/telemetry {"seq":12,"temp_c":4.1}وفي المخرج أعلاه لاحظ التالي:
- الأقواس بعد PUBLISH فيها أعلام الرسالة:
d0أنها ليست إعادة إرسال Duplicate، وqمستواها، وr0أنها ليست محفوظة، وmرقم الرسالة Message ID الذي تربط به الردود، ثم الموضوع وحجم المحتوى. - في QoS 0 لا يوجد أي رد، والناشر يرسل ثم ينسى، وإذا ضاعت الرسالة في الشبكة فلا أحد يعرف. ولاحظ أن رقم الرسالة عند المشترك
m0، لأن المستوى 0 لا يحتاج رقماً. - في QoS 1 يرد المستقبل بـ PUBACK، والمرسل يحتفظ بالرسالة ويعيد إرسالها بعلامة
d1حتى يصله الرد، فالرسالة تصل مرة على الأقل، وقد تصل مرتين إذا ضاع الرد نفسه. - في QoS 2 أربع رسائل بدل واحدة: PUBLISH ثم PUBREC «استلمت» ثم PUBREL «احذفها من عندك» ثم PUBCOMP «انتهينا»، وهذه المصافحة هي التي تضمن أن الرسالة تسلم للتطبيق مرة واحدة بالضبط.
- والأهم أن الوعد بين طرفين فقط: من الناشر إلى الوسيط، ثم من الوسيط إلى كل مشترك على حدة، ولكل منهما رقم رسالة مختلف، فالقراءة 12 كانت
m1عند الناشر وm2عند المشترك.
والصورة التالية تلخص المستويات الثلاثة:

ولنرى النقطة الأخيرة بوضوح، اشترك كلاينت آخر بمستوى 0، ثم نشرنا رسالة بمستوى 2:
Subscribed (mid: 1): 0
Client sub-q0 received PUBLISH (d0, q0, r0, m0, 'coldstore/store1/room1-temp/telemetry', ... (23 bytes))
coldstore/store1/room1-temp/telemetry {"seq":13,"temp_c":4.0}فالرسالة نشرت بـ QoS 2، ووصلت إلى هذا المشترك بـ q0، لأن الوسيط يسلم لكل مشترك بالأقل بين مستوى النشر ومستوى الاشتراك. وهذا يعني أن جهازاً ينشر أمراً مهماً بـ QoS 2 لا يضمن شيئاً إذا كان البرنامج الذي يستقبله اشترك بـ QoS 0، وأن المستوى قرار على الطرفين وليس على الناشر وحده.
وقد يتساءل البعض: إذا كان QoS 2 أضمن، فلماذا لا نستخدمه دائماً؟ والإجابة أنه أربع رسائل ذهاباً وإياباً لكل قراءة، والجهاز يجب أن يحتفظ بحالة كل رسالة حتى تكتمل، وهذا مكلف لجهاز على بطارية يرسل كل ثانيتين. والاختيار العملي في أغلب الأنظمة: QoS 0 لقراءات متكررة إذا ضاعت واحدة جاءت بعدها أحدث منها بثوان، وQoS 1 للقراءات التي تحتاج سجلاً كاملاً وللحالة، مع رقم تسلسلي يكشف التكرار عند الاستقبال، وQoS 2 فقط لأمر لا يحتمل التنفيذ مرتين.
الرسالة المحفوظة Retained: آخر قيمة لكل مشترك جديد
الوسيط في الأصل لا يحفظ الرسائل، فإذا نشرت رسالة ولم يكن هناك مشترك فهي تضيع. ولكن هناك أشياء تريد أن يعرفها كل من يشترك في أي وقت، مثل حالة الجهاز الآن أو إعداده الحالي، وهذا عمل علامة الحفظ Retain: الوسيط يحتفظ بآخر رسالة محفوظة على كل موضوع، ويرسلها فوراً لكل مشترك جديد. ونشرنا رسالتين محفوظتين بالخيار -r، ثم اشترك كلاينت جديد:
cli mosquitto_pub -h iot-mq -r -q 1 -t coldstore/store1/room1-temp/status -m online
cli mosquitto_pub -h iot-mq -r -q 1 -t coldstore/store1/room1-temp/config -m '{"period_s":30,"max_c":8}'
cli mosquitto_sub -h iot-mq -d -v -t 'coldstore/store1/room1-temp/#' -W 2Client (null) received CONNACK (0)
Subscribed (mid: 1): 0
Client null received PUBLISH (d0, q0, r1, m0, 'coldstore/store1/room1-temp/status', ... (6 bytes))
coldstore/store1/room1-temp/status online
Client null received PUBLISH (d0, q0, r1, m0, 'coldstore/store1/room1-temp/config', ... (25 bytes))
coldstore/store1/room1-temp/config {"period_s":30,"max_c":8}
Timed outولاحظ العلامة r1 على الرسالتين، فهي تقول للمشترك إن هذه رسالة محفوظة من الماضي وليست حدثاً جديداً، والتطبيق الجيد يفرق بين الاثنين، فلا يطلق تنبيهاً على حالة قديمة كأنها حدثت الآن. و-W 2 يجعل الأداة تخرج بعد ثانيتين، ولهذا ظهرت Timed out. ولحذف رسالة محفوظة تنشر رسالة محفوظة فارغة على الموضوع نفسه بالخيار -n:
cli mosquitto_pub -h iot-mq -r -n -t coldstore/store1/room1-temp/config
cli mosquitto_sub -h iot-mq -v -t 'coldstore/store1/room1-temp/#' -W 2coldstore/store1/room1-temp/status online
Timed outوالرسائل المحفوظة مفيدة جداً، ولها خطآن شائعان. الأول أن تحفظ القراءات نفسها، فإذا توقف الجهاز يبقى آخر رقم محفوظاً إلى الأبد، وكل لوحة جديدة تعرضه كأنه حرارة الغرفة الآن، ولذلك احفظ الحالة والإعداد، ولا تحفظ القراءة إلا إذا كان معها وقتها، والتطبيق يتحقق من عمرها. والثاني أخطر، وهو أن تحفظ أمراً، فالأمر المحفوظ «أطفئ الضاغط» ينفذ من جديد كلما أعيد تشغيل الجهاز واشترك في موضوع الأوامر، ولو بعد شهر.
الوصية Last Will: كيف يعرف الوسيط أن الجهاز اختفى؟
الوصية Last Will رسالة يسلمها الكلاينت للوسيط في رسالة CONNECT نفسها، ويقول له: إذا اختفيت دون أن أودعك، فانشر هذه الرسالة نيابة عني. والاستخدام الأشهر أن يكون موضوع الوصية هو موضوع الحالة، بالمحتوى offline وعلامة الحفظ، والجهاز نفسه ينشر online محفوظة فور اتصاله، وبهذا الشكل يجد أي مشترك في أي وقت حالة كل جهاز دون أن يسأله. ولكن السؤال المهم هو متى بالضبط يعتبر الوسيط أن الجهاز اختفى؟ وهناك ثلاث طرق لاختفاء الجهاز، وجربناها كلها.
الطريقة الأولى هي انقطاع الكهرباء أو الشبكة، حيث يتوقف الجهاز فجأة دون أن يرسل شيئاً، ولا يصل إلى الوسيط حتى إغلاق TCP. وأقرب محاكاة لذلك أن نجمد Container الجهاز بالأمر docker pause، فيبقى الاتصال مفتوحاً في نظر الوسيط ولكن لا يصل منه أي شيء. شغلنا الجهاز بـ keepalive قيمتها 10 ثوان ووصية، ومراقباً يطبع الوقت مع كل رسالة حالة:
docker run -d --name iot-mq-watch --network iot-mq-net eclipse-mosquitto:2.1.2-alpine \
mosquitto_sub -h iot-mq -F '%I %t %p' -t 'coldstore/+/+/status'
docker run -d --name iot-mq-dev --network iot-mq-net eclipse-mosquitto:2.1.2-alpine \
mosquitto_sub -h iot-mq -i room2-temp -k 10 --will-topic coldstore/store1/room2-temp/status \
--will-payload offline --will-qos 1 --will-retain -t coldstore/store1/room2-temp/cmd
cli mosquitto_pub -h iot-mq -r -q 1 -t coldstore/store1/room2-temp/status -m online
docker pause iot-mq-devوالمخرج من المراقب ومن سجل الوسيط:
2026-11-06T00:06:45+0000 coldstore/store1/room2-temp/status online
2026-11-06T00:06:57+0000 coldstore/store1/room2-temp/status offline
1793923617: Client room2-temp [172.18.0.5:55120] disconnected: exceeded timeout.جمدنا الجهاز في 00:06:47، ووصلت الوصية في 00:06:57، أي بعد 10 ثوان من الانقطاع، وسبب الانقطاع في سجل الوسيط exceeded timeout، أي أن المدة مرت دون أي رسالة. والمدة الفعلية تحسب من آخر رسالة وصلت من الجهاز وليس من لحظة الانقطاع، ولهذا قد تكون أقل من 15 ثانية التي تعطيها قاعدة المرة ونصف المرة لـ keepalive قيمتها 10. وبالقيمة الافتراضية 60 ثانية كان الانتظار سيصل إلى دقيقة ونصف.
والطريقتان الأخريان هما توقف البرنامج نفسه، وجربناهما بإرسال إشارتين مختلفتين للبرنامج:
INT at 00:07:20
KILL at 00:07:28
2026-11-06T00:07:28+0000 coldstore/store1/room3-temp/status offline-KILL
1793923641: Client room3-temp [172.18.0.5:49738] disconnected.
1793923648: Client room3-temp [172.18.0.5:41202] disconnected: connection closed by client.مع الإشارة SIGINT، وهي ما يحدث عندما تضغط Ctrl+C، أغلق البرنامج الاتصال بشكل طبيعي وأرسل رسالة DISCONNECT، فكتب الوسيط disconnected. فقط ولم يرسل أي وصية، لأن الكلاينت ودع فعلاً. ومع SIGKILL مات البرنامج فوراً وأغلق نظام التشغيل الاتصال دون DISCONNECT، فكتب الوسيط connection closed by client وأرسل الوصية offline-KILL في الثانية نفسها. والصورة التالية تجمع التجارب:

والدرس العملي من هذا: إذا أردت أن يعرف النظام بإعادة التشغيل المقصودة أيضاً، فاجعل الجهاز ينشر offline محفوظة بنفسه قبل أن يغلق الاتصال، لأن الإغلاق الطبيعي لا يطلق الوصية. وفي MQTT 5 هناك أيضاً تأخير الوصية Will Delay Interval، الذي يجعل الوسيط ينتظر قليلاً قبل نشرها، فإذا عاد الجهاز خلال المدة لا تنشر، وهذا مفيد للأجهزة على شبكة جوال تنقطع ثوان وتعود.
الجلسة الدائمة Persistent Session: رسائل المشترك الغائب
في المقال السابق رأينا أن الرسائل التي نشرت وخدمة الاستقبال غائبة ضاعت كلها، لأن جلستها كانت نظيفة. والحل هو الجلسة الدائمة: يتصل الكلاينت باسم ثابت وعلامة Clean Session مطفأة، فيحتفظ الوسيط باشتراكاته بعد انقطاعه، ويجمع له في طابور كل رسالة QoS 1 أو 2 تطابق اشتراكاته. وفي أدوات Mosquitto الخيار -c هو الذي يطفئ الجلسة النظيفة. أنشأنا الجلسة ثم خرجنا، ونشرنا ثلاث قراءات بـ QoS 1 وقراءتين بـ QoS 0، ثم عدنا بالاسم نفسه:
cli mosquitto_sub -h iot-mq -c -i ingest-1 -q 1 -t 'coldstore/+/+/telemetry' -W 1
for i in 1 2 3; do cli mosquitto_pub -h iot-mq -q 1 -t coldstore/store1/room1-temp/telemetry -m "{\"seq\":$((100+i)),\"q\":1}"; done
for i in 4 5; do cli mosquitto_pub -h iot-mq -q 0 -t coldstore/store1/room1-temp/telemetry -m "{\"seq\":$((100+i)),\"q\":0}"; done
cli mosquitto_sub -h iot-mq -c -i ingest-1 -q 1 -t 'coldstore/+/+/telemetry' -W 2 -v -dClient ingest-1 received CONNACK (0)
Client ingest-1 received PUBLISH (d0, q1, r0, m1, 'coldstore/store1/room1-temp/telemetry', ... (17 bytes))
coldstore/store1/room1-temp/telemetry {"seq":101,"q":1}
Client ingest-1 received PUBLISH (d0, q1, r0, m2, 'coldstore/store1/room1-temp/telemetry', ... (17 bytes))
coldstore/store1/room1-temp/telemetry {"seq":102,"q":1}
Client ingest-1 received PUBLISH (d0, q1, r0, m3, 'coldstore/store1/room1-temp/telemetry', ... (17 bytes))
coldstore/store1/room1-temp/telemetry {"seq":103,"q":1}
Subscribed (mid: 1): 1
Timed outوفي المخرج لاحظ التالي:
- وصلت القراءات 101 و102 و103 قبل أن يصل رد الاشتراك
Subscribed، لأن الوسيط كان يعرف الاشتراك من الجلسة القديمة، فأرسل الطابور فور الاتصال. - القراءتان 104 و105 بـ QoS 0 لم تصلا، وهذا ما يقوله البروتوكول نفسه، وفي Mosquitto خيار غير معياري
queue_qos0_messagesيغير ذلك، وقيمته الافتراضية false بحسب صفحة الإعداد. - الطابور له حد، فالخيار
max_queued_messagesقيمته الافتراضية 1000 رسالة لكل كلاينت، وما زاد يرمى. فإذا كان لديك 50 جهازاً ترسل كل ثانيتين، فهذا الحد يمتلئ في 40 ثانية فقط من غياب خدمة الاستقبال، وعليك أن تحسبه وترفعه أو تجعله بالحجمmax_queued_bytes. - والجلسة الدائمة لكلاينت لا يعود أبداً تبقى في ذاكرة الوسيط إلى الأبد، ولذلك هناك الخيار
persistent_client_expirationالذي يحذف الجلسات الغائبة بعد مدة تحددها مثل14d.
ماذا يحدث إذا أعيد تشغيل الوسيط Broker Restart؟
الجلسة الدائمة تحمي من غياب المشترك، ولكن ماذا لو كان الوسيط نفسه هو الذي أعيد تشغيله لتحديث أو عطل؟ هنا يأتي دور الخيار persistence. ففي الإعداد الأول كان مفعلاً، فنشرنا ثلاث قراءات أخرى بـ QoS 1 والخدمة غائبة، ثم أعدنا تشغيل الوسيط:
1793923694: Saving in-memory database to /mosquitto/data//mosquitto.db.
1793923696: Restored 6 base messages
1793923696: Restored 3 retained messages
1793923696: Restored 1 clients
1793923696: Restored 1 subscriptions
1793923696: Restored 3 client messages
coldstore/store1/room1-temp/telemetry {"seq":201}
coldstore/store1/room1-temp/telemetry {"seq":202}
coldstore/store1/room1-temp/telemetry {"seq":203}عند التوقف حفظ الوسيط كل ما في ذاكرته في الملف mosquitto.db داخل الـ Volume، وعند العودة استعاد جلسة واحدة دائمة هي ingest-1 مع اشتراكها والرسائل الثلاث في طابورها، فوصلت كلها عند عودة الخدمة. ولاحظ «Restored 3 retained messages»: حالات الأجهزة المحفوظة عادت أيضاً.
ثم كررنا الشيء نفسه بالإعداد ذاته مع تغيير سطر واحد إلى persistence false:
1793923727: mosquitto version 2.1.2 starting
== ingest-1 after restart
Timed out
== retained after restart
Timed outلا توجد أي أسطر Restored، والخدمة عادت فلم تجد شيئاً، والقراءات الثلاث ضاعت، والحالة المحفوظة online ضاعت أيضاً، فأي لوحة جديدة لن تعرف حالة أي جهاز حتى يعيد نشرها. والصورة التالية تلخص الجلسة الدائمة والتجربتين:

ولاحظ هنا أمرين: الأول أن الحفظ يحدث عند التوقف الطبيعي وكل فترة يحددها autosave_interval، وقيمتها الافتراضية 1800 ثانية بحسب صفحة الإعداد، فإذا انقطعت الكهرباء عن السيرفر فجأة فقد تضيع الرسائل التي وصلت بعد آخر حفظ، وفي Mosquitto 2.1 إضافة persist-sqlite بديلة تكتب باستمرار في قاعدة SQLite لمن يحتاج ذلك. والثاني أن الحفظ يحتاج Volume دائماً، فـ Container الوسيط دون Volume على /mosquitto/data يفقد كل شيء عند إعادة إنشائه حتى مع persistence true.
ميزات MQTT 5: الاشتراك المشترك Shared Subscription، وانتهاء الصلاحية Message Expiry
الإصدار 5.0 من البروتوكول أضاف ميزات كثيرة، وثلاث منها تهمك مباشرة في إنترنت الأشياء. الأولى الاشتراك المشترك Shared Subscription: عندما تكبر الأجهزة لا تكفي نسخة واحدة من خدمة الاستقبال، ولو شغلت نسختين باشتراك عادي لوصلت كل رسالة للاثنتين وحفظت مرتين. والحل أن تشترك النسختان في مجموعة باسم يبدأ بـ $share/، فيوزع الوسيط الرسائل بينهما ويرسل كل رسالة لواحدة فقط:
for w in a b; do
docker run -d --name iot-mq-w$w --network iot-mq-net eclipse-mosquitto:2.1.2-alpine \
mosquitto_sub -h iot-mq -V mqttv5 -i ingest-$w -q 1 -t '$share/ingest/coldstore/+/+/telemetry' -F "ingest-$w got %p"
done
for i in 1 2 3 4 5 6; do cli mosquitto_pub -h iot-mq -V mqttv5 -q 1 -t coldstore/store1/room1-temp/telemetry -m "{\"seq\":$((400+i))}"; doneingest-a got {"seq":401}
ingest-a got {"seq":403}
ingest-a got {"seq":405}
ingest-b got {"seq":402}
ingest-b got {"seq":404}
ingest-b got {"seq":406}وزع الوسيط القراءات بالتناوب، ولم تصل أي قراءة مرتين، وإذا توقفت إحدى النسختين فالأخرى تستقبل كل شيء. ولاحظ أن لكل نسخة اسماً مختلفاً، وهذا مهم كما سوف نرى بعد قليل.
والثانية انتهاء صلاحية الرسالة Message Expiry: تستطيع أن تقول للوسيط إن هذه الرسالة لا معنى لها بعد مدة معينة، فلا يسلمها لمشترك جديد ولا لطابور جلسة دائمة بعد انتهائها. ونشرنا تنبيه «الباب مفتوح» محفوظاً بصلاحية 5 ثوان:
cli mosquitto_pub -h iot-mq -V mqttv5 -r -q 1 -t coldstore/store1/room1-temp/alarm -m 'door open' \
-D publish message-expiry-interval 5
cli mosquitto_sub -h iot-mq -V mqttv5 -t coldstore/store1/room1-temp/alarm -W 1 -F '%t %p (expiry left: %E s)'
sleep 6
cli mosquitto_sub -h iot-mq -V mqttv5 -t coldstore/store1/room1-temp/alarm -v -W 1coldstore/store1/room1-temp/alarm door open (expiry left: 4 s)
Timed out
Timed outالمشترك الأول وصله التنبيه ومعه الوقت المتبقي من صلاحيته، أما بعد ست ثوان فلم يصل شيء، فقد حذفه الوسيط. وهذه الميزة هي الحل الصحيح لمشكلة القراءة المحفوظة القديمة التي ذكرناها، وللأوامر التي لا يجب أن تنفذ بعد ساعات من إرسالها.
والثالثة رموز السبب Reason Codes: في MQTT 3.1.1 كانت الردود تقول نجح أو فشل فقط، وفي أحيان كثيرة لا تقول شيئاً، أما في الإصدار 5 فكل رد فيه رمز يقول لماذا، وتعرضها المواصفة في جدول واحد، مثل 16 «لا يوجد مشتركون» و135 «غير مصرح» و142 «أخذت الجلسة». وسوف نرى الثلاثة في المختبر، وسوف نرى لماذا هذا الفرق مهم جداً في قسم الصلاحيات.
ماذا يفعل الجهاز عند العودة؟ عاصفة إعادة الاتصال Reconnect Storm
في تجربة إعادة تشغيل الوسيط كان لدينا كلاينت واحد يعود، أما في مستودع فيه مئة جهاز فكل الأجهزة تفقد الاتصال في اللحظة نفسها، وكلها تحاول العودة في اللحظة نفسها تقريباً، وكل جهاز يحمل معه طابوراً من القراءات المخزنة يريد أن يرسلها فوراً. وهذا ما يسمى عاصفة إعادة الاتصال Reconnect Storm، وفيها يستقبل الوسيط في ثانية واحدة مئة اتصال TLS جديد، وكل مصافحة TLS تكلف المعالج أكثر بكثير من رسالة عادية، ثم آلاف الرسائل المخزنة، فإذا كان السيرفر صغيراً فقد يبطئ إلى حد أن تفشل بعض المصافحات، فتعيد الأجهزة المحاولة، وتستمر العاصفة.
والحل على جهة الجهاز في ثلاث نقاط. الأولى الانتظار المتزايد Exponential Backoff مع حد أعلى معقول، كما رأينا في المقال السابق حيث كان الحد الافتراضي 120 ثانية في مكتبة paho طويلاً جداً. والثانية العشوائية Jitter: أن يضيف كل جهاز إلى مدة الانتظار جزءاً عشوائياً من الثانية أو الثانيتين، فتتوزع العودة على فترة بدل أن تأتي في لحظة واحدة، وهذه إضافة صغيرة في الكود ولكنها تغير شكل الضغط على الوسيط تماماً. والثالثة ألا يرسل الجهاز طابوره كله دفعة واحدة، وإنما على دفعات صغيرة، وهنا يساعد البروتوكول نفسه: في MQTT 5 يعلن كل طرف في CONNECT حداً اسمه Receive Maximum، وهو أكبر عدد من رسائل QoS 1 و2 التي تقبل أن تكون في الطريق دون تأكيد، وتقول ملاحظات الإصدار 2.1.1 في سجل التغييرات إن Mosquitto أصبح يكتب تحذيراً بدل أن يقطع الكلاينت الذي يتجاوز هذا الحد، حتى تتمكن من إصلاح الكلاينت المخالف بدل أن يختفي.
وعلى جهة الوسيط تستطيع أن تحمي نفسك بحدود واضحة: max_connections لكل منفذ، والخيار الجديد في 2.1 global_max_connections للوسيط كله، وmax_inflight_messages لعدد الرسائل في الطريق لكل كلاينت. وقد يتساءل البعض: أليس الأفضل ألا يرفض الوسيط أي اتصال؟ والإجابة أن الوسيط الذي يقبل كل شيء حتى تنفد ذاكرته يتوقف عن خدمة الجميع، أما الوسيط الذي يرفض بعض الاتصالات مؤقتاً فيبقى يعمل، والأجهزة المرفوضة تعود بعد ثوان بفضل الانتظار المتزايد، وهذا بالضبط سبب وجود الانتظار في الجهاز.
اسم الكلاينت Client ID: جهازان باسم واحد
نعود إلى الموظف الذي نسخ برنامج الجهاز الأول إلى الجهاز الثاني كما هو، فأصبح للجهازين الاسم نفسه room1-temp. والمواصفة تقول إن الوسيط إذا اتصل به كلاينت باسم موجود فعليه أن يقطع الاتصال القديم، وهذا منطقي لجهاز أعيد تشغيله قبل أن يعرف الوسيط أن اتصاله القديم مات. ولكن عندما يكون هناك جهازان فعلاً، وكل منهما يعيد الاتصال آلياً عند الانقطاع، فماذا يحدث؟ شغلنا كلاينتين بالاسم نفسه بفارق ثلاث ثوان:
== A
Client room1-temp sending SUBSCRIBE (Mid: 4, Topic: coldstore/store1/room1-temp/cmd, QoS: 0, Options: 0x00)
Client room1-temp received SUBACK
Subscribed (mid: 4): 0
Received DISCONNECT (142)
1793924085: Client room1-temp [172.18.0.4:57246] disconnected: session taken over.
1793924085: New client connected from 172.18.0.3:42330 as room1-temp (p5, c1, k60, u'room1-temp').
1793924086: Client room1-temp [172.18.0.3:42330] disconnected: session taken over.
1793924086: New client connected from 172.18.0.4:57250 as room1-temp (p5, c1, k60, u'room1-temp').الكلاينت A استقبل DISCONNECT برمز السبب 142، وهو «session taken over»، ثم أعاد الاتصال فطرد B، ثم أعاد B الاتصال فطرد A، وعددنا في سجل الوسيط 9 مرات من هذا الطرد المتبادل خلال قرابة 8 ثوان، وكل رسالة في الطريق أثناء ذلك معرضة للضياع، واللوحة ترى الجهاز يختفي ويظهر. وهذه بالضبط مشكلة الجهازين اللذين «يختفيان ويظهران كل ثانية» في قصتنا، وحلها أن يكون اسم الكلاينت فريداً لكل جهاز، ويأتي من شيء لا يتكرر مثل عنوان MAC أو رقم تسلسلي يكتب عند التصنيع، وليس من ملف إعداد ينسخ بين الأجهزة.

الأمان Security: TLS ثم كلمات المرور ثم الصلاحيات
كل ما سبق كان على وسيط يقبل أي أحد، ويقرأ أي أحد فيه أي شيء، ويكتب أي أحد على أي موضوع، بما في ذلك موضوع الأوامر. والآن نغلقه بثلاث طبقات، كل واحدة تجيب على سؤال مختلف: TLS يجيب «هل يقرأ أحد الرسائل في الطريق، وهل هذا هو الوسيط الحقيقي؟»، وكلمة المرور تجيب «من أنت؟»، والصلاحيات ACL تجيب «ماذا يحق لك؟». وسوف نهاجم هذا الوسيط نفسه في مقال أمن إنترنت الأشياء من السلسلة، أما هنا فنبني الإعداد ونفهمه.
شهادة الوسيط Certificate من سلطة خاصة CA
الأجهزة داخل شركتك لا تحتاج شهادة من سلطة عامة، لأنها لا تتصل باسم نطاق على الإنترنت، والأسهل والأكثر تحكماً أن تنشئ سلطة شهادات خاصة CA وتضع شهادتها في كل جهاز. وقد شرحنا الشهادات وصيغها في مقال الشهادات الرقمية، والسكربت التالي ينشئ السلطة ثم شهادة الوسيط:
#!/bin/sh
# Own CA for the lab, then a server certificate for the broker name iot-mq (CN and SAN must match what clients connect to).
set -e
cd /w/certs
openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:P-256 -nodes -days 3650 \
-keyout ca.key -out ca.crt -subj "/CN=coldstore lab CA"
openssl req -newkey ec -pkeyopt ec_paramgen_curve:P-256 -nodes \
-keyout server.key -out server.csr -subj "/CN=iot-mq"
printf "subjectAltName=DNS:iot-mq,DNS:localhost\nextendedKeyUsage=serverAuth\n" > server.ext
openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -days 825 -out server.crt -extfile server.ext
chmod 644 server.key ca.crt server.crt
openssl x509 -in server.crt -noout -subject -issuer -ext subjectAltName -datessubject=CN=iot-mq
issuer=CN=coldstore lab CA
X509v3 Subject Alternative Name:
DNS:iot-mq, DNS:localhost
notBefore=Nov 6 00:09:55 2026 GMT
notAfter=Feb 8 00:09:55 2029 GMTشغلناه في Container من python:3.13.18-slim لأن فيه OpenSSL 3.5.7. ولاحظ أن الاسم في الحقل subjectAltName هو iot-mq، وهو الاسم الذي سوف تتصل به الأجهزة، فالكلاينت يقارن الاسم الذي طلبه بالاسم في الشهادة، وإذا اختلفا رفض الاتصال حتى لو كانت الشهادة موقعة من سلطتك. ومفتاح السلطة ca.key هو أهم ملف في النظام كله، فمن يملكه يستطيع أن يصنع وسيطاً مزيفاً تثق به كل الأجهزة، ولذلك مكانه خارج السيرفر وخارج المستودع.
كلمات المرور Passwords، ثم الصلاحيات ACL
لكل جهاز وخدمة اسم وكلمة مرور خاصة، والأداة mosquitto_passwd تحفظها كهاش في ملف:
for u in room1-temp:Room1-Lab-Pass gw-store1:Gw-Lab-Pass ingest-1:Ingest-Lab-Pass dashboard:Dash-Lab-Pass; do
mosquitto_passwd -b /w/passwd ${u%%:*} ${u#*:}
doneroom1-temp:$7$1000$F4a1ybSXPasSJ3oQ84LCecVuEErfDa2UfxoS+lgD+ebEidbdmo1RedEFzxXpV...
gw-store1:$7$1000$Rdz/77XjbK2RjfgBinKZNk8iowoCl+mX9wSg/cAcRx1MKjBXpi1Wsl5imNR9Mt...وهنا ملاحظة وجدناها في المختبر: تقول صفحة الأداة ورسالة المساعدة فيها إن الخوارزمية الافتراضية argon2id، ولكن كل سطر في الملف بدأ بـ $7$1000$، وهي صيغة sha512-pbkdf2 بألف تكرار، ولما طلبنا argon2id صراحة بالخيار -H argon2id ردت الأداة في هذا الـ Image بالخطأ Error: Unable to hash password.. أي أن الـ Image المبني على Alpine يعمل بـ PBKDF2، وهي خوارزمية مقبولة، ولكن إذا كانت سياستك تشترط argon2id فتحقق من الملف نفسه ولا تعتمد على ما تقوله صفحة المساعدة.
ثم ملف الصلاحيات acl، وفيه تعطي لكل مستخدم ما يحتاجه فقط:
# Anyone authenticated: nothing unless granted below. Read top to bottom, user blocks then patterns.
# Each device writes only its own topics and reads only its own commands (%u = its username).
pattern write coldstore/store1/%u/telemetry
pattern write coldstore/store1/%u/status
pattern read coldstore/store1/%u/cmd
# The ingest service reads everything of the application, writes nothing.
user ingest-1
topic read coldstore/#
# The dashboard reads, and may send commands to devices.
user dashboard
topic read coldstore/#
topic write coldstore/+/+/cmdوفي الملف أعلاه لاحظ التالي:
- الأسطر
patternتطبق على كل مستخدم، و%uيستبدل باسم المستخدم، فسطر واحد يكفي لكل الأجهزة: كل جهاز يكتب قراءاته وحالته فقط، ويقرأ أوامره فقط. وبهذا الشكل اسم المستخدم هو اسم الجهاز في المواضيع، وهذا تصميم يجعل الصلاحيات تتبع الأسماء تلقائياً. - خدمة الاستقبال تقرأ كل شيء ولا تكتب شيئاً، فإذا سرقت كلمة مرورها لا يستطيع المخترق أن يرسل أمراً.
- اللوحة وحدها تكتب الأوامر، وهي المكان الذي يجب أن يكون فيه دخول المستخدمين وسجل من أرسل ماذا.
- ما لم يذكر في الملف ممنوع، فلا يوجد سطر «امنع»، وإنما كل شيء ممنوع إلا ما أعطيته.
إعداد الوسيط الآمن Secure Config
# Step 2: every client logs in, every topic is checked, and traffic outside the lab network is encrypted.
persistence true
persistence_location /mosquitto/data/
log_dest stdout
log_type error
log_type warning
log_type notice
log_type information
connection_messages true
# plain listener kept only for clients on the same host network namespace (health checks); no anonymous login
listener 1883
listener_allow_anonymous false
# TLS listener for devices and services
listener 8883
listener_allow_anonymous false
certfile /mosquitto/config/certs/server.crt
keyfile /mosquitto/config/certs/server.key
cafile /mosquitto/config/certs/ca.crt
tls_version tlsv1.2
# Mosquitto 2.1: password and ACL checks as plugins (the old password_file / acl_file options are deprecated)
global_plugin /usr/lib/mosquitto_password_file.so
plugin_opt_password_file /mosquitto/config/passwd
global_plugin /usr/lib/mosquitto_acl_file.so
plugin_opt_acl_file /mosquitto/config/aclولاحظ أن tls_version tlsv1.2 في Mosquitto 2 يعني الحد الأدنى وليس الإصدار الوحيد، كما تقول صفحة الإعداد، ولهذا سوف ترى في السجل أن الاتصالات اتفقت على TLS 1.3. وأن الإضافتين بـ global_plugin تطبقان على كل المنافذ، فلا يوجد منفذ يتجاوز كلمات المرور أو الصلاحيات.
مشكلتان واجهتانا: صلاحيات الملفات File Permissions ومجلد الشهادات
في المحاولة الأولى ربطنا مجلد المختبر بالـ Container مباشرة، فعمل الوسيط ولكن ملأ السجل بتحذيرات لكل ملف سري:
Warning: File /mosquitto/config/passwd has world readable permissions. Future versions will refuse to load this file.
To fix this, use `chmod 0700 /mosquitto/config/passwd`.
Warning: File /mosquitto/config/passwd owner is not mosquitto. Future versions will refuse to load this file.To fix this, use `chown mosquitto /mosquitto/config/passwd`.والسبب أن الملفات المربوطة من Windows عبر Docker Desktop، أو من مجلد مشترك، تظهر داخل الـ Container مملوكة للمستخدم root ويقرؤها الجميع، ولا ينفع chmod عليها. والتحذير يقول بوضوح إن الإصدارات القادمة سوف ترفض تحميل الملف، أي أن الوسيط الذي يعمل اليوم قد لا يعمل بعد ترقية. والحل الأنظف أن نبني Image صغيراً ينسخ الملفات بالمالك والصلاحية الصحيحة، فكتبنا Dockerfile بالخيار COPY --chmod=0600، فاختفت التحذيرات، ولكن الوسيط توقف فوراً بخطأ جديد:
Error: Unable to load CA certificates. Check cafile "/mosquitto/config/certs/ca.crt".
OpenSSL Error [0]: error:8000000D:system library::Permission denied
mosquitto version 2.1.2 terminatingوالملف ca.crt نفسه كانت صلاحيته 644 ويقرؤه الجميع، فلماذا «Permission denied»؟ وعند فحص المجلد وجدنا السبب:
drw------- 1 mosquitto mosquitto 4096 Nov 6 00:10 certsفالخيار --chmod في COPY يطبق الصلاحية على المجلد الذي ينشئه أيضاً، والمجلد بصلاحية 0600 ليس فيه حرف x، فلا يستطيع أحد أن يدخله ليقرأ أي ملف فيه مهما كانت صلاحية الملف نفسه. والحل أن ننشئ المجلد أولاً بصلاحية صحيحة، ثم ننسخ إليه:
# The secure broker: secrets copied in with the owner and mode Mosquitto 2.1 expects
# (a bind mount from Windows or a shared folder shows them world readable and owned by root).
FROM eclipse-mosquitto:2.1.2-alpine
# create the folder first: COPY --chmod applies the mode to folders it creates too, and 0600 without x cannot be entered
RUN install -d -o mosquitto -g mosquitto -m 0750 /mosquitto/config/certs
COPY --chown=mosquitto:mosquitto --chmod=0600 passwd acl /mosquitto/config/
COPY --chown=mosquitto:mosquitto --chmod=0600 certs/server.key /mosquitto/config/certs/
COPY --chmod=0644 certs/server.crt certs/ca.crt /mosquitto/config/certs/
COPY --chmod=0644 mosquitto-secure.conf /mosquitto/config/mosquitto.confdocker build -t iot-mq-secure:1 .
docker run -d --name iot-mq --network iot-mq-net -v iot-mq-data:/mosquitto/data iot-mq-secure:11793923989: Opening ipv4 listen socket on port 8883.
1793923989: Opening ipv6 listen socket on port 8883.
1793923989: mosquitto version 2.1.2 runningولاحظ أن هذا الـ Image فيه مفتاح الوسيط وملف كلمات المرور، فلا ترفعه إلى أي Registry عام، وفي الإنتاج الأفضل أن تأتي هذه الملفات من مدير أسرار، وقد شرحنا الخيارات في مقال إدارة الأسرار.
اختبار البوابات Security Tests: ماذا يرفض الوسيط ولماذا؟
الآن نجرب الأخطاء الشائعة واحداً واحداً، والكلاينت يأخذ شهادة السلطة ca.crt فقط، فهي عامة ولا سر فيها:
cli() { docker run --rm --network iot-mq-net -v "$PWD/certs/ca.crt:/ca.crt:ro" eclipse-mosquitto:2.1.2-alpine "$@"; }
cli mosquitto_pub -h iot-mq -t coldstore/store1/room1-temp/telemetry -m x # 1 anonymous
cli mosquitto_pub -h iot-mq -u room1-temp -P wrong -t coldstore/store1/room1-temp/telemetry -m x # 2 wrong password
cli mosquitto_pub -d -h iot-mq -p 8883 -u room1-temp -P Room1-Lab-Pass -t t -m x # 3 TLS, no CA
cli mosquitto_pub -d -h 172.18.0.2 -p 8883 --cafile /ca.crt -u room1-temp -P Room1-Lab-Pass -t t -m x # 4 TLS by IPConnection error: Connection Refused: not authorised
Error: The connection was refused
Connection error: Connection Refused: not authorised
Error: The connection was refused
Client null sending CONNECT
Error: Protocol error
OpenSSL Error while trying to get the error[0]: error:0A000086:SSL routines::certificate verify failed
Client null sending CONNECT
Error: Protocol error
OpenSSL Error while trying to get the error[0]: error:0A000086:SSL routines::certificate verify failedوسجل الوسيط للمحاولتين الأخيرتين:
1793924050: OpenSSL Error while trying to get the error[0]: error:0A000418:SSL routines::tlsv1 alert unknown ca
1793924052: OpenSSL Error while trying to get the error[0]: error:0A000412:SSL routines::ssl/tls alert bad certificateوفي المخرج أعلاه لاحظ التالي:
- الدخول دون اسم والدخول بكلمة مرور خاطئة أعطيا الرد نفسه
not authorised، وهذا مقصود، حتى لا يعرف المخترق هل الاسم موجود أم لا. - في المحاولة الثالثة لم يعط الكلاينت شهادة السلطة، فلم يثق بشهادة الوسيط، وفي الرابعة أعطاها ولكنه اتصل بعنوان IP بدل الاسم
iot-mqالموجود في الشهادة. والكلاينت يقول في الحالتينProtocol errorفقط، وهي رسالة لا تفيد، ومع-dظهر السبب الحقيقيcertificate verify failed، وفي سجل الوسيط فرق واضح:unknown caللأولى وbad certificateللثانية. فإذا اشتكى أحد من «Protocol error» فأول سؤال: بأي اسم يتصل، ومعه أي شهادة سلطة؟
ثم نجرب الصلاحيات بكلمات مرور صحيحة، أولاً بـ MQTT 5:
cli mosquitto_pub -h iot-mq -p 8883 --cafile /ca.crt -V mqttv5 -d -q 1 -u room1-temp -P Room1-Lab-Pass -t coldstore/store1/room1-temp/telemetry -m '{"seq":1}'
cli mosquitto_pub -h iot-mq -p 8883 --cafile /ca.crt -V mqttv5 -d -q 1 -u room1-temp -P Room1-Lab-Pass -t coldstore/store1/room2-temp/telemetry -m '{"seq":1}'
cli mosquitto_pub -h iot-mq -p 8883 --cafile /ca.crt -V mqttv5 -d -q 1 -u ingest-1 -P Ingest-Lab-Pass -t coldstore/store1/room1-temp/cmd -m 'compressor off'Client auto-2C8D383F-... sending PUBLISH (d0, q1, r0, m1, 'coldstore/store1/room1-temp/telemetry', ... (9 bytes))
Client auto-2C8D383F-... received PUBACK (Mid: 1, RC:16)
Warning: Publish 1 failed: Not authorized.
Client auto-7AD168A5-... sending PUBLISH (d0, q1, r0, m1, 'coldstore/store1/room2-temp/telemetry', ... (9 bytes))
Client auto-7AD168A5-... received PUBACK (Mid: 1, RC:135)
Warning: Publish 1 failed: Not authorized.
Client auto-1EEE3DBD-... sending PUBLISH (d0, q1, r0, m1, 'coldstore/store1/room1-temp/cmd', ... (14 bytes))
Client auto-1EEE3DBD-... received PUBACK (Mid: 1, RC:135)الجهاز نشر على موضوعه فوصله PUBACK برمز 16، وهو في المواصفة «No matching subscribers»، أي أن الرسالة قبلت ولكن لا يوجد مشترك الآن، وهذا نجاح مع معلومة وليس خطأ. ولما حاول أن ينشر على موضوع الغرفة الثانية جاءه الرمز 135 «Not authorized»، وكذلك خدمة الاستقبال لما حاولت أن ترسل أمر «compressor off». وسجل الاتصال في الوسيط يقول الآن مع كل اتصال اسم المستخدم والتشفير:
New client connected from 172.18.0.3:51730 as auto-7AD168A5-... (p5, c1, k60, u'room1-temp').
Client auto-7AD168A5-... negotiated TLSv1.3 cipher TLS_AES_256_GCM_SHA384ثم كررنا محاولة النشر على موضوع الغرفة الثانية نفسها، ولكن بـ MQTT 3.1.1، وهو الإصدار الافتراضي في كثير من المكتبات والأجهزة:
Client null sending PUBLISH (d0, q1, r0, m1, 'coldstore/store1/room2-temp/telemetry', ... (9 bytes))
Client null received PUBACK (Mid: 1, RC:0)الرد RC:0، أي نجاح! والحقيقة أن الوسيط رمى الرسالة، ولكن MQTT 3.1.1 لا يملك طريقة يقول بها «رفضت»، فيرد بالتأكيد العادي. وهذا يعني أن جهازاً بصلاحيات خاطئة بعد تعديل في ملف ACL سوف يرسل قراءاته أياماً وهو يظن أنها تصل، ولا يظهر أي خطأ في سجله، والطريقة الوحيدة لاكتشافه هي غياب القراءات عند المستقبل. وهذا سبب قوي لاستخدام MQTT 5 في الأجهزة الجديدة إذا كانت مكتبتها تدعمه.
وأخيراً جربنا القراءة: اشترك الجهاز room1-temp في كل شيء coldstore/#، ثم أرسلت اللوحة أمرين، واحداً له وواحداً للغرفة الثانية:
Subscribed (mid: 1): 0
== what room1 received with # subscription:
coldstore/store1/room1-temp/cmd period 30قبل الوسيط الاشتراك نفسه، ولكنه يفحص صلاحية القراءة مع كل رسالة، فوصل للجهاز أمره فقط، ولم يصله أمر الغرفة الثانية. والصورة التالية تلخص البوابات الثلاث وما رفضته كل منها:

Mosquitto في الإنتاج Production
- لا تنشر المنفذ 1883 إلى الإنترنت إطلاقاً: الأجهزة خارج الشبكة تتصل على 8883 فقط، والأفضل عبر شبكة خاصة VPN، وقد شرحنا الفكرة في مقال VPN.
- الحفظ والـ Volume:
persistence trueمع Volume دائم، وراجعautosave_intervalبحسب ما تحتمل أن تفقد عند انقطاع الكهرباء المفاجئ. - حدود الطوابير: احسب
max_queued_messagesمن عدد الأجهزة وسرعتها وأطول غياب تتوقعه للمستقبل، وأضفpersistent_client_expiration. - المراقبة: اشترك في مواضيع
$SYSلعدد الكلاينتات والرسائل المحفوظة والمستقبلة، ونبه على النقص المفاجئ في عدد المتصلين. - إدارة المستخدمين: ملف كلمات المرور يكفي لعشرات الأجهزة، ومع العدد الأكبر هناك إضافة
dynamic-securityالتي تدير المستخدمين والأدوار عبر الأداةmosquitto_ctrlدون إعادة تشغيل، أو شهادة لكل جهاز بدل كلمة المرور. - الجسر Bridge: إذا كان لديك عدة مستودعات، فوسيط صغير في كل مستودع يربط بجسر بالوسيط المركزي، فيستمر العمل المحلي والتنبيه المحلي إذا انقطع الإنترنت، وتصل القراءات للمركز عند العودة.
- فحص الإعداد قبل كل تعديل:
mosquitto --test-configقبل إعادة التشغيل، لأن الإصدار 2.1 يجعل الخطأ في ملف كلمات المرور أو الصلاحيات عند إعادة التحميل يوقف الوسيط كله، بحسب سجل التغييرات.
أخطاء شائعة Common Mistakes
- اسم كلاينت واحد لعدة أجهزة: رأينا الطرد المتبادل 9 مرات في 8 ثوان.
- اسم كلاينت عشوائي مع جلسة دائمة: كل اتصال ينشئ جلسة جديدة تبقى في ذاكرة الوسيط ولا يعود إليها أحد.
- الاعتماد على QoS الناشر وحده: المشترك بـ QoS 0 يستقبل كل شيء بـ QoS 0.
- حفظ القراءات أو الأوامر كرسائل محفوظة دون صلاحية: القراءة القديمة تظهر كأنها الآن، والأمر القديم ينفذ عند كل إعادة تشغيل.
- الوثوق بالوصية في الإغلاق الطبيعي: DISCONNECT العادي لا يطلقها، فانشر
offlineبنفسك. - keepalive طويلة لجهاز مهم: بالقيمة 60 قد تمر دقيقة ونصف قبل أن يعرف أحد.
- persistence دون Volume: الإعداد صحيح والنتيجة كأنه غير موجود.
- الاكتفاء بـ MQTT 3.1.1 مع ACL: الرفض صامت، والجهاز يظن أن رسائله تصل.
- التشخيص من «Protocol error»: استخدم
-dواقرأ سجل الوسيط لترى السبب الحقيقي.
قائمة تحقق Checklist قبل أن تربط أول جهاز
| البند | القيمة المناسبة |
|---|---|
| اسم الكلاينت | فريد لكل جهاز، من رقم تسلسلي أو عنوان MAC |
| الجلسة | نظيفة للأجهزة التي ترسل فقط، ودائمة للخدمات التي تستقبل |
| QoS | 0 للقراءات المتكررة، و1 للسجل والحالة، و2 للأوامر الحرجة فقط |
| keepalive | بالثواني التي تحتمل أن يغيب فيها الجهاز دون أن تعرف، مقسومة على 1.5 |
| الحالة | online محفوظة عند الاتصال، ووصية offline محفوظة |
| الحفظ | persistence true مع Volume، وautosave_interval مناسب |
| الطوابير | max_queued_messages محسوب، وpersistent_client_expiration |
| المنافذ | 8883 مع TLS فقط خارج السيرفر، ولا دخول دون اسم |
| الصلاحيات | كل جهاز على مواضيعه، والأوامر من اللوحة وحدها |
| إصدار البروتوكول | MQTT 5 إذا كانت المكتبة تدعمه، لرموز السبب |
تدريب عملي Practice
- غير keepalive في تجربة الوصية إلى 4 ثوان ثم 30 ثانية، وقس الوقت بين
docker pauseووصولofflineفي كل مرة. - أضف إلى ملف الصلاحيات مستخدماً للبوابة
gw-store1يكتب قراءات كل الأجهزة التي خلفها فقط، ثم جرب أن ينشر باسم جهاز ليس خلفه. - اجعل
max_queued_messages 5، ثم انشر 10 رسائل QoS 1 لجلسةingest-1الغائبة، وانظر كم وصل منها، وما الذي يكتبه الوسيط في سجله.
حذف المختبر Cleanup
docker rm -f iot-mq iot-mq-sub iot-mq-watch
docker network rm iot-mq-net
docker volume rm iot-mq-data
docker image rm iot-mq-secure:1ويبقى Image الوسيط eclipse-mosquitto:2.1.2-alpine لأننا سوف نستخدمه في بقية السلسلة، أما مجلد certs ففيه مفتاح السلطة، فاحذفه أو انقله إلى مكان آمن إذا كنت سوف تستخدم هذه السلطة لأجهزة حقيقية.
الخلاصة Summary
- رسالة CONNECT تحدد سلوك الكلاينت كله: اسمه وجلسته وkeepalive ووصيته، والوسيط يكتبها في سجله بالشكل
(p5, c1, k60, u'...'). - QoS وعد بين طرفين، والوسيط يسلم بالأقل بين مستوى النشر ومستوى الاشتراك.
- الرسالة المحفوظة مع الوصية تعطيان حالة كل جهاز دون سؤاله، والوصية تأتي بعد keepalive عند الانقطاع، وفوراً عند موت البرنامج، ولا تأتي عند الإغلاق الطبيعي.
- الجلسة الدائمة تحمي من غياب المشترك لرسائل QoS 1 و2، والحفظ على Volume يحميها من إعادة تشغيل الوسيط، ودون الحفظ ضاعت القراءات الثلاث والحالة المحفوظة.
- الأمان ثلاث بوابات: TLS بسلطة خاصة، ثم كلمة مرور لكل جهاز، ثم صلاحيات على المواضيع، وفي MQTT 3.1.1 يكون رفض الصلاحيات صامتاً.
دليلHome Assistant مع ESPHome: أتمتة المستودع على سيرفركنترجم برنامجاً حقيقياً للوحة ESP32، ونشغل الجهاز نفسه على السيرفر مع Home Assistant، ونكتب أتمتة تشغل الضاغط الاحتياطي، ثم نفصل الجهاز لنرى ما يحدث.
دليلالشهادات الرقمية TLS للمبتدئين وصيغ ملفاتهاكيف يعرف المتصفح أنه يتحدث مع الموقع الحقيقي، وماذا يوجد داخل الشهادة، ولماذا تأتي ملفاتها بأكثر من صيغة.
دليلمقاييس السيرفرات Metrics: Prometheus مع لوحات Grafanaنجمع مقاييس المعالج والذاكرة والقرص والـ Containers مع Prometheus، ونتنبأ بموعد امتلاء القرص قبل أن يحدث، ونبني لوحة Grafana محفوظة ككود في Git.
دليلتقسيم الشبكة Network Segmentation بال VLAN وال VPCلماذا تصل كاميرا مخترقة إلى قاعدة بياناتك، وكيف تمنع ذلك بتقسيم الشبكة إلى مناطق لا يمر بينها إلا ما تسمح به.وفي المقال القادم من السلسلة بإذن الله سوف نضع فوق هذا الوسيط Home Assistant وأجهزة ESPHome، ونكتب أول أتمتة.
سجل التحديثات Changelog
- نوفمبر 2026: كتابة المقال، والتجربة على Mosquitto 2.1.2 (eclipse-mosquitto:2.1.2-alpine) مع أدوات mosquitto_pub وmosquitto_sub من الـ Image نفسه، وشهادات من OpenSSL 3.5.7 في python:3.13.18-slim، على Docker Engine 29.8.0، والمعلومات من توثيق Mosquitto وسجل تغييراته ومواصفة MQTT 5.0 كما قرأناها في 6 نوفمبر 2026.