apps/cunicu
1
0
Fork 0
mirror of https://codeberg.org/cunicu/cunicu.git synced 2025-10-05 16:57:01 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
gh-pages
cunicu/docs/design.html
github-actions[bot] 18d289f88a deploy: a9ce32297f
2025-01-04 15:03:03 +00:00

126 lines
19 KiB
HTML
Raw Permalink Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!doctype html>
<html lang="en" dir="ltr" class="docs-wrapper plugin-docs plugin-id-default docs-version-current docs-doc-page docs-doc-id-design" data-has-hydrated="false">
<head>
<meta charset="UTF-8">
<meta name="generator" content="Docusaurus v3.4.0">
<title data-rh="true">Design | cunīcu</title><meta data-rh="true" name="viewport" content="width=device-width,initial-scale=1"><meta data-rh="true" name="twitter:card" content="summary_large_image"><meta data-rh="true" property="og:url" content="https://cunicu.li/docs/design"><meta data-rh="true" property="og:locale" content="en"><meta data-rh="true" name="docusaurus_locale" content="en"><meta data-rh="true" name="docsearch:language" content="en"><meta data-rh="true" name="keywords" content="go, golang, iot, networking, nat-traversal, vpn, vpn-manager, mesh, ice, multi-agent-systems, wireguard, edge-cloud, wireguard-vpn"><meta data-rh="true" name="twitter:creator" content="@stv0g"><meta data-rh="true" name="docusaurus_version" content="current"><meta data-rh="true" name="docusaurus_tag" content="docs-default-current"><meta data-rh="true" name="docsearch:version" content="current"><meta data-rh="true" name="docsearch:docusaurus_tag" content="docs-default-current"><meta data-rh="true" property="og:title" content="Design | cunīcu"><meta data-rh="true" name="description" content="Architecture"><meta data-rh="true" property="og:description" content="Architecture"><link data-rh="true" rel="icon" href="/img/favicon.png"><link data-rh="true" rel="canonical" href="https://cunicu.li/docs/design"><link data-rh="true" rel="alternate" href="https://cunicu.li/docs/design" hreflang="en"><link data-rh="true" rel="alternate" href="https://cunicu.li/docs/design" hreflang="x-default"><link rel="alternate" type="application/rss+xml" href="/blog/rss.xml" title="cunīcu RSS Feed">
<link rel="alternate" type="application/atom+xml" href="/blog/atom.xml" title="cunīcu Atom Feed">
<link rel="preconnect" href="https://matomo.0l.de/piwik.js">
<noscript>
var img = document.createElement('img');
img.src = "https://matomo.0l.de/piwik.php?idsite=5&rec=1&url=https://cunicu.li" + location.pathname;
img.style = "border:0";
img.alt = "tracker";
var s = document.getElementsByTagName('script')[0];
s.parentNode.insertBefore(img,s);
</noscript>
<script>window.dev=void 0,(!0===window.dev||"1"!==navigator.doNotTrack&&"1"!==window.doNotTrack)&&(window._paq=window._paq||[],window._paq.push(["setTrackerUrl","https://matomo.0l.de/piwik.php"]),window._paq.push(["setSiteId","5"]),window._paq.push(["enableHeartBeatTimer"]),window.start=new Date,function(){var e=document,t=e.createElement("script"),o=e.getElementsByTagName("script")[0];t.type="text/javascript",t.async=!0,t.defer=!0,t.src="https://matomo.0l.de/piwik.js",o.parentNode.insertBefore(t,o)}(),!0===window.dev&&(console.debug("[Matomo] Tracking initialized"),console.debug("[Matomo] matomoUrl: https://matomo.0l.de, siteId: 5")))</script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.13.24/dist/katex.min.css" integrity="sha384-odtC+0UGzzFL/6PNoE8rX/SPcQDXBJ+uRepguP4QkPCm2LBxH3FA3y+fKSiJ+AmM" crossorigin="anonymous"><link rel="stylesheet" href="/assets/css/styles.5ec7fe54.css">
<script src="/assets/js/runtime~main.ee3009b3.js" defer="defer"></script>
<script src="/assets/js/main.ac5db17a.js" defer="defer"></script>
</head>
<body class="navigation-with-keyboard">
<script>!function(){function t(t){document.documentElement.setAttribute("data-theme",t)}var e=function(){try{return new URLSearchParams(window.location.search).get("docusaurus-theme")}catch(t){}}()||function(){try{return window.localStorage.getItem("theme")}catch(t){}}();t(null!==e?e:"light")}(),function(){try{const n=new URLSearchParams(window.location.search).entries();for(var[t,e]of n)if(t.startsWith("docusaurus-data-")){var a=t.replace("docusaurus-data-","data-");document.documentElement.setAttribute(a,e)}}catch(t){}}()</script><div id="__docusaurus"><div role="region" aria-label="Skip to main content"><a class="skipToContent_fXgn" href="#__docusaurus_skipToContent_fallback">Skip to main content</a></div><nav aria-label="Main" class="navbar navbar--fixed-top"><div class="navbar__inner"><div class="navbar__items"><button aria-label="Toggle navigation bar" aria-expanded="false" class="navbar__toggle clean-btn" type="button"><svg width="30" height="30" viewBox="0 0 30 30" aria-hidden="true"><path stroke="currentColor" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2" d="M4 7h22M4 15h22M4 23h22"></path></svg></button><a class="navbar__brand" href="/"><div class="navbar__logo"><img src="/img/cunicu_icon.svg" alt="cunīcu logo" class="themedComponent_mlkZ themedComponent--light_NVdE"><img src="/img/cunicu_icon.svg" alt="cunīcu logo" class="themedComponent_mlkZ themedComponent--dark_xIcU"></div><b class="navbar__title text--truncate">cunīcu</b></a><a class="navbar__item navbar__link" href="/blog">📰 Blog</a><a href="https://discuss.cunicu.li" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">👋 Community</a><a aria-current="page" class="navbar__item navbar__link navbar__link--active" href="/docs">📚 Documentation</a></div><div class="navbar__items navbar__items--right"><a href="https://github.com/cunicu" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link header-github-link" aria-label="GitHub repository"></a><a href="https://codeberg.org/cunicu" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link header-codeberg-link" aria-label="Codeberg repository"></a><div class="navbarSearchContainer_Bca1"><div class="navbar__search"><span aria-label="expand searchbar" role="button" class="search-icon" tabindex="0"></span><input id="search_input_react" type="search" placeholder="Loading..." aria-label="Search" class="navbar__search-input search-bar" disabled=""></div></div></div></div><div role="presentation" class="navbar-sidebar__backdrop"></div></nav><div id="__docusaurus_skipToContent_fallback" class="main-wrapper mainWrapper_z2l0"><div class="docsWrapper_hBAB"><button aria-label="Scroll back to top" class="clean-btn theme-back-to-top-button backToTopButton_sjWU" type="button"></button><div class="docRoot_UBD9"><aside class="theme-doc-sidebar-container docSidebarContainer_YfHR"><div class="sidebarViewport_aRkj"><div class="sidebar_njMd"><nav aria-label="Docs sidebar" class="menu thin-scrollbar menu_SIkG"><ul class="theme-doc-sidebar-menu menu__list"><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link" href="/docs">Welcome</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link" href="/docs/install">Installation</a></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" href="/docs/features">Features</a><button aria-label="Expand sidebar category &#x27;Features&#x27;" aria-expanded="false" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" href="/docs/usage">Usage</a><button aria-label="Expand sidebar category &#x27;Usage&#x27;" aria-expanded="false" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" href="/docs/config">Configuration</a><button aria-label="Expand sidebar category &#x27;Configuration&#x27;" aria-expanded="false" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link menu__link--active" aria-current="page" href="/docs/design">Design</a></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" href="/docs/dev">Development</a><button aria-label="Expand sidebar category &#x27;Development&#x27;" aria-expanded="false" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link" href="/docs/comparison">Comparison</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link" href="/docs/funding">Funding</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link" href="/docs/license">Licence</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link" href="/docs/legal">Legal</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link" href="/docs/contact">Contact</a></li></ul></nav></div></div></aside><main class="docMainContainer_TBSr"><div class="container padding-top--md padding-bottom--lg"><div class="row"><div class="col docItemCol_VOVn"><div class="docItemContainer_Djhp"><article><nav class="theme-doc-breadcrumbs breadcrumbsContainer_Z_bl" aria-label="Breadcrumbs"><ul class="breadcrumbs" itemscope="" itemtype="https://schema.org/BreadcrumbList"><li class="breadcrumbs__item"><a aria-label="Home page" class="breadcrumbs__link" href="/"><svg viewBox="0 0 24 24" class="breadcrumbHomeIcon_YNFT"><path d="M10 19v-5h4v5c0 .55.45 1 1 1h3c.55 0 1-.45 1-1v-7h1.7c.46 0 .68-.57.33-.87L12.67 3.6c-.38-.34-.96-.34-1.34 0l-8.36 7.53c-.34.3-.13.87.33.87H5v7c0 .55.45 1 1 1h3c.55 0 1-.45 1-1z" fill="currentColor"></path></svg></a></li><li itemscope="" itemprop="itemListElement" itemtype="https://schema.org/ListItem" class="breadcrumbs__item breadcrumbs__item--active"><span class="breadcrumbs__link" itemprop="name">Design</span><meta itemprop="position" content="1"></li></ul></nav><div class="tocCollapsible_ETCw theme-doc-toc-mobile tocMobile_ITEo"><button type="button" class="clean-btn tocCollapsibleButton_TO0P">On this page</button></div><div class="theme-doc-markdown markdown"><h1>Design</h1>
<h2 class="anchor anchorWithStickyNavbar_LWe7" id="architecture">Architecture<a class="hash-link" aria-label="Direct link to Architecture" title="Direct link to Architecture" href="/docs/design#architecture">​</a></h2>
<p><img decoding="async" loading="lazy" src="/assets/images/architecture-698f935e44bbe4e44537cc165a669ff3.svg" width="901" height="629" class="img_ev3q"></p>
<h2 class="anchor anchorWithStickyNavbar_LWe7" id="objectives">Objectives<a class="hash-link" aria-label="Direct link to Objectives" title="Direct link to Objectives" href="/docs/design#objectives">​</a></h2>
<ul>
<li>
<p>Encrypt all signaling messages</p>
</li>
<li>
<p>Plug-able signaling backends:</p>
<ul>
<li>gRPC</li>
</ul>
</li>
<li>
<p>Support <a href="https://datatracker.ietf.org/doc/html/rfc8838" target="_blank" rel="noopener noreferrer">Trickle ICE</a></p>
</li>
<li>
<p>Support <a href="https://datatracker.ietf.org/doc/html/rfc8445#section-2.4" target="_blank" rel="noopener noreferrer">ICE restart</a></p>
</li>
<li>
<p>Support <a href="https://datatracker.ietf.org/doc/html/rfc6544" target="_blank" rel="noopener noreferrer">ICE-TCP</a></p>
</li>
<li>
<p>Encrypt exchanged ICE offers with WireGuard keys</p>
</li>
<li>
<p>Seamless switch between ICE candidates and relays</p>
</li>
<li>
<p>Zero configuration</p>
<ul>
<li>Alleviate users of exchanging endpoint IPs &amp; ports</li>
</ul>
</li>
<li>
<p>Enables direct communication of WireGuard peers behind NAT / UDP-blocking firewalls</p>
</li>
<li>
<p>Single-binary, zero dependency installation</p>
<ul>
<li>Bundled ICE agent &amp; <a href="https://git.zx2c4.com/wireguard-go" target="_blank" rel="noopener noreferrer">WireGuard user-space daemon</a></li>
<li>Portability</li>
</ul>
</li>
<li>
<p>Support for user and kernel-space WireGuard implementations</p>
</li>
<li>
<p>Zero performance impact</p>
<ul>
<li>Kernel-side filtering / redirection of WireGuard traffic</li>
<li>Fallback to user-space proxying only if no Kernel features are available</li>
</ul>
</li>
<li>
<p>Minimized attack surface</p>
<ul>
<li>Drop privileges after initial configuration</li>
</ul>
</li>
<li>
<p>Compatible with existing WireGuard configuration utilities like:</p>
<ul>
<li><a href="https://github.com/max-moser/network-manager-wireguard" target="_blank" rel="noopener noreferrer">NetworkManager</a></li>
<li><a href="https://www.freedesktop.org/software/systemd/man/systemd.netdev.html#%5BWireGuard%5D%20Section%20Options" target="_blank" rel="noopener noreferrer">systemd-networkd</a></li>
<li><a href="https://manpages.debian.org/unstable/wireguard-tools/wg-quick.8.en.html" target="_blank" rel="noopener noreferrer">wg-quick</a></li>
<li><a href="https://kilo.squat.ai" target="_blank" rel="noopener noreferrer">Kilo</a></li>
<li><a href="https://seashell.github.io/drago/" target="_blank" rel="noopener noreferrer">drago</a></li>
</ul>
</li>
<li>
<p>Monitoring for new WireGuard interfaces and peers</p>
<ul>
<li>Inotify for new UAPI sockets in /var/run/wireguard</li>
<li>Netlink subscription for link updates (patch is pending)</li>
</ul>
</li>
</ul>
<h2 class="anchor anchorWithStickyNavbar_LWe7" id="related-rfcs">Related RFCs<a class="hash-link" aria-label="Direct link to Related RFCs" title="Direct link to Related RFCs" href="/docs/design#related-rfcs">​</a></h2>
<ul>
<li><a href="https://datatracker.ietf.org/doc/html/rfc6544" target="_blank" rel="noopener noreferrer">RFC6544</a> TCP Candidates with Interactive Connectivity Establishment (ICE)</li>
<li><a href="https://datatracker.ietf.org/doc/html/rfc8838" target="_blank" rel="noopener noreferrer">RFC8838</a> Trickle ICE: Incremental Provisioning of Candidates for the Interactive Connectivity Establishment (ICE) Protocol</li>
<li><a href="https://datatracker.ietf.org/doc/html/rfc8445" target="_blank" rel="noopener noreferrer">RFC8445</a> Interactive Connectivity Establishment (ICE): A Protocol for Network Address Translator (NAT) Traversal</li>
<li><a href="https://datatracker.ietf.org/doc/html/rfc8863" target="_blank" rel="noopener noreferrer">RFC8863</a> Interactive Connectivity Establishment Patiently Awaiting Connectivity (ICE PAC)</li>
<li><a href="https://datatracker.ietf.org/doc/html/rfc8839" target="_blank" rel="noopener noreferrer">RFC8839</a> Session Description Protocol (SDP) Offer/Answer Procedures for Interactive Connectivity Establishment (ICE)</li>
<li><a href="https://datatracker.ietf.org/doc/html/rfc6062" target="_blank" rel="noopener noreferrer">RFC6062</a> Traversal Using Relays around NAT (TURN) Extensions for TCP Allocations</li>
<li><a href="https://datatracker.ietf.org/doc/html/rfc8656" target="_blank" rel="noopener noreferrer">RFC8656</a> Traversal Using Relays around NAT (TURN): Relay Extensions to Session Traversal Utilities for NAT (STUN)</li>
<li><a href="https://datatracker.ietf.org/doc/html/rfc8489" target="_blank" rel="noopener noreferrer">RFC8489</a> Session Traversal Utilities for NAT (STUN)</li>
<li><a href="https://datatracker.ietf.org/doc/html/rfc8866" target="_blank" rel="noopener noreferrer">RFC8866</a> SDP: Session Description Protocol</li>
<li><a href="https://datatracker.ietf.org/doc/html/rfc3264" target="_blank" rel="noopener noreferrer">RFC3264</a> An Offer/Answer Model with the Session Description Protocol (SDP)</li>
<li><a href="https://datatracker.ietf.org/doc/html/rfc7064" target="_blank" rel="noopener noreferrer">RFC7064</a> URI Scheme for the Session Traversal Utilities for NAT (STUN) Protocol</li>
<li><a href="https://datatracker.ietf.org/doc/html/rfc7065" target="_blank" rel="noopener noreferrer">RFC7065</a> Traversal Using Relays around NAT (TURN) Uniform Resource Identifiers</li>
</ul></div><footer class="theme-doc-footer docusaurus-mt-lg"><div class="row margin-top--sm theme-doc-footer-edit-meta-row"><div class="col"><a href="https://github.com/cunicu/cunicu/edit/main/docs/design.md" target="_blank" rel="noopener noreferrer" class="theme-edit-this-page"><svg fill="currentColor" height="20" width="20" viewBox="0 0 40 40" class="iconEdit_Z9Sw" aria-hidden="true"><g><path d="m34.5 11.7l-3 3.1-6.3-6.3 3.1-3q0.5-0.5 1.2-0.5t1.1 0.5l3.9 3.9q0.5 0.4 0.5 1.1t-0.5 1.2z m-29.5 17.1l18.4-18.5 6.3 6.3-18.4 18.4h-6.3v-6.2z"></path></g></svg>Edit this page</a></div><div class="col lastUpdated_JAkA"></div></div></footer></article><nav class="pagination-nav docusaurus-mt-lg" aria-label="Docs pages"><a class="pagination-nav__link pagination-nav__link--prev" href="/docs/config/schema"><div class="pagination-nav__sublabel">Previous</div><div class="pagination-nav__label">JSON Schema</div></a><a class="pagination-nav__link pagination-nav__link--next" href="/docs/dev"><div class="pagination-nav__sublabel">Next</div><div class="pagination-nav__label">Development</div></a></nav></div></div><div class="col col--3"><div class="tableOfContents_bqdL thin-scrollbar theme-doc-toc-desktop"><ul class="table-of-contents table-of-contents__left-border"><li><a class="table-of-contents__link toc-highlight" href="/docs/design#architecture">Architecture</a></li><li><a class="table-of-contents__link toc-highlight" href="/docs/design#objectives">Objectives</a></li><li><a class="table-of-contents__link toc-highlight" href="/docs/design#related-rfcs">Related RFCs</a></li></ul></div></div></div></div></main></div></div></div><footer class="footer footer--dark"><div class="container container-fluid"><div class="row footer__links"><div class="col footer__col"><div class="footer__title">Documentation</div><ul class="footer__items clean-list"><li class="footer__item"><a class="footer__link-item" href="/docs">Tutorial</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/legal">Legal</a></li></ul></div><div class="col footer__col"><div class="footer__title">Community</div><ul class="footer__items clean-list"><li class="footer__item"><a href="https://discuss.cunicu.li" target="_blank" rel="noopener noreferrer" class="footer__link-item">Forum<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li class="footer__item"><a href="https://fosstodon.org/@cunicu" target="_blank" rel="noopener noreferrer" class="footer__link-item">Fediverse<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li></ul></div><div class="col footer__col"><div class="footer__title">More</div><ul class="footer__items clean-list"><li class="footer__item"><a class="footer__link-item" href="/blog">Blog</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/contact">Contact</a></li></ul></div></div><div class="footer__bottom text--center"><div class="footer__copyright">Copyright © 2025 Steffen Vogel.</div></div></div></footer></div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink