mirror of
https://codeberg.org/cunicu/cunicu.git
synced 2025-09-27 05:06:02 +08:00
64 lines
20 KiB
HTML
64 lines
20 KiB
HTML
<!doctype html>
|
||
<html lang="en" dir="ltr" class="docs-wrapper plugin-docs plugin-id-default docs-version-current docs-doc-page docs-doc-id-index" data-has-hydrated="false">
|
||
<head>
|
||
<meta charset="UTF-8">
|
||
<meta name="generator" content="Docusaurus v3.4.0">
|
||
<title data-rh="true">Welcome | 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"><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="Welcome | cunīcu"><meta data-rh="true" name="description" content="GitHub build"><meta data-rh="true" property="og:description" content="GitHub build"><link data-rh="true" rel="icon" href="/img/favicon.png"><link data-rh="true" rel="canonical" href="https://cunicu.li/docs"><link data-rh="true" rel="alternate" href="https://cunicu.li/docs" hreflang="en"><link data-rh="true" rel="alternate" href="https://cunicu.li/docs" 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 menu__link--active" aria-current="page" 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 'Features'" 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 'Usage'" 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 'Configuration'" 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/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 'Development'" 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">Welcome</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"><p align="center"><img style="width:60%" src="/img/cunicu_logo.svg" alt="cunīcu logo"></p><p><a href="https://github.com/cunicu/cunicu/actions" target="_blank" rel="noopener noreferrer"><img decoding="async" loading="lazy" src="https://img.shields.io/github/actions/workflow/status/cunicu/cunicu/build.yaml?style=flat-square" alt="GitHub build" class="img_ev3q"></a>
|
||
<a href="https://goreportcard.com/report/github.com/cunicu/cunicu" target="_blank" rel="noopener noreferrer"><img decoding="async" loading="lazy" src="https://goreportcard.com/badge/github.com/cunicu/cunicu?style=flat-square" alt="goreportcard" class="img_ev3q"></a>
|
||
<a href="https://app.codecov.io/gh/cunicu/cunicu" target="_blank" rel="noopener noreferrer"><img decoding="async" loading="lazy" src="https://img.shields.io/codecov/c/github/cunicu/cunicu?token=WWQ6SR16LA&style=flat-square" alt="Codecov" class="img_ev3q"></a>
|
||
<a href="https://github.com/cunicu/cunicu/blob/main/LICENSE" target="_blank" rel="noopener noreferrer"><img decoding="async" loading="lazy" src="https://img.shields.io/github/license/cunicu/cunicu?style=flat-square" alt="License" class="img_ev3q"></a>
|
||
<img decoding="async" loading="lazy" src="https://img.shields.io/github/go-mod/go-version/cunicu/cunicu?style=flat-square" alt="GitHub go.mod Go version" class="img_ev3q">
|
||
<a href="https://pkg.go.dev/github.com/cunicu/cunicu" target="_blank" rel="noopener noreferrer"><img decoding="async" loading="lazy" src="https://pkg.go.dev/badge/github.com/cunicu/cunicu.svg" alt="Go Reference" class="img_ev3q"></a></p><p></p>
|
||
<div class="theme-admonition theme-admonition-caution admonition_xJq3 alert alert--warning"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 16 16"><path fill-rule="evenodd" d="M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z"></path></svg></span>cunīcu is currently still in an Alpha state and not usable yet 🚧</div></div>
|
||
<p><a href="https://github.com/cunicu/cunicu" target="_blank" rel="noopener noreferrer">cunīcu</a> is a user-space daemon managing <a href="https://wireguard.com" target="_blank" rel="noopener noreferrer">WireGuard®</a> interfaces to establish a mesh of peer-to-peer VPN connections in harsh network environments.</p>
|
||
<p>To achieve this, cunīcu utilizes a signaling layer to exchange peer information such as public encryption keys, hostname, advertised networks and reachability information to automate the configuration of the networking links.
|
||
From a user perspective, cunīcu alleviates the need of manual configuration such as exchange of public keys, IP addresses, endpoints, etc..
|
||
Hence, it adopts the design goals of the WireGuard project, to be simple and easy to use.</p>
|
||
<p>Thanks to <a href="https://en.wikipedia.org/wiki/Interactive_Connectivity_Establishment" target="_blank" rel="noopener noreferrer">Interactive Connectivity Establishment (ICE)</a>, cunīcu is capable to establish direct connections between peers which are located behind NAT firewalls such as home routers.
|
||
In situations where ICE fails, or direct UDP connectivity is not available, cunīcu falls back to using TURN relays to reroute traffic over an intermediate hop or encapsulate the WireGuard traffic via TURN-TCP.</p>
|
||
<p>It relies on the <a href="https://github.com/pion/awesome-pion" target="_blank" rel="noopener noreferrer">awesome</a> <a href="https://github.com/pion/ice" target="_blank" rel="noopener noreferrer">pion/ice</a> package for ICE as well as bundles the a Go user-space implementation of WireGuard in a single binary for systems in which WireGuard kernel support has not landed yet.</p>
|
||
<p>With these features, cunīcu can be used to quickly build multi-agent systems or connect field devices such as power grid monitoring infrastructure into a fully connected mesh.
|
||
Within the <a href="https://erigrid2.eu" target="_blank" rel="noopener noreferrer">ERIGrid 2.0 project</a>, cunīcu is used to interconnect smart grid laboratories for geographically distributed simulation of energy systems.</p>
|
||
<p>The project is currently actively developed by Steffen Vogel at the <a href="https://www.acs.eonerc.rwth-aachen.de" target="_blank" rel="noopener noreferrer">Institute for Automation of Complex Power Systems (ACS)</a> of <a href="https://www.rwth-aachen.de" target="_blank" rel="noopener noreferrer">RWTH Aachen University</a></p>
|
||
<h2 class="anchor anchorWithStickyNavbar_LWe7" id="getting-started">Getting started<a class="hash-link" aria-label="Direct link to Getting started" title="Direct link to Getting started" href="/docs#getting-started"></a></h2>
|
||
<p>To use cunīcu follow these steps on each host:</p>
|
||
<ol>
|
||
<li><a href="/docs/install">Install cunīcu</a></li>
|
||
<li>Configure your WireGuard interfaces using <code>wg</code>, <code>wg-quick</code> or <a href="https://blogs.gnome.org/thaller/2019/03/15/wireguard-in-networkmanager/" target="_blank" rel="noopener noreferrer">NetworkManager</a></li>
|
||
<li>Start the cunīcu daemon by running: <code>sudo cunicu daemon</code></li>
|
||
</ol>
|
||
<p>Make sure that in step 2. you have created WireGuard keys and exchanged them by hand between the hosts.
|
||
cunīcu does not (yet) discover available peers. You are responsible to add the peers to the WireGuard interface by yourself.</p>
|
||
<p>After the cunīcu daemons have been started, they will attempt to discover valid endpoint addresses using the ICE protocol (e.g. contacting STUN servers).
|
||
These <em>ICE candidates</em> are then exchanged via the signaling server and cunīcu will update the endpoint addresses of the WireGuard peers accordingly.
|
||
Once this has been done, the cunīcu logs should show a line <code>state=connected</code>.</p>
|
||
<h2 class="anchor anchorWithStickyNavbar_LWe7" id="name">Name<a class="hash-link" aria-label="Direct link to Name" title="Direct link to Name" href="/docs#name"></a></h2>
|
||
<p>The project name <em>cunīcu</em> [kʊˈniːkʊ] is derived from the <a href="https://en.wiktionary.org/wiki/cuniculus#Latin" target="_blank" rel="noopener noreferrer">latin noun cunīculus</a> which means rabbit, a rabbit burrow or underground tunnel. We have choosen it as a name for this project as <em>cunīcu</em> builds tunnels between otherwise hard to reach network locations.
|
||
It has been changed from the former name <em>wice</em> in order to broaden the scope of the project and avoid any potential trademark violations.</p></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/index.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--next" href="/docs/install"><div class="pagination-nav__sublabel">Next</div><div class="pagination-nav__label">Installation</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#getting-started">Getting started</a></li><li><a class="table-of-contents__link toc-highlight" href="/docs#name">Name</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> |