Sibuna पुस्तक 1.0.0-beta.3 दस्तावेज़
भाषा: हिन्दी
English简体中文한국어日本語EspañolDeutschहिन्दीالعربية
इस पृष्ठ पर

भाग X: डेस्क संदर्भ और निदान

एंडपॉइंट, मेट्रिक, त्रुटि सूची, नीति स्कीमा और स्टोरेज टेबल, सब एक स्थान पर।

एंडपॉइंट

तालिका 27 आरक्षित रूट
एंडपॉइंट मेथड कार्य
/__sibuna/challenge GET इंटरस्टिशियल पेज
/__sibuna/challenge.json?need=&path= GET एक स्टेटलेस चैलेंज जारी करता है: चैलेंज वाले रिस्पॉन्स का आवश्यकता टिकट उसे तय करता है, अन्यथा रिपोर्ट किए गए URL का सामान्य रूप में मूल्यांकन होता है (8 KiB से ऊपर 414, सामान्य रूप न रखने वाले पाथ के लिए 400)। {id, algorithm, difficulty, challenges, expires_at} लौटाता है
/__sibuna/verify POST {"challenge_id", "nonce"} या {"challenge_id", "proof"} स्वीकार करता है; Set-Cookie के साथ 200, निदान के साथ 400, या कनेक्शन बफ़र से बड़ी बॉडी के लिए 413
/__sibuna/wasm/sibuna-pow.wasm GET सॉल्वर मॉड्यूल, 14,744 बाइट (benchmarks/results/primitives-latest.json में wasm_bytes), एक घंटे तक cache योग्य
/__sibuna/worker.js GET WASM और JavaScript प्रूवर वाला Web Worker, एक घंटे तक cache योग्य
/__sibuna/honeypot GET कॉल करने वाले पर --ban-seconds के लिए प्रतिबंध लगाता है और एक घटना दर्ज करता है; 403। केवल शीर्ष-स्तर का अनुरोध प्रतिबंध लगवाता है (Sec-Fetch-Dest न हो या document हो, और cross-site Sec-Fetch-Site न हो); किसी अन्य को 404 उत्तर मिलता है और उसे गिना जाता है
/__sibuna/health GET इंजन के नाम, संस्करण, प्रॉक्सी मोड और प्रमाण एल्गोरिदम के साथ JSON liveness स्टेटस
/__sibuna/metrics GET Prometheus टेक्स्ट प्रारूप (संस्करण 0.0.4)

/__sibuna/ के अंतर्गत किसी भी अन्य पाथ को 404 उत्तर मिलता है। जारी करना और सत्यापन अलग --challenge-rate-limit बजट खर्च करते हैं, और प्रतिबंधित पते को हर रूट पर 403 से अस्वीकार किया जाता है। चैलेंज रिस्पॉन्स X-Sibuna-Status: CHALLENGE ले जाते हैं; स्वीकृत अनुरोध अपस्ट्रीम की ओर X-Sibuna-Status: PASS और X-Sibuna-Rule ले जाते हैं (और forward-auth उत्तरों में हेक्साडेसिमल में X-Sibuna-Rule-Hash)। जो क्लाइंट HTML स्वीकार नहीं करता, उसे {"error":"challenge_required","challenge":"/__sibuna/challenge.json?need=<ticket>"} के साथ 401 मिलता है।

अलग, वैकल्पिक प्रबंधन listener /console/ देता है। इसके एडमिनिस्ट्रेटर को sibuna init-admin से स्थानीय रूप से प्रारंभ करें, फिर पहले साइन-इन पर अस्थायी पासवर्ड बदलें। /console/api/stats और /console/ws के लिए प्रमाणित सत्र चाहिए (kiosk सत्र सहित)। WebSocket सीमित स्नैपशॉट, delta और gap recovery के साथ आँकड़े, इवेंट, नोड, नीति, चैलेंज और ऑडिट को मल्टीप्लेक्स करता है। प्रबंधन पीयर /console/peer से जुड़ते हैं, और हर API रूट /console/api/ के अंतर्गत है। forward-auth मोड में ऑरिजिन त्रुटि काउंटर नहीं देखे जाते। भाग IX कंसोल के वर्कफ़्लो, HTTPS डिप्लॉयमेंट और SID 0007 की वर्तमान सीमाओं का दस्तावेज़ देता है।

मेट्रिक

Prometheus टेक्स्ट प्रारूप में sibuna_<name>_total के रूप में दिखाए जाने वाले काउंटर, इस क्रम में:

तालिका 28 काउंटर
काउंटर कब बढ़ता है
incidents_persisted, incident_batches वे रिकॉर्ड और ट्रांज़ैक्शन जिनके कमिट की पुष्टि स्टोरेज थ्रेड ने की
incidents_dropped, incident_write_failures रिंग भरी होने के कारण अस्वीकार किए गए कतार push, और कमिट के विफल प्रयास
requests पार्स किया गया अनुरोध डिस्पैच तक पहुँचा (आरक्षित रूट सहित)
allowed, denied, challenged नीति निर्णय लिया गया (स्वीकृत, अस्वीकृत, चैलेंज जारी या दोबारा जारी)
challenges_issued /__sibuna/challenge.json ने एक चैलेंज रिकॉर्ड जारी किया
solutions_accepted, solutions_rejected /__sibuna/verify ने किसी प्रमाण को स्वीकार या अस्वीकार किया
rate_limited GCRA ने किसी अनुरोध को अस्वीकार किया (429): अनुरोध सीमा, चैलेंज बजट या किसी नियम का कोटा
banned किसी प्रतिबंधित पते को अस्वीकार किया गया, या हनीपॉट ने किसी पर प्रतिबंध लगाया
bans_issued एक प्रतिबंध दर्ज किया गया (हनीपॉट या किसी नियम कोटा का प्रतिबंध)
proxied, upstream_errors एक अनुरोध ऑरिजिन तक रिले किया गया, या ऑरिजिन विफल हुआ (502)
parse_errors विकृत हेड, दोहराया गया Host, सामान्य रूप न रखने वाला लक्ष्य (400), या असमर्थित transfer coding (501) अस्वीकार किया गया
overloaded --max-connections या --max-connections-per-ip से आगे के कनेक्शन को 503 उत्तर मिला
bans_refused प्रतिबंध दर्ज नहीं हुआ, क्योंकि उसकी कुंजी जो भी स्लॉट ले सकती थी उन सभी में एक प्रभावी प्रतिबंध था
forwarded_invalid विश्वसनीय फ़ॉरवर्ड किया गया क्लाइंट पता पार्स नहीं हुआ; अनुरोध का निर्णय सॉकेट पीयर से हुआ
honeypot_refused हनीपॉट हिट से किसी पर प्रतिबंध नहीं लगा, क्योंकि उसे किसी व्यक्ति ने नहीं, एक पेज ने माँगा था
rate_evictions लिमिटर में किसी आगमन ने किसी दूसरे सक्रिय क्लाइंट की सेल को हटा दिया
ja4_present --ja4-header और विश्वसनीय फ़ॉरवर्डिंग के साथ, अनुरोध में उस नाम का ठीक एक हेडर JA4 फ़िंगरप्रिंट के साथ था
ja4_invalid --ja4-header और विश्वसनीय फ़ॉरवर्डिंग के साथ, हेडर विकृत या दोहराया गया था; अनुरोध का मूल्यांकन बिना फ़िंगरप्रिंट के हुआ

एक रीट्राई रिकॉर्ड खोए बिना incident_write_failures बढ़ा सकता है, क्योंकि लंबित बैच रखा जाता है। किसी अंतराल में हुई बढ़ोतरी की निगरानी करें; केवल कुल योग कतार की गहराई नहीं बताते।

स्टेटस कोड

तालिका 29 डेटा plane के स्टेटस कोड
कोड कब
200 स्वीकृत (forward-auth), इंटरस्टिशियल (चैलेंज की ज़रूरत वाला HTML नेविगेशन), आंतरिक रूट
302 वर्तमान प्रोटोकॉल में उपयोग नहीं होता; सत्यापन 200 उत्तर देता है और पेज दोबारा लोड होता है
400 विकृत अनुरोध, दोहराया गया Host फ़ील्ड, सामान्य रूप न रखने वाला लक्ष्य, अमान्य फ़ॉरवर्ड किया गया मेटाडेटा, विकृत बॉडी, या Elm-शैली के निदान के साथ अस्वीकृत समाधान
401 HTML स्वीकार न करने वाले क्लाइंट के लिए, या forward-auth मोड में, चैलेंज आवश्यक
403 नीति या WAF द्वारा अस्वीकृति, प्रतिबंधित पता, हनीपॉट
404 /__sibuna/ के अंतर्गत अज्ञात पाथ, या ऐसा हनीपॉट हिट जो शीर्ष-स्तर का अनुरोध नहीं है
413 समाधान की बॉडी 64 KB कनेक्शन बफ़र से बड़ी
414 रिपोर्ट किया गया चैलेंज URL 8 KiB से बड़ा
417 असमर्थित अनुरोध अपेक्षा (expectation); 100-continue स्थानीय रूप से संभाला जाता है
429 GCRA सीमा पार; Retry-After सेकंड में
431 अनुरोध हेड 16 KB से बड़ा
501 chunked के अलावा किसी अन्य coding वाला Transfer-Encoding
502 ऑरिजिन तक पहुँच नहीं, या उसका रिस्पॉन्स हेड विकृत था या 16 KB से बड़ा था
503 कनेक्शन सीमा (--max-connections या --max-connections-per-ip) पूरी, या नोड ड्रेन हो रहा है; उत्तर के बाद सॉकेट बंद कर दिया जाता है

त्रुटि सूची

INVALID COMMAND LINE हर उस विकल्प के लिए स्टार्टअप रोक देता है जिसे डेमन नहीं पहचानता, अपनी दस्तावेज़ित सीमा से बाहर के हर मान के लिए, और अमान्य, अनुपस्थित या दोहराए गए मोड चयन के लिए। ब्लॉक विकल्प, दिया गया मान, अपेक्षित सीमा और त्रुटि (UnknownOption, MissingValue, InvalidValue, InvalidMode, MissingMode, DuplicateMode, Zaxonlite क्लस्टर विकल्प के लिए RemovedOption, एक-दूसरे को बाहर करने वाले दो स्टोरेज विकल्पों के लिए ConflictingOptions, --cluster-node के बिना डेटाबेस URL के लिए MissingOption) का नाम देता है, और एक संकेत के साथ समाप्त होता है। डेटाबेस URL [redacted] के रूप में दिखाया जाता है। --mode reverse_proxy या --mode forward_auth एक बार दें; -m समतुल्य छोटा विकल्प है। अस्वीकृत नीति फ़ाइल अपनी त्रुटि के शीर्षक वाला एक ब्लॉक छापती है (उदाहरण के लिए INVALID POLICY ACTION), जिसमें फ़ाइल, त्रुटि का नाम, नियम, फ़ील्ड और मान होते हैं। ऐसा ja4 पैटर्न जिससे कोई फ़िंगरप्रिंट मेल नहीं खा सकता, INVALID POLICY JA4 (InvalidJa4) छापता है; ऐसे पैटर्न वाला कंसोल प्रबंधन दस्तावेज़ उसी त्रुटि नाम के साथ अस्वीकार होता है। कंसोल विकल्पों की जाँच अलग से होती है: CONSOLE002 विकृत या दोहराए गए कंसोल विकल्प का नाम देता है, और CONSOLE001 किसी नियम को तोड़ने वाले कंसोल कॉन्फ़िगरेशन का (स्टोरेज के बिना StorageRequired)।

तालिका 30 चैलेंज और सत्र की त्रुटियाँ
त्रुटि कारण संकेत
MalformedChallenge पहचानकर्ता एक सही रूप वाला चैलेंज रिकॉर्ड नहीं है नया चैलेंज लाएँ और उसे बिना बदले सबमिट करें
InvalidChallengeTag टैग प्रमाणित नहीं होता; इस क्लस्टर ने जारी नहीं किया या संपादित किया गया चैलेंज जाली नहीं बनाए जा सकते; नया माँगें
ChallengeExpired चैलेंज TTL से पुराना, या भविष्य में जारी किया गया नया चैलेंज माँगें
FingerprintMismatch किसी दूसरे पते या User-Agent से सबमिट किया गया उसी क्लाइंट से सबमिट करें जिसने उसे मँगाया था
DifficultyNotMet Hashcash नॉनस में आवश्यक शून्य बिट नहीं हैं नॉनस खोजते रहें
InvalidProof अनुक्रमिक कार्य का प्रमाण कमिट किए गए लेबल नहीं खोलता जारी की गई गहराई और ओपनिंग के लिए प्रूवर को पूरा चलाएँ
WrongSolutionType PoSW चैलेंज के लिए नॉनस या Hashcash के लिए प्रमाण समाधान के फ़ील्ड को एल्गोरिदम से मिलाएँ
DoubleSpendAttempt चैलेंज पहले ही खर्च हो चुका था चैलेंज एक बार ही उपयोग होते हैं
StoreFull spent set भरा हुआ है चैलेंज TTL घटाएँ या --spent-tags बढ़ाएँ
InvalidTokenSignature कुकी का टैग या हस्ताक्षर विफल इंटरस्टिशियल के ज़रिए दोबारा प्रमाणित हों
TokenExpired कुकी अपनी समाप्ति से आगे दोबारा प्रमाणित हों
TokenBoundAddressMismatch कुकी किसी दूसरी क्लाइंट पहचान से प्रस्तुत की गई कुकी साझा नहीं की जा सकतीं

