Netfence

مثل Envoy xDS، ولكن لمرشحات eBPF.

يعمل Netfence كخفي على مضيفي الأجهزة الافتراضية/الحاويات الخاص بك ويقوم تلقائياً بحقن برامج مرشحات eBPF في مجموعات cgroups وواجهات الشبكة، مع خادم DNS مدمج يقوم بحل النطاقات المسموح بها ويملأ قائمة عناوين IP المسموح بها.

يمكن تشغيل خفي Netfence من خلال واجهة برمجة التطبيقات المحلية لمقبس Unix وحدها، أو الاتصال بمستوى تحكم مركزي تقوم بتنفيذه عبر gRPC لمزامنة قوائم السماح/المنع مع الواجهة الخلفية الخاصة بك.

يدفع مستوى التحكم الخاص بك قواعد الشبكة مثل ALLOW *.pypi.org أو ALLOW 10.0.0.0/16 إلى الواجهات/مجموعات cgroups المرفقة. عندما يستعلم جهاز افتراضي/حاوية عن DNS، يقوم Netfence بحله، ويضيف عناوين IP إلى مرشح eBPF، ويسقط حركة المرور إلى عناوين IP غير معروفة قبل أن تغادر المضيف مع حمل المسار الدافئ الذي لا يمكن تمييزه فعلياً عن اتصال مأخذ عادي في المقاييس الحالية.

الميزات

• إرفاق مرشحات eBPF بواجهات الشبكة (TC) أو مجموعات cgroups
• أوضاع السياسة: معطل، قائمة السماح، قائمة المنع، منع الكل
• دعم CIDR للإصدارين IPv4 و IPv6 مع TTLs اختيارية
• خادم DNS لكل مرفق UDP/TCP مع قائمة سماح/منع للنطاقات وتجاوزات تصاعدية مرتبة
• تدعم قواعد النطاق النطاقات الفرعية مع مطابقة تعتمد على الخصوصية (القواعد الأكثر تحديداً تفوز)
• النطاقات التي تم حلها تملأ مرشح IP تلقائياً
• بيانات وصفية على الخفايا والمرفقات للربط مع معرف الجهاز الافتراضي، المستأجر، إلخ.
• دعم لتوجيه استعلامات DNS إلى مستوى التحكم لاتخاذ قرارات DNS لكل مرفق

ملاحظة أمنية: الاستثناءات الافتراضية

في وضع قائمة السماح، لم يعد IPv4 المحلي للرابط (169.254.0.0/16) مسموحاً به تلقائياً بشكل افتراضي — لذا يتم حظر خدمة البيانات الوصفية السحابية (169.254.169.254) ما لم يتم السماح بها صراحة. هذا متعمد: خدمة البيانات الوصفية هي هدف لسرقة بيانات الاعتماد، ويجب ألا تتمكن أعباء العمل المحصورة من الوصول إليها ضمنياً. يظل المضيف المحلي (127.0.0.0/8, ::1) واكتشاف الجيران IPv6 (fe80::/10, ff02::/16) مسموحين بهم افتراضياً حتى تستمر الاتصالية الأساسية و NDP في العمل. للسماح بخدمة البيانات الوصفية لعبء عمل، قم بالسماح 169.254.169.254/32 (تجاوز استثناء لكل مرفق عبر مستوى التحكم هو متابعة مخطط لها).

البث IPv4 (255.255.255.255) والبث المتعدد (224.0.0.0/4) ليس لهما استثناء ويخضعان للسياسة، لذا في وضع قائمة السماح TC يتم حظر حركة المرور مثل بث تجديد DHCP ما لم يتم السماح بها صراحة. يتم إجراء فحوصات الاستثناء قبل قائمة المنع، لذا لا يمكن حظر نطاق مستثنى إلا بإيقاف تشغيل استثنائه — ولأن IPv4 المحلي للرابط الآن متوقف افتراضياً، يمكن لوضع قائمة المنع حظر خدمة البيانات الوصفية أيضاً.

الاختلافات عن الخيارات الأخرى

بعض الفوائد الرئيسية لهذا الحل التي لا تدعمها الخيارات الأخرى عادةً:

• قطع فوري للاتصالات الحالية عندما تتغير القواعد لمنع عنوان IP (إرفاق الواجهة فقط)
• دعم جميع بروتوكولات الشبكة، والتوجيه المباشر للشبكات بعناوين IP. على سبيل المثال، httpjail الرائع لا يسمح لك بالاتصال المباشر بعناوين IP، أو اتصالات TCP/UDP المباشرة مثل الاتصال بقواعد البيانات.
• الحل الديناميكي لـ DNS والترشيح قبل الحل (بحيث لا يكون هناك تسريب لـ secretdata.someattacker.com)

على حد علمي، لا تقدم أي حلول أخرى كل هذه الميزات معاً.

قيد معروف: تقوم مرفقات cgroup بالتصفية على طبقة المقبس (خطافات connect/sendmsg)، لذا يمكن لعملية لديها CAP_NET_RAW إنشاء حزم خام تتجاوزها. استخدم مرفق TC (الواجهة)، الذي يقوم بالتصفية على طبقة الجهاز، لأعباء العمل التي قد تحمل CAP_NET_RAW.

ومع ذلك، فإن هذا له حمل زائد أكبر قليلاً من شيء مثل httpjail.

لمحة عن الأداء

تم قياس هذه الأرقام في بوابة Docker Linux المميزة على linux/arm64 باستخدام make bench-docker. القيم هي متوسطات خمس عينات.

مسار المقبس الدافئ

يستخدم معيار المقبس الدافئ مقابس UDP متصلة لعزل تكلفة خطاف eBPF cgroup/connect4 عن زمن مصافحة TCP. في هذا المسار، قام DNS بالفعل بحل النطاق، ولا يزال عنوان IP ضمن TTL، وعنوان IP/CIDR موجود بالفعل في خريطة eBPF.

الفرق المقاس بين مسارات الاتصال العادي، LPM المحمي، ومضيف DNS الدقيق يقع ضمن ضوضاء العينة.

لا يوجد مسار "فقدان kernel يسأل العملية الأم" اليوم. يتم تحديد فقدان قائمة السماح cgroup محلياً بواسطة eBPF ويتم حظره فوراً.

مسار استعلام DNS

تقيس هذه الأرقام مسار خادم DNS، وليس مسار اتصال المقبس الدافئ.

تتزامن الصفوف الباردة عبر حاجز تحوير المرفق الحقيقي وتمسح رسم بياني لملكية المعيار ولقطة خريطة دقيقة وهمية بين الاستعلامات. يعمل المؤقت بشكل مستمر للحفاظ على موقع جدولة UDP، بينما يطرح ns/op وقت الجدار fixture-reset-ns/op المُبلغ عنه بشكل منفصل (بما في ذلك أي ذيل من المعالج السابق بعد أن استلم العميل حزمة) وبالتالي يقيس تبادل العميل الحالي. يُبلغ raw-total-ns/op عن كليهما معاً. يحافظ إعادة التعيين على نطاقات السياسة المكونة والتخزين الداعم، ويؤكد المعيار إضافة خريطة دقيقة مادية واحدة لكل استعلام. تقوم الصفوف الدافئة بتهيئة الملكية مرة واحدة وتؤكد إضافة مادية واحدة عبر التشغيل.

المعايير الدقيقة للملكية الداخلية أدناه هي تشخيصات قابلية التوسع، وليست صفوف قبول مسار استعلام DNS من النهاية إلى النهاية. يتم الاحتفاظ بالمساعد المخبأ فقط للاختبارات والمعايير؛ فهو يلف سجلاً واحداً في كل مرة ويكرر التحقق من النطاق. كلاهما وحركة مرور المحلل العادي يعبران حاجز تحوير المرفق، بينما تعترف حركة مرور المحلل العادي بكل استجابة كاملة كصفقة واحدة.

التصميم

الهندسة المعمارية```

+------------------+ +-------------------------+ | Your Control |<------->| Daemon (per host) | | Plane (gRPC) | stream | | +------------------+ | +-------------------+ | | | DNS Server | | | | (per-attachment) | | | +-------------------+ | +-------------------------+ | +------+------+ | | TC Filter Cgroup Filter (veth, eth) (containers)

يحصل كل مرفق على عنوان DNS فريد (منفذ) يوفره الخفي. يجب تكوين الحاويات/الآلات الافتراضية لاستخدام عنوان DNS المخصص لها؛ ولا يؤدي تصفية حركة مرور DNS العادية للعمل إلى إعادة توجيهها بشكل شفاف.

### طوبولوجيا وسلوك محلل DNS

`dns.listen_addr` يجب أن يحدد عنوان IPv4 أو IPv6 ماديًا واحدًا يمكن لكل عمل ملحق الوصول إليه. يتم رفض العناوين البدل لأنها لا يمكن الإعلان عنها كنقاط نهاية محلل. يتم حل اسم المضيف المُكوّن مرة واحدة عند بدء تشغيل الخفي ويتم استخدام عنوان IP المادي الناتج للربط والإعلان والثبات وتشغيل الفلتر. القيمة الافتراضية `127.0.0.1` مناسبة فقط عندما يشارك العمل نفس مساحة اسم الشبكة الخاصة بالخفي؛ الحاوية أو الآلة الافتراضية في مساحة اسم أخرى تحتاج عادةً إلى عنوان مضيف/جسر يمكن الوصول إليه بدلاً من ذلك.```yaml
dns:
  listen_addr: 10.0.0.1
  port_min: 11000
  port_max: 11500
  # Daemon-global fallback when DnsConfig.upstream_servers is empty.
  upstream: 1.1.1.1:53
  # Hard daemon ceilings for each attachment's bounded DNS exact ownership.
  # Zero/unset uses these defaults (max_ips_per_family instead derives from
  # filter.max_dns_rule_entries).
  max_ips_per_family: 4096
  max_ips_per_response: 64
  max_ips_per_policy_domain: 1024
  max_tracked_domains: 1024
  max_ownership_edges: 8192
  # Rolling physical-admission/LRU mutation budget and slow-planning work
  # allowance. The window is daemon-global and immutable until restart;
  # DnsConfig.max_churn_units may only lower the daemon ceiling.
  max_churn_units: 8192
  churn_window: 1m

يُرجع Attach عنوان dns_address المحدد؛ قم بتكوين هذا العنوان بالضبط كمُحلِّل (resolver) لعبء العمل. يُثبِّت Netfence إدخال سماح محمي غير منتهي الصلاحية من نوع /32 أو /128 لعنوان IP الخاص بالمستمع، بحيث يمكن لوضع القائمة البيضاء (allowlist) الإقلاع بدون قاعدة تحكم في مستوى التحكم (control-plane) لـ DNS-IP. تُطبِّق المرشحات الحالية بادئات IP، وليس منافذ الوجهة، لذا فإن هذا الإدخال المحمي يسمح بكل منفذ على عنوان IP الخاص بالمستمع (وليس فقط منفذ DNS الخاص به)؛ وهذا مهم بشكل خاص لنماذج التهديد المرتبطة بـ cgroup. استخدم عنوان IP مخصص للمستمع عندما لا تكون قابلية الوصول الأوسع هذه مقبولة.

يخدم نقطة النهاية المُعيَّنة كلاً من UDP و TCP. يتم اقتطاع ردود UDP إلى حد 512 بايت الخاص بالعميل القديم أو إلى حجم EDNS المُعلن عنه وتحمل علامة TC عند الحاجة، مما يسمح لعبء العمل بإعادة المحاولة على نفس نقطة النهاية عبر TCP. بالنسبة للحل التصاعدي (upstream resolution)، يتم إعادة محاولة إجابة UDP المقتطعة عبر TCP ضد نفس المُحلِّل التصاعدي أولاً. يؤدي فشل النقل، أو SERVFAIL، أو REFUSED إلى التقدم إلى المُحلِّل التصاعدي التالي المُكوَّن بالترتيب.

يتجاوز DnsConfig.upstream_servers الإعداد العام للبرنامج الخفي dns.upstream لارتباط واحد. تستخدم الإدخالات صيغة host:port (مع أقواس لعناوين IPv6 الحرفية)، ويتم توحيدها وإزالة التكرار بترتيب الظهور الأول، وتقتصر على ثمانية خوادم فريدة. تحدد القائمة الفارغة الاحتياطي العام.

في أوضاع التصفية، يزيل Netfence معلمات ipv4hint و ipv6hint من إجابات HTTPS/SVCB، بما في ذلك مراجع mandatory المقابلة لها، لأن العناوين المُلمَّح إليها لم تمر بشكل مستقل من خلال قبول المرشح. يحافظ الوضع المُعطَّل (Disabled mode) على إجابات المُحلِّل التصاعدي دون تغيير.

عدادات استعلامات DNS حصرية متبادلة: dns_queries_allowed يحسب الاستعلامات المسموح بها من خلال السياسة والتي تمت الإجابة عليها بنجاح (بما في ذلك NXDOMAIN)، dns_queries_blocked يحسب استجابات السياسة REFUSED، و dns_queries_errors يحسب مسارات الخطأ في المُحلِّل والوكيل وقبول المرشح وكتابة الرد وغيرها. يزيد كل استعلام في سلة واحدة بالضبط.

يتم قبول كل استجابة تحمل عنوانًا في وضع تصفية DNS في طبقة HASH الدقيقة (IPv4/IPv6) الخاصة بالارتباط كمعاملة واحدة قبل إرجاع أي عنوان من أقسام الإجابة (answer) أو السلطة (authority) أو الإضافية (additional) من نوع A/AAAA. إذا تعذر تمثيل الاستجابة الكاملة، يُرجع المُحلِّل SERVFAIL بدون عنوان ويحافظ على مجموعة العمل المُقبولة سابقًا. يجب أن تضبط قرارات PROXY التي تُرجع عناوين add_to_filter؛ وإلا فإنها تفشل أيضًا كـ SERVFAIL. وضع DNS المُعطَّل هو الاستثناء الصريح للمرور المباشر.