कंसोल का API विफलता का उत्तर {"error":"<CODE>","hint":"<sentence>"} से देता है; hint वह टेक्स्ट है जो इंटरफ़ेस दिखाता है (crates/console/src/http/reply.rs)।

तालिका 31 ऑपरेटर से संबंधित कंसोल विफलता कोड
कोड स्टेटस अर्थ
CONSOLE002 400 अनुरोध विकृत है, बहुत बड़ा है, या अपने रूप में अनुमत नहीं है
CONSOLE003 503 / 429 स्टोरेज जॉब कतार भरी है (32 जॉब), या पासवर्ड सत्यापनकर्ता व्यस्त है
CONSOLEQUORUM 503 डेटाबेस ने अनुरोध की 10 सेकंड की प्रतीक्षा के भीतर उत्तर नहीं दिया; परिणाम अज्ञात है, और डेटा plane अंतिम लागू नीति से चलता रहता है
CONSOLE004 503 सेवा उत्तर नहीं दे सकती: इस बिल्ड में उपलब्ध नहीं, रुक रही है, या आंतरिक विफलता
CONSOLENODE 400 / 409 / 503 नोड कमांड अस्वीकार हुई: वह किसी दूसरे नोड का नाम देती है (400), पुराना boot या control revision (409), या वह तब आई जब कोई दूसरी कमांड चल रही थी या किसी पूर्णता को दर्ज नहीं किया जा सका (503); रीट्राई से पहले operation receipt की जाँच करें
CONSOLEMUTATION 429 एक सत्र से एक मिनट में साठ से अधिक प्रबंधन परिवर्तन (mutation)

नीति स्कीमा

{
  "default_action": "ALLOW" | "DENY" | "CHALLENGE",
  "waf": true | false,
  "inspection": { "path_traversal" | "sqli" | "xss" | "rce": "disabled" | "audit" | "enforce" },
  "thresholds": { "challenge_at": int, "deny_at": int, "bits_step": int },
  "ip_rules": { "<cidr>": "ALLOW" | "DENY" | "CHALLENGE", ... },
  "rules": [                                                    // अधिकतम 128
    {
      "name": "<kebab-case>",                                   // 1 से 128 printable बाइट
      "path" | "path_regex": "<pattern>",                       // अधिकतम 512 बाइट
      "user_agent" | "user_agent_regex": "<pattern>",
      "headers" | "headers_regex": { "<Header>": "<pattern>" }, // अधिकतम 4
      "remote_addresses" | "cidrs": ["<cidr>", ...],            // अधिकतम 8, IPv4 या IPv6
      "action": "ALLOW" | "DENY" | "CHALLENGE" | "WEIGH",
      "weight": int,                                            // केवल WEIGH, -1000..1000
      "challenge": { "difficulty": <work bits>, "algorithm": "hashcash" | "posw" },
      "limits": { "rate": int, "window_seconds": int, "ban_seconds": int },
      "ja4": "<fingerprint>" | "<prefix>*"                      // 36 बाइट, या प्रीफ़िक्स और *
    }
  ]
}

challenge_at और deny_at -1000 से 1000 के बीच होते हैं, deny_at का मान challenge_at के बराबर या उससे ऊपर होता है, और bits_step 1 से 1000 के बीच। challenge ब्लॉक केवल CHALLENGE नियमों का होता है, 1 से 64 वर्क बिट्स के साथ। limits किसी नियम को उसका अपना कोटा देता है: rate 1 से 1,000,000 और window_seconds 1 से 86,400 आवश्यक हैं, ban_seconds (अधिकतम 86,400) वैकल्पिक है, और WEIGH नियम सीमाएँ नहीं रख सकते। ja4 या तो एक पूरा JA4 फ़िंगरप्रिंट है, जिसके बराबर फ़िंगरप्रिंट होना चाहिए, या ऐसा प्रीफ़िक्स जिसके बाद * हो, और फ़िंगरप्रिंट उसी से शुरू होना चाहिए; अकेला * किसी भी फ़िंगरप्रिंट से मेल खाता है, और फ़िंगरप्रिंट रहित अनुरोध किसी ja4 नियम से मेल नहीं खाता। ऐसा पैटर्न जिससे कोई फ़िंगरप्रिंट मेल नहीं खा सकता, InvalidJa4 के साथ अस्वीकार होता है (भाग IX, इनग्रेस से JA4 फ़िंगरप्रिंट)। ip_rules का प्रतिष्ठा trie अधिकतम 8,192 नोड रखता है। हर नियम हर मानदंड की एक ही वर्तनी का उपयोग कर सकता है।