تحمل الإدخالات الدقيقة حواف TTL من الاستعلام المُوحَّد إلى مالك السياسة المُطابِق. إزالة نطاق أو حظره فورًا يزيل آخر عناوين DNS الدقيقة الخاصة به، بينما يبقى العنوان المشترك على قيد الحياة من مالك استعلام حي آخر، وتستمر CIDR متداخلة من مستوى التحكم بشكل مستقل في طبقة LPM المحمية. يتم تتبع إجابات السماح الافتراضي والسماح الصريح في قائمة حظر DNS أيضًا، حتى بينما تتجاهل قائمة حظر الحزم السماحات الدقيقة، بحيث يمكن لتبديل لاحق إلى وضع قائمة البيضاء (ALLOWLIST) استخدام العناوين المُخزَّنة مؤقتًا التي تم إرجاعها بالفعل دون إعادة استعلام.

كل حالة ملكية userspace العادية/الحية مقيدة بإعدادات الملكية الخمسة أعلاه. حواف الملكية المؤقتة الاصطناعية المستعادة (restored synthetic provisional edges) معفاة من تلك الحدود المنطقية بحيث لا يمكن نسيانها قبل المصالحة (reconciliation)، لكنها تظل مقيدة بالخرائط الدقيقة الفعلية IPv4/IPv6. نطاقات السياسة المُكوَّنة ونطاقات الاستعلام الحية تتشارك max_tracked_domains، وكل سجل TTL (استعلام، مالك مطابق، IP) يستهلك خانة max_ownership_edges واحدة.

عند الضغط، يقوم القبول (admission) أولاً بإزالة حواف TTL المنتهية. ثم يستعيد حواف الاستعلام/المالك المنطقية الكاملة بأقل ضمانات فيزيائية collateral قبل الأحدثية، يليها LRU المُحدَّد من المُحلِّل (تكسر الروابط بعنوان IP الأساسي). يؤدي الإزالة الفيزيائية إلى إزالة مفتاح DNS الدقيق بأكمله وجميع مالكي DNS الخاصين به. يتم حماية عنوان IP الفيزيائي الوارد والحافة الدقيقة الواردة (IP، استعلام، مالك) طوال معاملة الاستجابة. تحمي الملكية المؤقتة المستعادة مفتاحها الفيزيائي حتى المصالحة الموثوقة، لكن بيانات DNS العادية غير المرتبطة التي تشارك هذا المفتاح قد تظل قابلة للاسترداد. تبقى السماحات الموثوقة من مستوى التحكم/النظام وكل حظر في طبقات LPM منفصلة ولا تكون أبدًا مرشحة لاستصلاح DNS.

تفرض ميزانية التغيير (churn budget) المتجددة لكل ارتباط وحدة واحدة لمفتاح دقيق فيزيائي جديد وواحدة لكل مفتاح DNS فيزيائي حي يتم إخلاؤه؛ وبالتالي فإن الاستبدال الكامل من القديم إلى الجديد يكلف وحدتين. التحديثات، والاستصلاح المنطقي فقط، والانتهاء، والإزالة حسب السياسة لا تكلف شيئًا. تبقى الأحداث نشطة بينما عمرها أقل من dns.churn_window وتنتهي عند الحدود الدقيقة. يمكن لـ DnsConfig.max_churn_units فقط خفض سقف البرنامج الخفي؛ الصفر يرثه. لا يمكن تغيير النافذة بواسطة مستوى التحكم، وتغيير سقف/نافذة البرنامج الخفي يتطلب إعادة تشغيل. خفض حد الارتباط ثم رفعه لاحقًا لا ينسى التاريخ الذي لا يزال نشطًا.

يسجل دفتر عمل متجدد منفصل التخطيط المكلف للرسم البياني للملكية. التحديثات السريعة والقبول العادي لا تلمسه أبدًا. قبل أن يقوم مسار الضغط باستنساخ الرسم البياني أو تحليله، يفرض Netfence وحدات عمل مستقرة مشتقة من المفاتيح الفيزيائية الحالية وحواف الملكية والنطاقات المُتتبعة وحجم الاستجابة بالنسبة لسقوف البرنامج الخفي/الخريطة الثابتة. يتم الاحتفاظ برسوم المحاولة هذه حتى عندما يثبت أن الخطة مستحيلة أو تفشل معاملة الخريطة الدقيقة لاحقًا، مما يغلق مسار إعادة المحاولة بدون طفرات (zero-mutation retry path) لضغط وحدة المعالجة المركزية/التخصيص دون تغيير محاسبة التغيير الفيزيائي للمعاملات أعلاه. عند السقوف الافتراضية، يسمح البدل بثمانية مرات مرور مكافئة للرسم البياني الأقصى لكل نافذة؛ خفض DnsConfig.max_churn_units يحتفظ بواحدة على الأقل. خفض الحد ثم رفعه لاحقًا لا يعيد تحجيم أو نسيان تاريخ العمل النشط.

عندما لا يمكن لحالة DNS المؤهلة تلبية حد، أو استنفد أي من البدلين المتجددين، يحافظ Netfence على مجموعة العمل المُقبولة ويُرجِع SERVFAIL دون إرجاع العنوان غير المُقبَل. تزيد إخفاقات السعة map_full_drops؛ لا تفعل ذلك دواسات التغيير الفيزيائي وتقييد تخطيط العمل. تكشف ضربات القلب (heartbeats) القيم الحالية للخريطة الدقيقة والسعة وأعلى قيم عملية الجيل بالإضافة إلى إخلاءات LRU التراكمية لـ DNS وجميع إخفاقات القبول وعدد إجمالي لميزانية الاختناق يغطي كلا الحارسين المتجددين. سجلات ضغط/استرداد السعة والميزانية الفيزيائية وميزانية العمل محدودة المعدل بشكل مستقل. يمكن للمشغلين انتظار استرداد TTL/النافذة، أو تقليل تغيير الاستجابة/النطاق أو محاولات ضغط السعة المتكررة، أو رفع DnsConfig.max_churn_units حتى سقف البرنامج الخفي dns.max_churn_units. رفع سقف البرنامج الخفي يتطلب إعادة تشغيل؛ زيادة filter.max_dns_rule_entries تتطلب أيضًا إعادة إنشاء الارتباط لأنه لا يمكن تغيير حجم الخرائط المثبتة (pinned maps) في مكانها.

سعة CIDR المحمية واسترداد فشل الإغلاق (fail-closed recovery)

تستخدم CIDRs الموثوقة من مستوى التحكم وقواعد نظام البرنامج الخفي أربع خرائط LPM مستقلة غير قابلة للإخلاء: سماح/حظر × IPv4/IPv6. كل خريطة بها filter.max_rule_entries خانة. إقلاع /32 أو /128 لمستمع DNS هو سماح نظام ويُحتسب ضمن خريطة السماح المحمية المقابلة. تبقى إدخالات المضيف الدقيقة لـ DNS في خرائطها المنفصلة ولا يمكنها استهلاك هذه الخانات. لا يتم إخلاء أي قاعدة محمية بواسطة LRU أبدًا: السماحات الصريحة وقواعد النظام وكل حظر تبقى حتى إزالة مصرح بها أو استبدال كامل.

يتم توحيد SubscribedAck أو BulkUpdate الكامل ويتم التحقق من إشغالها النهائي لجميع الخرائط الأربع قبل التغيير. تعتمد السعة على الحالة النهائية، لذا فإن استبدال المفاتيح في خريطة ممتلئة صحيح؛ يتم رفض الحالة كبيرة الحجم دون إخلاء أو قبول جزئي للقواعد. لا يتم إزالة الناجين وإعادة إضافتهم. إذا فشلت استدعاء نظام خريطة لاحق، يستعيد Netfence المخزون الدقيق للخرائط الأربع قبل الاستدعاء ويتحقق منه. الوضع المُثبت بعد التراجع هو الوضع القديم أو BLOCK_ALL (عادة BLOCK_ALL)، لذلك لا يزال البرنامج الخفي يحمل الارتباط مغلقًا عند الفشل حتى تنجح إعادة محاولة موثوقة كاملة.

يتم الاحتفاظ بحالة سلامة السياسة المحمية مع الارتباط وتصديرها في ضربات القلب. BLOCK_ALL بحد ذاته هو وضع مُكوَّن طبيعي وصحي: policy_degraded خاطئ عندما يكون policy_degraded_reason فارغًا. طفرة محمية خطرة تبدأ بينما BLOCK_ALL صحي تقوم أولاً بتدوين protected_policy_mutation_in_progress. هذا سجل انهيار عابر (transient crash journal)، وليس تشخيص فشل مستقر: العملية الحية قد تنشر وضعها المقصود قبل الحفظ النهائي لمسح السجل، والإكمال الناجح يمسح السجل نفسه. إذا وجدته بدء التشغيل بعد تعطل، يقوم بدء التشغيل أولاً بفرض وإثبات BLOCK_ALL، ثم يستمر protected_policy_mutation_interrupted. رموز السبب المستقرة للتدهور هي:

• protected_policy_mutation_interrupted
• authoritative_protected_policy_failed
• incremental_deny_install_failed
• incremental_allow_removal_failed
• incremental_mode_change_failed

هذه تصنيفات مستقرة، وليست نص استدعاء نظام/تخزين خام. السجل قيد التقدم هو حد انهيار داخلي مستمر؛ إحصائيات ضربات القلب تتسلسل مع الطفرة المالكة وبالتالي تراقب إما مسحها الناجح أو تحويل الفشل المستقر، وليس السجل الوسيط الحي. تحتوي أسباب التدهور/الانقطاع المستقرة على تطبيق الحزمة في BLOCK_ALL المُثبت وترفض أوامر CIDR المتزايدة وأوامر وضع الحزمة. قد تستمر تغييرات تكوين DNS المستقلة وانتهاء صلاحية TTL لـ DNS تحت ذلك الإمساك المُثبت، لكن لا يمكنها مسح السبب المستقر أو إعادة تنشيط سياسة الحزمة. يتطلب الاسترداد من سبب مستقر حالة LPM كاملة و حالة DNS مرغوبة: طبق BulkUpdate عبر مستوى التحكم أو واجهة برمجة التطبيقات المحلية (أو أجب على Subscribed الجديد لارتباط مستعاد بـ SubscribedAck). يقوم Netfence بترتيب الحالة المحمية الكاملة، ويطبق حالة DNS الموثوقة، وينشط الوضع المطلوب، ويمسح السبب الدائم فقط بعد نجاح كل خطوة. يُفضل command_id فريد في BulkUpdate لاسترداد من مستوى التحكم وطلب CommandResult ناجح؛ ترفض واجهة برمجة التطبيقات المحلية command_id لأن نتيجة RPC أحادية الاتجاه (unary RPC) تُبلغ بالفعل عن النجاح أو الفشل.

تكشف ضربات القلب الإدخالات الفيزيائية الحالية والسعة الصلبة وأعلى قيم عملية الجيل بشكل مستقل لجميع الخرائط المحمية الأربع. يتم تضمين الإقلاع؛ الإدخالات المثبتة المُعتمدة (adopted pinned entries) تهيئ أعلى قيمة للجيل الجديد. map_full_drops تراكمي وتتضمن رفض السعة المحمية. إذا فشلت قراءة الإشغال، يحتفظ البرنامج الخفي بأحدث لقطة مُثبتة ويصدر تحذيرًا مرة واحدة على الأكثر كل 30 ثانية بدلاً من اختراع أعداد جديدة. للتعافي من الضغط، قلل القواعد المرغوبة الكاملة تحت سعة كل خريطة وأعد المحاولة للتحديث الكامل. رفع filter.max_rule_entries يكون فقط عند التحميل ويتطلب إعادة إنشاء ارتباط مثبت موجود. إذا لم يستطع البرنامج الخفي إثبات BLOCK_ALL أو تسجيل علامة الأمان بشكل دائم، فإنه يوقف قبول الطفرات؛ أصلح خطأ الخريطة/التخزين وأعد التشغيل بدلاً من افتراض إعادة فتح التنفيذ.

لكل مضيف

قم بتشغيل البرنامج الخفي، الذي:

• يُظهر واجهة برمجة تطبيقات gRPC محلية (DaemonService) للارتباطات والسياسة والتفتيش
• يتصل اختياريًا بمستوى التحكم الخاص بك عبر تدفق ثنائي الاتجاه (ControlPlane.Connect)
• يقوم بتحميل وإدارة برامج eBPF

ابدأ البرنامج الخفي:```bash

Start with default config

netfenced start

Start with custom config file

netfenced start --config /etc/netfence/config.yaml

**تحقق من حالة الخفي:**```bash
netfenced status

بدون control_plane.url، يتم تقديم مرفق جديد في وضع الحزمة/DNS المعطل ويمكن تكوينه فوراً من خلال واجهة برمجة التطبيقات المحلية أو سطر الأوامر. لا حاجة لعملية تحكم لأجل سير العمل المستقل الموثق تحت "لكل مرفق."

حدود الثقة لمقبس Unix المحلي