पैटर्न का व्याकरण: .* या * किसी भी चीज़ से मेल खाते हैं; ^...$ एक सटीक पाथ को बाँधता है; अंत में *, /* या .* प्रीफ़िक्स है; / से शुरू होने वाला पैटर्न सटीक पाथ है; बाकी सब केस-असंवेदी सबस्ट्रिंग है। पाथ पैटर्न सामान्य रूप वाले पाथ से मेल खाते हैं (खंडों के बीच एक स्लैश, कोई dot खंड नहीं, unreserved अक्षर unescaped, अन्य escape बड़े अक्षरों वाले हेक्साडेसिमल अंकों के साथ), इसलिए ;, %2F, %5C या \ रखने वाला पैटर्न किसी से मेल नहीं खाता, और पाथ मिलान केस-संवेदी है (SID 0003)।

स्टोरेज टेबल

policy_revision, policies (अधिकतम 37 बाइट के nullable ja4_pattern मानदंड के साथ), policy_inspection, ip_reputation, incident_receipts, security_incidents (256-बाइट एम्बेडिंग और nullable 36-बाइट ja4 फ़िंगरप्रिंट के साथ), full-text इंडेक्स (SQLite पर incidents_fts, canonical टोकन पर FTS5; PostgreSQL पर GIN इंडेक्स के साथ tsvector कॉलम search) और sibuna_schema; कंसोल 33 console_* टेबल जोड़ता है। संग्रहीत एक्शन, एल्गोरिदम और मोड के नाम छोटे अक्षरों में हैं। घटना id node_id << 40 | sequence हैं, जो बिना समन्वय के पूरे क्लस्टर में अद्वितीय हैं; नोड id 1 से 8,388,607 तक होते हैं।

बिल्ड टारगेट

तालिका 32 बिल्ड और रिपॉज़िटरी कमांड
कमांड परिणाम
cargo build --release -p sibuna SQLite स्टोरेज और कंसोल वाला डेमन (डिफ़ॉल्ट features)
cargo build --release -p sibuna --no-default-features मेमोरी में चलने वाला डेमन, स्टोरेज या कंसोल के बिना और किसी बाहरी क्रेट के बिना
cargo build --release -p sibuna --features postgres-tls डेमन जो एक साझा PostgreSQL डेटाबेस से भी जुड़ता है, सत्यापित TLS के साथ (केवल postgres feature TLS के बिना जुड़ता है)
cargo test यूनिट परीक्षण, चलते हुए डेमन पर integration परीक्षण, स्टोरेज और कंसोल परीक्षण (SIBUNA_TEST_DATABASE_URL सेट होने पर PostgreSQL वाले भी)
cargo clippy --all-targets, cargo fmt --check लिंट और फ़ॉर्मेटिंग (max_width = 99)
cargo xtask check 70-पंक्ति फ़ंक्शन, 1,408-पंक्ति फ़ाइल और 99/108-कॉलम पंक्ति की सीमाएँ; कोई टैब नहीं
cargo xtask browser headless Chromium में जाँचें (sibuna-browser)
cargo xtask bench <primitives|product|latency> रिलीज़ मोड के बेंचमार्क; परिणाम benchmarks/results/<command>-latest.json में
cargo build -p sibuna-pow-wasm --target wasm32-unknown-unknown --profile wasm केवल ब्राउज़र मॉड्यूल (कंसोल इंटरफ़ेस के लिए -p sibuna-console-ui)
cargo run -p sibuna-geoip --bin geoip-snapshot -- ... देश डेटा का सत्यापन करें और एम्बेड करने योग्य GeoIP स्नैपशॉट लिखें
guidedog build / guidedog dsc यह पुस्तक / SID रिकॉर्ड

डेमन की बिल्ड स्क्रिप्ट (cmd/sibuna/build.rs) दोनों WebAssembly मॉड्यूल को wasm प्रोफ़ाइल के साथ वर्कस्पेस की टारगेट डायरेक्टरी में बनाती है, और कंसोल इंटरफ़ेस 768 KiB से अधिक होने पर बिल्ड विफल कर देती है। wasm32-unknown-unknown टारगेट के बिना बिल्ड के लिए SIBUNA_POW_WASM और SIBUNA_CONSOLE_WASM इसके बजाय पहले से बने मॉड्यूल का नाम देते हैं। SIBUNA_GEOIP_DATA एम्बेड करने के लिए एक GeoIP स्नैपशॉट का नाम देता है; इसे बिल्ड के समय डिकोड किया जाता है, और कंसोल के बिना बिल्ड इसे अस्वीकार करता है (GEOIP001)।