واجهة برمجة التطبيقات gRPC المحلية ليس لديها مصادقة لكل-RPC. الوصول إلى نظام الملفات لمقبس Unix الخاص بها هو حدود الترخيص، وكل عملية يمكنها الاتصال هي مسؤول شبكة مضيف موثوق به بالكامل: يمكنها إرفاق أو فصل برامج eBPF المضيفة، واستبدال سياسة الحزمة وDNS، وفتح أو إغلاق حركة مرور العمل. احتفظ بعضوية مجموعة المقبس ضيقة واحمِ الدليل الأصلي للمقبس.```yaml

Defaults to /var/run/netfence.sock.

socket: /run/netfence/netfence.sock

Unix group name or numeric GID. Empty/unset uses the daemon's effective GID.

socket_group: netfence-admin

`NETFENCE_SOCKET` و `NETFENCE_SOCKET_GROUP` هما متغيران بيئيان مكافئان. عند بدء التشغيل، يربط الخفي (daemon) المقبس في دليل مؤقت خاص، ويضبط مجموعته ووضعه على `0660` بينما لا يمكن الوصول إليه، ثم ينشره بشكل ذري. يزيل الخفي أي مقبس يونكس موجود مسبقًا في المسار المُهيأ—فهو لا يميز بين مقبس قديم وآخر مملوك لخفي آخر نشط—لذا يجب أن يكون خفي واحد فقط مالكًا لمسار المقبس. يرفض إزالة هدف ليس بمقبس. على نظام لينكس، يمنع إعادة التسمية بدون استبدال الكتابة فوق مسار جديد تم إنشاؤه بعد تلك الإزالة؛ وعند الإغلاق، يزيل المسار المنشور فقط طالما أنه لا يزال يعرف inode المقبس الخاص بالخفي. تؤدي مجموعة غير صحيحة، أو فشل في الملكية/الوضع، أو هدف غير مقبس إلى فشل بدء التشغيل دون نشر نقطة نهاية مسموحة.

### أمان طبقة النقل في مستوى التحكم (TLS / mTLS / bearer token)

قناة مستوى التحكم هي سطح الهجوم الأعلى قيمة في النظام (من يتحكم فيها يمكنه دفع قواعد `ALLOW` إلى كل عبء عمل)، لذا فإن الخفي **يفشل مغلقًا**: إذا تم تعيين `control_plane.url`، يجب أن يختار التكوين صراحةً ناقلًا — إما كتلة `control_plane.tls` أو `control_plane.insecure: true`. يتم رفض عنوان URL لا يحتوي على أي منهما عند بدء التشغيل؛ لا يوجد افتراضي نص عادي ضمني. (هذا تغيير متعمد في السلوك: الإصدارات الأقدم كانت تتصل بمستوى التحكم بدون تشفير بصمت.)```yaml
control_plane:
  url: cp.internal:443
  tls:
    # CA bundle used to verify the control-plane server certificate.
    # Path to a PEM file or inline PEM; omit to use the system root pool.
    ca: /etc/netfence/cp-ca.pem
    # Client certificate + key (path or inline PEM). Setting BOTH enables
    # mTLS: the daemon presents this cert to the control plane. Setting only
    # one is a config error.
    cert: /etc/netfence/daemon.pem
    key: /etc/netfence/daemon.key
    # Optional hostname override for server certificate verification (SNI),
    # e.g. when dialing by IP.
    server_name: cp.internal
  # Optional bearer token, sent as `authorization: Bearer <token>` metadata
  # on every control-plane RPC. Refused on a plaintext channel unless
  # `insecure: true` was explicitly set (so a misconfiguration can't leak it).
  auth_token: "..."

TLS مع جذور النظام فقط (شهادة خادم صادرة عن مرجع تصديق عام، لا mTLS) هو مجرد كتلة فارغة:```yaml control_plane: url: cp.example.com:443 tls: {}

النص العادي للتطوير المحلي هو اختيار صريح (حصرية مع `tls`):```yaml
control_plane:
  url: localhost:9000
  insecure: true

يتم تحميل الشهادات والمفاتيح مرة واحدة عند بدء التشغيل، لذا فإن مسارًا خاطئًا أو ملف PEM معطلاً يؤدي إلى فشل بدء التشغيل مع رسالة خطأ واضحة بدلاً من الظهور عند كل إعادة اتصال.

حيوية مستوى التحكم (keepalive) وتأخير إعادة الاتصال (backoff)

يرسل البرنامج الخفي (daemon) نبضات keepalive من نوع HTTP/2 على اتصال مستوى التحكم بحيث يتم اكتشاف المسار الميت بصمت (سحب الكابل، إسقاط تعيين NAT، مسار معتم) وإسقاطه في حوالي keepalive_time + keepalive_timeout — بدلاً من الجلوس بحالة CONNECTED لدقائق حتى انتهاء مهلة إعادة الإرسال TCP في النواة بينما كل استعلام DNS موقّت يستهلك مهلة كاملة. يتم ضبط وتيرة عمليات إعادة الاتصال باستخدام تراجع أسي مضاف إليه تموج (يبدأ عند 1 ثانية، يتضاعف، تموج ±20%، محدود بقيمة reconnect_backoff_max)؛ يعود التراجع إلى الحد الأدنى فقط بعد أن يظل الاتصال سليمًا لمدة 30 ثانية، بحيث أن مستوى التحكم الذي يقبل الاتصالات ثم يسقطها فورًا يستمر في التراجع بدلاً من أن يتعرض للضرب في الحد الأدنى.```yaml control_plane:

Send a keepalive ping after this much inactivity… (default 30s; gRPC

clamps the effective interval to a 10s minimum client-side)

keepalive_time: 30s

…and declare the peer dead if no ack arrives within this (default 10s).

keepalive_timeout: 10s

Cap on the jittered exponential reconnect backoff (default 30s).

reconnect_backoff_max: 30s

القيم الصفرية/غير المعينة تعني القيم الافتراضية — فهي **لا** تعطّل keepalive أو
الـ backoff. يجب أن تسمح لوحة التحكم الخاصة بك بوتيرة ping هذه في سياسة فرض keepalive gRPC الخاصة بها (انظر أدناه)، وإلا سترفض البرنامج الخفي برسالة
`ENHANCE_YOUR_CALM (too_many_pings)`.

### إعادة تشغيل البرنامج الخفي، تعطّله، وترقيته (حالة BPF المثبتة)

يقوم البرنامج الخفي بتثبيت روابط BPF وخرائط القواعد لكل إرفاق على bpffs
(`filter.bpf_pin_dir`، الافتراضي `/sys/fs/bpf/netfence`، دليل واحد لكل
معرّف إرفاق). نظرًا لأن الحالة المثبتة محتفظ بها بواسطة النواة — وليس عملية البرنامج الخفي
— **يستمر الفرض أثناء تعطل البرنامج الخفي**: تعطّل
(`kill -9`)، أو توقف آمن، أو ترقية يترك آخر سياسة معروفة
(وضع + جميع القواعد) مفروضة، وبدء تشغيل البرنامج الخفي التالي يعيد تبني الحالة المثبتة
كما هي. الاستعادة لا تعيد إرفاق أو إعادة كتابة الخرائط الحية، لذلك لا توجد
نافذة زمنية يتم فيها حظر حمل عمل مسموح به أو السماح بوجهة محظورة، ولا يوجد إرفاق مكرر.

سلوك الإيقاف هو إعداد صريح (`filter.detach_on_stop`):```yaml
filter:
  # false (default): stopping the daemon KEEPS ENFORCING — filters stay
  # attached via their bpffs pins and are re-adopted on the next start
  # (fail-closed across restarts/upgrades).
  # true: stopping the daemon detaches filters and removes their pins —
  # traffic is unfiltered while the daemon is down (explicit fail-open).
  detach_on_stop: false
  # bpffs directory for pinned state. Must be on a bpffs mount; the daemon
  # mounts bpffs at /sys/fs/bpf if needed (privileged). An explicit "" turns
  # pinning off entirely (BPF state then dies with the process).
  bpf_pin_dir: /sys/fs/bpf/netfence
  # Capacity of each authoritative/system LPM map (allowed/denied per family).
  # Protected entries are non-evictable; the DNS listener bootstrap consumes
  # one slot in its address family. Changing pinned-map capacity requires
  # recreating the attachment.
  max_rule_entries: 4096
  # Independent capacity of each DNS-derived exact-host HASH map (IPv4/IPv6).
  # These entries can never consume or evict authoritative/deny capacity.
  max_dns_rule_entries: 4096

Detach (RPC/CLI) صريح، أو إزالة هدف حي مملوك بشكل متماسك، يدمر الحالة المثبتة مع المرفق. عند إعادة التشغيل، لا يسمح غياب الهدف بالتخمين: يتم الاحتفاظ بالدبابيس المستمرة المستقبلية أو غير الملتزمة أو المختلطة أو التي لا يمكن التحقق منها بخلاف ذلك، ويتوقف الإقلاع للفحص.

دلائل الدبابيس هي تنسيق استمرار ذو إصدارات. يتم تثبيت علامة المخطط أخيرًا، فقط بعد وجود كل خريطة ورابط مطلوبين. ترقية مرفق بدقة مستوى سابق تثبت خرائط الدقيقة الفارغة الجديدة بعلامة قيد التقدم، وتستبدل برنامج كل رابط بشكل ذري مع إعادة استخدام الخرائط الموثوقة الحية، وتتحقق من هوية البرنامج/الخريطة، وتلتزم بالعلامة أخيرًا. يؤدي تعطل أو تحديث غامض إلى ترك العلامة غير ملتزمة؛ تقوم البداية التالية بإعادة تحديث كل رابط باستخدام نفس الخرائط. تفرض أجيال البرامج القديمة والجديدة نفس سياسة LPM الموثوقة خلال تلك الحالة المختلطة المحدودة، لذلك لا يؤدي الترحيل أبدًا إلى إلغاء تثبيت أو إعادة إنشاء مرشح قابل للتطبيق. يتم الاحتفاظ بمجموعات الدبابيس غير المعروفة أو غير المكتملة أو التي لا يمكن التحقق منها ويتم إجهاض الإقلاع للفحص بدلاً من تخمينها.

ملاحظات حول الحالة المعاد اعتمادها:

• يتم وضع علامة على كل مرفق تمت استعادته بنجاح للمصالحة الموثوقة. عند كل اتصال بمستوى التحكم، يرسل الخفي SyncRequest أولاً، ثم إعلان Subscribed كامل لكل مرفق تمت استعادته لا يزال بحاجة إلى المصالحة. الرد بـ SubscribedAck جديد: وضعه، CIDRs، TTLs، وتكوين DNS هي الحالة المرغوبة الكاملة. يطبق الخفي دلتا (لا تتم إزالة CIDRs غير المتغيرة أبدًا)، ويمسح علامة الاستعادة فقط بعد تطبيق الإقرار بالكامل. يؤدي انتهاء المهلة أو قطع الاتصال أو فشل التحقق إلى ترك التنفيذ دون تغيير. قد يؤدي فشل تطبيق المرشح/الخريطة/DNS/المخزن إلى ترك دلتا جزئية، لكن المصالحة لا تستخدم مسحًا كليًا للخريطة أو إزالة/إعادة إضافة الناجين غير المتغيرين؛ تظل علامة الاستعادة مضبوطة ويعيد الخفي المحاولة بعد اتصال لاحق.
• لا يتم استمرار مواعيد انتهاء صلاحية قواعد TTL نفسها. تُعالج القواعد المعاد اعتمادها مؤقتًا على أنها دائمة حتى يصل SubscribedAck الجديد؛ يستبدل هذا الإقرار الموثوق أعمارها تمامًا، بما في ذلك تقصير الموعد النهائي أو تحويل قاعدة مؤقتة دائمة مرة أخرى إلى قاعدة ذات TTL محدود. يتم جرد مفاتيح DNS الدقيقة المستعادة وتمثيلها بواسطة مالكين مؤقتين محددين (سعات الخريطة المثبتة الفعلية هي الحد)؛ يتجاهل تكوين DNS الموثوق الأول كل ادعاء اصطناعي، ويزيل المفاتيح التي تركت بدون مالك، ويحتفظ بمفتاح فقط عندما يكون له بشكل منفصل مالك حي عادي. يؤدي جرد غير قانوني/متضارب إلى إجهاض الاستعادة دون تخمين أو نشر بيانات ملكية جزئيًا.
• لا توجد وثيقة حالة مرغوبة محلية مستمرة. إذا لم يتم تكوين مستوى تحكم أو كان غير قابل للوصول، لا تحدث تغييرات تلقائية في القواعد: تستمر خريطة مثبتة معتمدة في فرض CIDRs المحمية المعروفة الأخيرة، ممثلة في سجل مساحة المستخدم على أنها مؤقتة حتى تحديث كامل. استعادة لا يمكنها اعتماد دبابيس صالحة تعيد إنشاء المرفق في وضعه المستمر بخرائط فارغة (فشل مغلق للقائمة البيضاء/حظر الكل). يجب على المنسق المستقل إعادة تشغيل netfenced apply-rules بعد كل إعادة تشغيل للخفي لاستبدال حالة الحزمة المؤقتة واستعادة حالته المرغوبة الكاملة وTTLs.
• قواعد مجال DNS، والتجاوزات الخاصة بالمرفق، وحدود DNS للمرفق هي حالة مرغوبة وقت التشغيل يتم توفيرها إما من خلال API المحلي أو مستوى التحكم؛ لا يتم استمرارها. يبدأ المرفق المستعاد الذي كان آخر وضع DNS له هو ALLOWLIST أو DENYLIST أو PROXY المحلل الخاص به في وضع ALLOWLIST فارغ، ويعيد حتى يتم تطبيق أو كامل. يظل وضع DNS المعطل صراحةً (DISABLED) في حالة إعادة التوجيه. إذا مات أي مستمع UDP/TCP ملتزم لاحقًا بشكل غير متوقع، يتم عزل المرفق في IP ويتم الإبلاغ عنه كإلغاء اشتراك خطأ.

لكل مرفق

يقوم نظام التنسيق الخاص بك باستدعاء API المحلي للخفي.

RPC:``` DaemonService.Attach(interface_name: "veth123", tc_direction: TC_DIRECTION_INGRESS, metadata: {vm_id: "abc"}) // or DaemonService.Attach(cgroup_path: "/sys/fs/cgroup/...", metadata: {container_id: "xyz"})

**CLI:**```bash
# Attach to a host-side veth peer or VM tap (TC) - use ingress direction
netfenced attach --interface veth123 --direction ingress --metadata vm_id=abc

# Attach to a cgroup
netfenced attach --cgroup /sys/fs/cgroup/... --metadata container_id=xyz

# Attach to an uplink inside the workload's own netns (TC) - egress is the default
netfenced attach --interface eth0 --metadata tenant=acme,env=prod

اتجاه TC: حقل tc_direction (CLI --direction) يحدد أي خطاف TCX يرتبط به المرشح، ويعتمد اختيار الخطاف الصحيح على أي جانب من الرابط توجد الواجهة:

الاتجاه ينطبق فقط على ارتباطات الواجهة (TC)؛ ويتم تجاهله لارتباطات cgroup.

• يقوم العميل بربط مرشح eBPF بالهدف.
• عندما يتم تكوين control_plane.url، يرسل العميل Subscribed{id, target, type, metadata} وينتظر SubscribedAck مع التكوين الأولي (الوضع، CIDRs، قواعد DNS). إذا لم يستجب مستوى التحكم خلال المهلة (افتراضي 5 ثوانٍ، قابل للتكوين عبر control_plane.subscribe_ack_timeout)، يتم التراجع عن الارتباط ويفشل استدعاء attach. تتبع فشل التحقق وغيرها من حالات الفشل قبل الالتزام نفس قاعدة التراجع العادية.
• بدون تكوين مستوى تحكم، يلتزم attach فورًا في الوضع المعطل؛ استخدم أوامر السياسة المحلية أدناه لتكوينه.
• السياسة الأولية الصالحة التي تصل إلى فشل مصيدة/مخزن محمي هي الاستثناء المتعمد للخطأ الملتزم: يحتفظ العميل بالارتباط في BLOCK_ALL الدائم بدلاً من التراجع عنه بشكل مدمر. مع مهلة محددة، يُرجع Attach خطأ يحتوي على معرف الارتباط المحتفظ به؛ يمكن للمتصل اكتشاف هذا المعرف من خلال مطابقة الهدف في List، ويجب على مستوى التحكم استرداده باستخدام BulkUpdate كامل.
• مع subscribe_ack_timeout: 0، يُرجع Attach جديد بعد وضع Subscribed في قائمة الانتظار؛ لا يزال يتم التحقق من ack لاحق وتطبيقه. هذه القيمة الصفرية لا تعطل التوفيق بين الارتباطات المستعادة: تحاول عملية الاستعادة الانتظار لمدة تصل إلى 5 ثوانٍ في الخلفية وتعيد المحاولة على اتصال لاحق إذا لزم الأمر. إذا وصل ذلك ack اللاحق إلى ضغط محمي، يتم الاحتفاظ بالارتباط الذي تم إرجاعه بالفعل في ؛ ولا يرسل أي أو خطأ، ولا يقوم العميل تلقائيًا بإعادة دفع الإعلان قبل إعادة التشغيل. اكتشف بالإضافة إلى سببه، والإشغال/السعة، و في ، ثم أرسل كامل مع للحصول على نتيجة استرداد صريحة.

RPC:``` DaemonService.Detach(id)

**CLI:**```bash
netfenced detach --id <attachment-id>

قائمة المرفقات:```bash netfenced list netfenced list --all # fetch all pages

### السياسة المحلية والتفتيش

كل تحويلة محلية هي تشفير خفيف لواجهة سطر الأوامر (CLI) لـ RPC المفردة `DaemonService.ApplyCommand(ControlCommand)`. قم بتوفير معرف المرفق (ID) الذي تم إرجاعه بواسطة `attach`:```bash
# Packet policy and protected CIDRs.
netfenced set-mode <id> allowlist
netfenced allow-cidr <id> 10.0.0.0/8
netfenced allow-cidr <id> 192.0.2.10/32 --ttl 5m
netfenced deny-cidr <id> 10.20.0.0/16
netfenced remove-cidr <id> 10.20.0.0/16 --list deny
# --list accepts allow, deny, or both (the default).

# DNS policy.
netfenced set-dns-mode <id> denylist
netfenced allow-domain <id> example.com --subdomains
netfenced deny-domain <id> blocked.example.com
netfenced remove-domain <id> blocked.example.com

# Deterministic current-policy inspection as protobuf JSON.
netfenced rules <id>

أوضاع الحزمة هي disabled و allowlist و denylist و block-all؛ وأوضاع DNS هي disabled و allowlist و denylist و proxy. يتطلب وضع DNS proxy وجود لوحة تحكم مهيأة وقابلة للوصول. يستخدم مطابقة النطاق لاحقة المطابقة الأكثر تحديدًا؛ عندما تتطابق قواعد السماح والمنع بنفس الدرجة من التحديد، تفوز قاعدة المنع. يتم توحيد CIDRs والنطاقات. يتم رفض القيم السالبة أو غير الصحيحة أو غير الصالحة بخلاف ذلك من TTLs، والتعدادات، وCIDRs، والنطاقات، والمحددات، والرسائل المتداخلة قبل التغيير، وبالتالي فإن الأمر غير الصالح هو عملية عدم تأثير على السياسة.

لاستبدال كامل، يقرأ apply-rules شكل protobuf JSON الحالي BulkUpdate من ملف أو من stdin:```bash cat >rules.json <<'JSON' { "mode": "POLICY_MODE_ALLOWLIST", "allowCidrs": [{"cidr": "10.0.0.0/8"}], "dns": { "mode": "DNS_MODE_DENYLIST", "denyDomains": [{"domain": "blocked.example.com", "includeSubdomains": true}] } } JSON netfenced apply-rules --file rules.json

Equivalent stdin form:

netfenced apply-rules --file - < rules.json

`ApplyCommand` يقبل فقط `SetMode`, `AllowCIDR`, `DenyCIDR`, `RemoveCIDR`,
`BulkUpdate`, `SetDnsMode`, `AllowDomain`, `DenyDomain`, و `RemoveDomain`.
يتم رفض المتغيرات الخاصة بالمزامنة/الإقرار الخاصة بالدفق فقط، والأوامر غير المعروفة أو الفارغة، وقيم
`command_id` المحلية. `BulkUpdate` هي أيضًا العملية المحلية الوحيدة
التي يمكنها استعادة سياسة حزم متدهورة مستقرة؛ يجب أن تحتوي على الحالة الكاملة المطلوبة لـ LPM و DNS.

يمكن لمحدد `ControlCommand.remove_cidr_list` الاختياري أن يستهدف قائمة السماح،
قائمة الرفض، أو كليهما عندما يكون نوع الأمر هو `RemoveCIDR`. قيمته القديمة
غير المحددة والقيمة الصريحة `BOTH` تزيلان من كلا القائمتين، مما يحافظ على
سلوك البروتوكول الأصلي.

الطفرات المحلية والخاصة بمستوى التحكم تشترك في محلل واحد، حاجز الطفرات، سجل TTL،
مسار الاسترداد للإغلاق عند الفشل، ومالك السياسة. لا يوجد عمدًا أي تحكيم
على الملكية بين المحلي ومستوى التحكم: العمليات المتضاربة على قائمة سياسة فردية
تصبح سارية المفعول بترتيب التزامها، بغض النظر عن المصدر. على وجه الخصوص، يمكن لعملية
`BulkUpdate` أو `SubscribedAck` كاملة لاحقة من مستوى التحكم استبدال الحالة المحلية.

`GetRules`/`netfenced rules` يُعيد لقطة سجل مستخدم متماسكة وحتمية.
يُبلغ كل CIDR عن قائمة السماح/الرفض، `policyOwned` محلي أو من مستوى التحكم،
`systemOwned` الخاص بالخفي، `expiresAt` المطلق، `provisional` المستعاد،
وحالة `installed` الأساسية الملتزمة الأخيرة. الإدخال المثبت مع عدم وجود مالك
هو إعادة محاولة لإزالة فاشلة، وليس سياسة مرغوبة. مخرجات DNS هي
`DnsConfig` الفعالة الحية والموحدة. لا يقوم التفتيش عمدًا بتعداد
خرائط النواة المحمية أو كشف إدخالات ذاكرة التخزين المؤقت للمضيف الدقيق لـ DNS المُحَل ديناميكيًا؛
استخدم قياسات نبضات القلب لشغل الخريطة المحمية.

## على مستوى التحكم (يمكنك تنفيذ هذا)

قم بتنفيذ RPC `ControlPlane.Connect` - دفق ثنائي الاتجاه:

قم بتكوين سياسة فرض keepalive لخادم gRPC الخاص بك للسماح
بإيقاع ping الخاص بالخفي (`control_plane.keepalive_time`، الافتراضي 30 ثانية): قم بتعيين
`MinTime` عند أو أقل من تلك الفترة الزمنية و `PermitWithoutStream: true`. سياسة
gRPC الافتراضية (5 دقائق) تعامل pings الخفي على أنها مسيئة وتغلق
الاتصال بـ `ENHANCE_YOUR_CALM (too_many_pings)`. في Go:```go
grpc.NewServer(grpc.KeepaliveEnforcementPolicy(keepalive.EnforcementPolicy{
    MinTime:             10 * time.Second,
    PermitWithoutStream: true,
}))

الاستلام من الخفي:

• SyncRequest عند الاتصال/إعادة الاتصال (يسرد المرفقات الحالية)
• Subscribed عند إضافة مرفقات جديدة، وبعد SyncRequest للمرفقات المستعادة التي لا تزال بحاجة إلى حالة موثوقة جديدة
• Unsubscribed عند إزالة المرفقات
• Heartbeat مع الإحصائيات
• CommandResult{command_id, id, success, error} — نتيجة أي أمر أرسلته مع command_id غير فارغ (رقم ربط اختياري في ControlCommand؛ الأوامر التي لا تحتوي على واحد لا تنتج نتيجة). success تكون صحيحة فقط إذا تم تطبيق الأمر بالكامل — BulkUpdate المطبق جزئيًا يبلغ عن فشل مع الخطأ المجمع. النتائج تكون بأفضل جهد: تعامل مع النتيجة المفقودة على أنها غير معروفة، وليس فاشلة.

الإرسال إلى الخفي:

• SyncAck بعد استلام SyncRequest
• SubscribedAck{mode, cidrs, dns_config} بعد استلام Subscribed (مطلوب - الخفي ينتظر هذا)
• SetMode{mode} - تغيير وضع سياسة تصفية IP
• AllowCIDR{cidr, ttl} / DenyCIDR / RemoveCIDR (اختياريًا، حدد السماح أو الرفض أو كليهما؛ غير المحدد يحتفظ بالسلوك "كلاهما" القديم)
• SetDnsMode{mode} - تغيير وضع تصفية DNS
• AllowDomain{domain} / DenyDomain / RemoveDomain (المطابقة الأكثر تحديدًا تفوز؛ الرفض يفوز في حالة التعادل بنفس التحديد)
• BulkUpdate{mode, cidrs, dns_config} - مزامنة الحالة الكاملة

عندما تتلقى طبقة التحكم Subscribed، يجب عليها الرد بـ SubscribedAck كاملة. بالنسبة للمرفق الجديد، ينتظر الخفي عادةً ذلك الإقرار قبل إرجاع النجاح إلى المتصل المحلي. بالنسبة للمرفق المستعاد، تتم المصافحة في الخلفية بينما تظل السياسة المعروفة الأخيرة المثبتة قيد التنفيذ. استخدم البيانات الوصفية لتحديد VM/tenant/container وأرجع الوضع الكامل المطلوب، CIDRs (بما في ذلك TTLs)، وحالة DNS؛ تكوين DNS المحذوف يعني معطل مع قوائم نطاق فارغة.

إعادة الاتصال وعدم التكرار (مطلوب)

SyncRequest هي نقطة التوفيق الموثوقة: في كل اتصال (إعادة) يكون أول حدث في الدفق ويسرد مجموعة المرفقات الحالية الكاملة للخفي. قم بتوفيق عرضك مقابلها — أضف المرفقات التي لم تكن تعرف عنها، وقم بإسقاط تلك الغائبة عن القائمة. عند إعادة الاتصال، يقوم الخفي بتنظيف الأحداث التي كانت في قائمة الانتظار مقابل الاتصال السابق (المزامنة تحل محلها)، لذا لن ترى Heartbeat قديمة، أو Unsubscribed لمرفقات غائبة بالفعل عن المزامنة، أو CommandResult من الاتصال الميت الذي يتم إعادة تشغيله بعد ذلك. تبقى حالتان حديتان حسب التصميم، ويجب على طبقة التحكم الخاصة بك التعامل معها بشكل غير متكرر:

• يمكن أن يتبع Subscribed SyncRequest الذي يسرد بالفعل نفس المعرف. يحدث هذا عندما كان إقرار مرفق جديد معلقًا عبر إعادة الاتصال، وعن قصد لكل مرفق مستعاد حتى يتم تطبيق إقرار موثوق واحد بالكامل. تعامل معه كتحديث، ورد بإقرار SubscribedAck كامل جديد، ولا تتخلص منه أبدًا كمكرر. SyncRequest يوفق مخزون المرفقات؛ SubscribedAck يوفق السياسة المطلوبة.
• يمكن أن يسبق حدث تم إنشاؤه بالتزامن مع (إعادة) الاتصال لقطة المزامنة في أي اتجاه. تعامل مع Unsubscribed لمعرف مرفق غير معروف أو تمت إزالته بالفعل كعملية لا تؤدي شيئًا.

فترات حياة القواعد (TTLs)

• تحمل إدخالات CIDR (أوامر AllowCIDR/DenyCIDR، وقوائم CIDR في SubscribedAck/BulkUpdate) TTL اختياري. تتم إزالة القواعد ذات TTL بواسطة مهمة تنظيف الخفي بمجرد انتهائها (فترة المسح ttl_janitor_interval، الافتراضي 1 ثانية)؛ القواعد بدون TTL تكون دائمة.
• إعادة الإضافة التزايدية لـ AllowCIDR/DenyCIDR تمد CIDR إلى الموعد النهائي الأحدث — لا تقصر أبدًا واحدًا — وإعادة الإضافة التزايدية بدون TTL تجعلها دائمة. في المقابل، تحل الحالة الكاملة في SubscribedAck/BulkUpdate محل كل عمر طبقة تحكم تمامًا، لذا يمكن للتوفيق الموثوق تقصير TTL أو تغيير الدائم إلى محدود دون إزالة/إعادة إضافة إدخال الخريطة الحية. استخدم RemoveCIDR لإسقاط قاعدة تزايدية مبكرًا.
• تدخل عناوين IP التي تم حلها عبر DNS فقط الطبقة الدقيقة مع TTL السجل مقيدًا بـ dns.min_filter_ttl (الافتراضي 60 ثانية؛ صفر/غير معين يعني الافتراضي، وليس "بدون حد"). وبالتالي فإن TTL المنبع بقيمة صفر يعيش لمدة الحد الأدنى؛ TTL PROXY المحذوف يتم تحديده افتراضيًا إلى 300 ثانية قبل تطبيق الحد الأدنى. تبقى قاعدة CIDR دائمة أو أطول تغطي نفس العنوان مثبتة بشكل مستقل في طبقة LPM المحمية عندما تنتهي صلاحية ملكية DNS الدقيقة.