From 95258be27446b3584528c5bc7177aca40ddba2d5 Mon Sep 17 00:00:00 2001 From: Dimitri Staessens Date: Fri, 5 Jul 2019 22:27:04 +0200 Subject: content: Reorganize to better suit ananke theme --- config.toml | 99 +++++++- content/_index.md | 6 +- content/about.md | 35 --- content/about/about.md | 31 +++ content/about/contribute.md | 80 +++++++ content/about/philosophy.md | 56 +++++ content/compopt.html | 434 --------------------------------- content/contact/contribute.md | 80 +++++++ content/contribute.md | 83 ------- content/dev-tut-1.md | 73 ------ content/docs/_index.md | 6 + content/docs/compopt.html | 435 ++++++++++++++++++++++++++++++++++ content/docs/development/_index.md | 6 + content/docs/documentation.md | 41 ++++ content/docs/faq.md | 122 ++++++++++ content/docs/manuals.md | 18 ++ content/docs/performance.md | 74 ++++++ content/docs/quickstart.md | 11 + content/docs/tutorials/_index.md | 5 + content/docs/tutorials/dev-tut-1.md | 73 ++++++ content/docs/tutorials/tutorial-1.md | 153 ++++++++++++ content/docs/tutorials/tutorial-2.md | 297 +++++++++++++++++++++++ content/docs/tutorials/tutorial-3.md | 210 ++++++++++++++++ content/docs/tutorials/tutorial-4.md | 123 ++++++++++ content/documentation.md | 43 ---- content/download.md | 25 -- content/download/_index.md | 6 + content/download/download.md | 26 ++ content/download/install.md | 52 ++++ content/download/requirements.md | 71 ++++++ content/extra.md | 169 ------------- content/extra/_index.md | 6 + content/extra/ioq3.md | 96 ++++++++ content/extra/raptor.md | 59 +++++ content/extra/rumba.md | 11 + content/faq.md | 121 ---------- content/install.md | 52 ---- content/manuals.md | 17 -- content/performance.md | 73 ------ content/philosophy.md | 57 ----- content/requirements.md | 71 ------ content/tutorial-1.md | 153 ------------ content/tutorial-2.md | 297 ----------------------- content/tutorial-3.md | 210 ---------------- content/tutorial-4.md | 123 ---------- layouts/partials/site-navigation.html | 72 ++++++ static/javascript/dropdown.js | 10 + 47 files changed, 2327 insertions(+), 2044 deletions(-) delete mode 100644 content/about.md create mode 100644 content/about/about.md create mode 100644 content/about/contribute.md create mode 100644 content/about/philosophy.md delete mode 100644 content/compopt.html create mode 100644 content/contact/contribute.md delete mode 100644 content/contribute.md delete mode 100644 content/dev-tut-1.md create mode 100644 content/docs/_index.md create mode 100644 content/docs/compopt.html create mode 100644 content/docs/development/_index.md create mode 100644 content/docs/documentation.md create mode 100644 content/docs/faq.md create mode 100644 content/docs/manuals.md create mode 100644 content/docs/performance.md create mode 100644 content/docs/quickstart.md create mode 100644 content/docs/tutorials/_index.md create mode 100644 content/docs/tutorials/dev-tut-1.md create mode 100644 content/docs/tutorials/tutorial-1.md create mode 100644 content/docs/tutorials/tutorial-2.md create mode 100644 content/docs/tutorials/tutorial-3.md create mode 100644 content/docs/tutorials/tutorial-4.md delete mode 100644 content/documentation.md delete mode 100644 content/download.md create mode 100644 content/download/_index.md create mode 100644 content/download/download.md create mode 100644 content/download/install.md create mode 100644 content/download/requirements.md delete mode 100644 content/extra.md create mode 100644 content/extra/_index.md create mode 100644 content/extra/ioq3.md create mode 100644 content/extra/raptor.md create mode 100644 content/extra/rumba.md delete mode 100644 content/faq.md delete mode 100644 content/install.md delete mode 100644 content/manuals.md delete mode 100644 content/performance.md delete mode 100644 content/philosophy.md delete mode 100644 content/requirements.md delete mode 100644 content/tutorial-1.md delete mode 100644 content/tutorial-2.md delete mode 100644 content/tutorial-3.md delete mode 100644 content/tutorial-4.md create mode 100644 layouts/partials/site-navigation.html create mode 100644 static/javascript/dropdown.js diff --git a/config.toml b/config.toml index afaa1d0..93f8126 100644 --- a/config.toml +++ b/config.toml @@ -4,18 +4,103 @@ title = "Ouroboros" theme = "ananke" enableRobotsTXT = true DefaultContentLanguage = "en" +#MetaDataFormat = "yaml" [params] description = "Ouroboros is a decentralized packet network" favicon = "/images/ouroboros_icon.png" logo = "/images/ouroboros_compact_64px.png" featured_image = "/images/ouroboros_bg3.jpg" - -[params.copy] -copy = "" +twitter = "https://twitter.com/ODecentralize" +date_format = "January 2, 2006" +copyright = "CC BY-SA" +author = "Dimitri Staessens" +defaultDestcription = "Ouroboros" [menu] -[[menu.main]] -name = "Repository" -weight = 40 -url = "/cgit" + + [[menu.main]] + name = "Download" + weight = 1 + url = "/download/" + # [[menu.main]] + # name = "Get Ouroboros" + # parent = "Download" + # weight = 1 + # url = "/download/get/" + # [[menu.main]] + # name = "Install" + # parent = "Download" + # weight = 2 + # url = "/download/install/" + # [[menu.main]] + # name = "Requirements" + # parent = "Download" + # weight = 3 + # url = "/download/requirements/" + + [[menu.main]] + name = "Documentation" + weight = 2 + identifier = "id_docs" + url = "/docs/" + [[menu.main]] + name = "Getting started" + parent = "id_docs" + weight = 1 + identifier = "id_docs_qs" + url = "/docs/quickstart/" + [[menu.main]] + name = "Tutorials" + parent = "id_docs" + weight = 2 + identifier = "id_tut" + url = "/docs/tutorials/" + [[menu.main]] + name = "Development" + parent = "id_docs" + weight = 3 + identifier = "id_devt" + url = "/docs/development/" + [[menu.main]] + name = "Manual" + parent = "id_docs" + weight = 4 + identifier = "id_man" + url = "/man/" + + [[menu.main]] + name = "Extra" + weight = 3 + identifier = "id_extra" + url = "/extra/" + # [[menu.main]] + # name = "Rumba" + # parent = "id_extra" + # weight = 1 + # identifier = "id_extra" + # url = "/extra/rumba/" + # [[menu.main]] + # name = "IoQuake3" + # parent = "id_extra" + # weight = 2 + # identifier = "id_extra" + # url = "/extra/ioq3/" + # [[menu.main]] + # name = "Raptor" + # parent = "id_extra" + # weight = 3 + # identifier = "id_extra_raptor" + # url = "/extra/raptor/" + + [[menu.main]] + name = "About" + weight = 4 + identifier = "id_about" + url = "/about/" + + [[menu.main]] + name = "Repository" + weight = 100 + identifier = "id_repo" + url = "/cgit/" diff --git a/content/_index.md b/content/_index.md index 6a79621..5ac1f6a 100644 --- a/content/_index.md +++ b/content/_index.md @@ -1,5 +1,7 @@ --- -title: "The first completely decentralized packet network" +title: "A completely decentralized packet network" +date: 2019-06-22 +draft: false --- Ouroboros is a __peer-to-peer transport network__ built on a new @@ -9,6 +11,7 @@ networking experience and __simplify writing distributed software__ and networking libraries. It provides a __very simple API__, enabling __unicast__ and __multicast__ services. + This new website is currently under construction and undergoing frequent updates. The documentation is still sparse, please don't diff --git a/content/about.md b/content/about.md deleted file mode 100644 index 0ac9966..0000000 --- a/content/about.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: "About" -menu: "main" -draft: false -menu: - main: - weight: 30 ---- - -The Ouroboros project is a decentralized packet network implementation -started by Sander Vrijders and Dimitri Staessens. - -### Licenses - -Ouroboros is [free -software](https://www.gnu.org/philosophy/free-sw.html). The libraries -are available under the [GNU Lesser Public License (LGPL) version -2.1](https://www.gnu.org/licenses/old-licenses/lgpl-2.1.html). The -daemons are available under the [GNU Public License (GPL) version -2](https://www.gnu.org/licenses/old-licenses/gpl-2.0.html). The tools -are availabe under the [3-Clause BSD -License](https://opensource.org/licenses/BSD-3-Clause). - -Ouroboros logos © Dimitri Staessens. All Rights Reserved. - -### Disclaimer - -Ouroboros is distributed in the hope that it will be useful, but without -any warranty; without even the implied warranty of merchantability or -fitness for a particular purpose. - -At present, Ouroboros is a research prototype. Although it is developed -with utmost care, it may expose the host system to unknown security -risks and attack vectors. As such, we recommend to test it in a -contained environment. diff --git a/content/about/about.md b/content/about/about.md new file mode 100644 index 0000000..b518751 --- /dev/null +++ b/content/about/about.md @@ -0,0 +1,31 @@ +--- +title: "About" +draft: false +--- + +The Ouroboros project is a decentralized packet network implementation +started by Sander Vrijders and Dimitri Staessens. + +### Licenses + +Ouroboros is [free +software](https://www.gnu.org/philosophy/free-sw.html). The libraries +are available under the [GNU Lesser Public License (LGPL) version +2.1](https://www.gnu.org/licenses/old-licenses/lgpl-2.1.html). The +daemons are available under the [GNU Public License (GPL) version +2](https://www.gnu.org/licenses/old-licenses/gpl-2.0.html). The tools +are availabe under the [3-Clause BSD +License](https://opensource.org/licenses/BSD-3-Clause). + +Ouroboros logos © Dimitri Staessens. All Rights Reserved. + +### Disclaimer + +Ouroboros is distributed in the hope that it will be useful, but without +any warranty; without even the implied warranty of merchantability or +fitness for a particular purpose. + +At present, Ouroboros is a research prototype. Although it is developed +with utmost care, it may expose the host system to unknown security +risks and attack vectors. As such, we recommend to test it in a +contained environment. diff --git a/content/about/contribute.md b/content/about/contribute.md new file mode 100644 index 0000000..5dbe7ad --- /dev/null +++ b/content/about/contribute.md @@ -0,0 +1,80 @@ +--- +title: Contact +date: 2019-06-22 +draft: false +--- + +General discussion and support +------------------------------ + +For general discussion of Ouroboros, +[subscribe](https://www.freelists.org/list/ouroboros) to our mailing +list: [ouroboros@freelists.org](mailto:ouroboros@freelists.org). + +For day-to-day discussions, join our IRC chat: +[\#ouroboros](irc://irc.freenode.net/ouroboros). + +Contact us on twitter: @ODecentralize + +Contributing code +----------------- + +Contributions should be sent as patches to the mailing list, using your +real name and real e-mail address. + +The git repository contains three branches: + +- master: Contains the most stable version of Ouroboros. +- testing: Contains tested code but may still contain bugs. +- be: Contains untested but compiling code. + +New development is done against the 'be' branch of the git repository. +The testing and master branches take only bugfixes. + +Bug reporting +------------- + +Please report all bugs [here](/bugzilla). When reporting a bug, please +do the following: + +1. Provide a description of the bug. How did you get it and which + version of Ouroboros were you using? Which Operating System are you + on? +2. Provide as much technical information as possible (system logs, + debug traces, \...). +3. If possible, provide a minimal code example to reproduce the bug. +4. If you can provide a bugfix, provide it against the HEAD of the most + stable branch where the bug is present and send the patch to the + mailing list. + +Todo list +--------- + +We are currently looking for + +- Testing and bugfixing. +- Integration testing for the build system beyond the "make check" + unit tests. +- People that are interested in setting up some nodes to establish a + global testing layer. +- Non-blocking flow allocation: Allow specifying a {0, 0} timespec to + return immediately and use fevent() to know when the flow is ready + (or allocation failed). +- Asynchronous IPC over the UNIX sockets. For each command to the + IRMd, we create a UNIX socket, send the request and wait for the + response. This could be changed so that there is only a single UNIX + socket that is used for all messaging. This would simplify parallel + querying of the IPCPs and speed up flow allocation. The far-future + option is to ditch UNIX sockets and bootstrap Ouroboros local IPC + over itself. +- ECDH-AES encryption using libssl and/or libgcrypt. The goal is to + support both libraries so that we have a fallback should major bugs + be discovered in one of them. +- Customized packet serialization to remove the dependency on Google + Protocol Buffers. We like GPB, but it's not perfect. Importing + .proto files may give rise to multiple definitions and we found no + way to solve that. +- Caching for the DHT. +- Cross-compilation to OpenWRT (musl). +- Ported applications! If you want to add native Ouroboros support for + your applications, just let us know and we will help you out! diff --git a/content/about/philosophy.md b/content/about/philosophy.md new file mode 100644 index 0000000..556071f --- /dev/null +++ b/content/about/philosophy.md @@ -0,0 +1,56 @@ +--- +title: "Philosophy" +date: 2019-02-28T09:52:26+01:00 +publishDate: 2019-02-28T09:52:26+01:00 +author: "Dimitri Staessens" +images: [] +draft: false +tags: [] +--- + +
![](https://effectivesoftwaredesign.files.wordpress.com/2015/10/quote-if-10-years-from-now-when-you-are-doing-something-quick-and-dirty-you-suddenly-visualize-that-i-edsger-dijkstra-50997.jpg)
+ +During his entire scientific career, Edsger Dijkstra broke a lance for +the creed -- which he attributes to Tony Hoare -- that [*simplicity is +prerequisite for +reliability*](http://www.cs.utexas.edu/users/EWD/transcriptions/EWD06xx/EWD619.html). He +spent a lot of time and effort convincing his contemporaries in the +computing science community that *elegance is not a dispensable +luxury, but a matter of life and death*. Dijkstra was painfully aware +that [*simplicity is very hard to +achieve*](https://www.cs.utexas.edu/users/EWD/transcriptions/EWD08xx/EWD896.html) +and grossly underrated, even to the point that the academic and +economic reward systems work against any attempt do so: "*complexity +sells better*". With some computer engineers living by the motto *move +fast and break things*, Dijkstra would most definitely [not have been +happy](http://www.cs.utexas.edu/users/EWD/transcriptions/EWD12xx/EWD1213.html) +with much of the current state of affairs of computing science. While +he always will be considered one of the greatest computer scientists +that ever lived, his passionate message to diligently strive for +elegance seems to be all but erased from the collective consciousness +of engineers and computer scientists. Are we further away today from +computing's central challenge than we were [almost 20 years ago] +(https://www.cs.utexas.edu/users/EWD/transcriptions/EWD13xx/EWD1304.html)? + +
{{
}} +
+ +The current TCP/IP network stack has a long development history, and +its technical debt is leading to inefficiencies that allow hackers to +infiltrate networks with childish ease. In order to get to a +trustworthy and secure communications infrastructure, the structure of +the Internet needs to be drastically revised. The current protocols +have so much deprecated, unused and unnecessary bits and fields, that +trying to guard against every possible exploit is inefficient and +virtually impossible. + +Ouroboros is a new decentralized packet transport network for POSIX +operating systems that aims to accepts Edward Snowdens +[challenge](https://www.theatlantic.com/politics/archive/2014/05/edward-snowdens-other-motive-for-leaking/370068/): +to build a network infrastructure that will "*enforce a principle +whereby the only way the powerful may enjoy privacy is when it is the +same kind shared by the ordinary: one enforced by the laws of nature, +rather than the policies of man*." diff --git a/content/compopt.html b/content/compopt.html deleted file mode 100644 index 93ad1c4..0000000 --- a/content/compopt.html +++ /dev/null @@ -1,434 +0,0 @@ ---- -title: "Compilation options" -draft: false ---- - -

- Below is a list of the compile-time configuration options for - Ouroboros. These can be set using -

-
$ cmake -D<option>=<value> ..
-

or using

-
ccmake .
-

- Options will only show up in ccmake if they are relevant for - your system configuration. The default value for each option - is underlined. Boolean values will print as ON/OFF in - ccmake instead of True/False. -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
OptionDescriptionValues
Compilation options
CMAKE_BUILD_TYPE - Set the build type for Ouroboros. Debug builds will add some - extra logging. The debug build can further enable the - address sanitizer (ASan) thread sanitizer (TSan) and leak - sanitizer (LSan) options. - - Release, Debug, DebugASan, DebugTSan, DebugLSan -
CMAKE_INSTALL_PREFIX - Set a path prefix in order to install Ouroboros in a - sandboxed environment. Default is a system-wide install. - - <path> -
DISABLE_SWIG - Disable SWIG support. - - True, False -
Library options
DISABLE_FUSE - Disable FUSE support, removing the virtual filesystem under - <FUSE_PREFIX>. - - True, False -
FUSE_PREFIX - Set the path where the fuse system should be - mounted. Default is /tmp/ouroboros. - - <path> -
DISABLE_LIBGCRYPT - Disable support for using the libgcrypt library for - cryptographically secure random number generation and - hashing. - - True, False -
DISABLE_OPENSSL - Disable support for the libssl library for cryptographic - random number generation and hashing. - - True, False -
DISABLE_ROBUST_MUTEXES - Disable - - robust mutex - - support. Without robust mutex support, Ouroboros may lock up - if processes are killed using SIGKILL. - - True, False -
PTHREAD_COND_CLOCK - Set the - - clock type - - to use for timeouts for pthread condition variables. Default - on Linux/FreeBSD: CLOCK_MONOTONIC. Default on OS X: - CLOCK_REALTIME. - - <clock_id_t> -
Shared memory system options
SHM_PREFIX - Set a prefix for the shared memory filenames. The mandatory - leading - - slash - - is added by the build system. Default is "ouroboros". - - <size_t> -
SHM_BUFFER_SIZE - Set the maximum total number of packet blocks Ouroboros - can buffer at any point in time. Must be a power of 2. - - <size_t> -
SHM_RDRB_BLOCK_SIZE - Set the size of a packet block. Default: page size of the - system. - - <size_t> -
SHM_RDRB_MULTI-BLOCK - Allow packets that are larger than a single packet block. - - True, False -
DU_BUFF_HEADSPACE - Set the amount of space to allow for the addition of - protocol headers when a new packet buffer is passed to the - system. Default: 128 bytes. - - <size_t> -
DU_BUFF_TAILSPACE - Set the amount of space to allow for the addition of - protocol tail information (CRCs) when a new packet buffer - is passed to the system. Default: 32 bytes. - - <size_t> -
IRMd options
SYS_MAX_FLOWS - The maximum number of flows this Ouroboros system can - allocate. Default: 10240. - - <size_t> -
SOCKET_TIMEOUT - The IRMd sends commands to IPCPs over UNIX sockets. This - sets the timeout for such commands in milliseconds. Some - commands can be set independently. Default: 1000. - - <time_t> -
BOOTSTRAP_TIMEOUT - Timeout for the IRMd to wait for a response to a bootstrap - command from an IPCP in milliseconds. Default: 5000. - - <time_t> -
ENROLL_TIMEOUT - Timeout for the IRMd to wait for a response to an enroll - command from an IPCP in milliseconds. Default: 60000. - - <time_t> -
CONNECT_TIMEOUT - Timeout for the IRMd to wait for a response to a connect - command from an IPCP in milliseconds. Default: 5000. - - <time_t> -
REG_TIMEOUT - Timeout for the IRMd to wait for a response to a register - command from an IPCP in milliseconds. Default: 3000. - - <time_t> -
QUERY_TIMEOUT - Timeout for the IRMd to wait for a response to a query - command from an IPCP in milliseconds. Default: 3000. - - <time_t> -
IRMD_MIN_THREADS - The minimum number of threads in the threadpool the IRMd - keeps waiting for commands. Default: 8. - - <size_t> -
IRMD_ADD_THREADS - The number of threads the IRMd will create if the current - available threadpool is lower than - IRMD_MIN_THREADS. Default: 8. - - <size_t> -
IPCP options
DISABLE_RAPTOR - Disable support for the raptor NetFPGA implementation. - - True, False -
DISABLE_BPF - Disable support for the Berkeley Packet Filter device - interface for the Ethernet LLC layer. If no suitable - interface is found, the LLC layer will not be built. - - True, False -
DISABLE_NETMAP - Disable netmap - support for the Ethernet LLC layer. If no suitable interface - is found, the LLC layer will not be built. - - True, False -
DISABLE_RAW_SOCKETS - Disable raw sockets support for the Ethernet LLC layer. If - no suitable interface is found,the LLC layer will not be - built. - - True, False -
DISABLE_DDNS - Disable Dynamic Domain Name System support for the UDP - layer. - - True, False -
IPCP_SCHED_THR_MUL - The number of scheduler threads an IPCP runs per QoS - cube. Default is 2. - - <size_t> -
IPCP_QOS_CUBE_BE_PRIORITY - Priority for the best effort qos cube scheduler - thread. This is mapped to a system value. Scheduler - threads have at least half the system max priority value. - - 0..99 -
IPCP_QOS_CUBE_VIDEO_PRIORITY - Priority for the video qos cube scheduler thread. This is - mapped to a system value. Scheduler threads have at least - half the system max priority value. - - 0..90..99 -
IPCP_QOS_CUBE_VOICE_PRIORITY - Priority for the voice qos cube scheduler thread. This is - mapped to a system value. Scheduler threads have at least - half the system max priority value. - - 0..99 -
IPCP_FLOW_STATS - Enable statistics for the data transfer component. - - True, False -
PFT_SIZE - The forwarding table in the normal IPCP uses a - hashtable. This sets the size of this hash table. Default: 4096. - - <size_t> -
IPCP_MIN_THREADS - The minimum number of threads in the threadpool the IPCP - keeps waiting for commands. Default: 4. - - <size_t> -
IPCP_ADD_THREADS - The number of threads the IPCP will create if the current - available threadpool is lower than - IPCP_MIN_THREADS. Default:4. - - <size_t> -
diff --git a/content/contact/contribute.md b/content/contact/contribute.md new file mode 100644 index 0000000..0c2a2e6 --- /dev/null +++ b/content/contact/contribute.md @@ -0,0 +1,80 @@ +--- +title: "Contribute" +date: 2019-06-22 +draft: false +--- + +General discussion and support +------------------------------ + +For general discussion of Ouroboros, +[subscribe](https://www.freelists.org/list/ouroboros) to our mailing +list: [ouroboros@freelists.org](mailto:ouroboros@freelists.org). + +For day-to-day discussions, join our IRC chat: +[\#ouroboros](irc://irc.freenode.net/ouroboros). + +Contact us on twitter: @ODecentralize + +Contributing code +----------------- + +Contributions should be sent as patches to the mailing list, using your +real name and real e-mail address. + +The git repository contains three branches: + +- master: Contains the most stable version of Ouroboros. +- testing: Contains tested code but may still contain bugs. +- be: Contains untested but compiling code. + +New development is done against the 'be' branch of the git repository. +The testing and master branches take only bugfixes. + +Bug reporting +------------- + +Please report all bugs [here](/bugzilla). When reporting a bug, please +do the following: + +1. Provide a description of the bug. How did you get it and which + version of Ouroboros were you using? Which Operating System are you + on? +2. Provide as much technical information as possible (system logs, + debug traces, \...). +3. If possible, provide a minimal code example to reproduce the bug. +4. If you can provide a bugfix, provide it against the HEAD of the most + stable branch where the bug is present and send the patch to the + mailing list. + +Todo list +--------- + +We are currently looking for + +- Testing and bugfixing. +- Integration testing for the build system beyond the "make check" + unit tests. +- People that are interested in setting up some nodes to establish a + global testing layer. +- Non-blocking flow allocation: Allow specifying a {0, 0} timespec to + return immediately and use fevent() to know when the flow is ready + (or allocation failed). +- Asynchronous IPC over the UNIX sockets. For each command to the + IRMd, we create a UNIX socket, send the request and wait for the + response. This could be changed so that there is only a single UNIX + socket that is used for all messaging. This would simplify parallel + querying of the IPCPs and speed up flow allocation. The far-future + option is to ditch UNIX sockets and bootstrap Ouroboros local IPC + over itself. +- ECDH-AES encryption using libssl and/or libgcrypt. The goal is to + support both libraries so that we have a fallback should major bugs + be discovered in one of them. +- Customized packet serialization to remove the dependency on Google + Protocol Buffers. We like GPB, but it's not perfect. Importing + .proto files may give rise to multiple definitions and we found no + way to solve that. +- Caching for the DHT. +- Cross-compilation to OpenWRT (musl). +- Ported applications! If you want to add native Ouroboros support for + your applications, just let us know and we will help you out! diff --git a/content/contribute.md b/content/contribute.md deleted file mode 100644 index 4f1c8cc..0000000 --- a/content/contribute.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: "Contribute" -menu: "main" -draft: false -menu: - main: - weight: 20 ---- - -General discussion and support ------------------------------- - -For general discussion of Ouroboros, -[subscribe](https://www.freelists.org/list/ouroboros) to our mailing -list: [ouroboros@freelists.org](mailto:ouroboros@freelists.org). - -For day-to-day discussions, join our IRC chat: -[\#ouroboros](irc://irc.freenode.net/ouroboros). - -Contact us on twitter: @ODecentralize - -Contributing code ------------------ - -Contributions should be sent as patches to the mailing list, using your -real name and real e-mail address. - -The git repository contains three branches: - -- master: Contains the most stable version of Ouroboros. -- testing: Contains tested code but may still contain bugs. -- be: Contains untested but compiling code. - -New development is done against the 'be' branch of the git repository. -The testing and master branches take only bugfixes. - -Bug reporting -------------- - -Please report all bugs [here](/bugzilla). When reporting a bug, please -do the following: - -1. Provide a description of the bug. How did you get it and which - version of Ouroboros were you using? Which Operating System are you - on? -2. Provide as much technical information as possible (system logs, - debug traces, \...). -3. If possible, provide a minimal code example to reproduce the bug. -4. If you can provide a bugfix, provide it against the HEAD of the most - stable branch where the bug is present and send the patch to the - mailing list. - -Todo list ---------- - -We are currently looking for - -- Testing and bugfixing. -- Integration testing for the build system beyond the "make check" - unit tests. -- People that are interested in setting up some nodes to establish a - global testing layer. -- Non-blocking flow allocation: Allow specifying a {0, 0} timespec to - return immediately and use fevent() to know when the flow is ready - (or allocation failed). -- Asynchronous IPC over the UNIX sockets. For each command to the - IRMd, we create a UNIX socket, send the request and wait for the - response. This could be changed so that there is only a single UNIX - socket that is used for all messaging. This would simplify parallel - querying of the IPCPs and speed up flow allocation. The far-future - option is to ditch UNIX sockets and bootstrap Ouroboros local IPC - over itself. -- ECDH-AES encryption using libssl and/or libgcrypt. The goal is to - support both libraries so that we have a fallback should major bugs - be discovered in one of them. -- Customized packet serialization to remove the dependency on Google - Protocol Buffers. We like GPB, but it's not perfect. Importing - .proto files may give rise to multiple definitions and we found no - way to solve that. -- Caching for the DHT. -- Cross-compilation to OpenWRT (musl). -- Ported applications! If you want to add native Ouroboros support for - your applications, just let us know and we will help you out! diff --git a/content/dev-tut-1.md b/content/dev-tut-1.md deleted file mode 100644 index ceac8b6..0000000 --- a/content/dev-tut-1.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: "Developer tutorial 1: Writing your first Ouroboros C program" -draft: false ---- - -This tutorial will guide you to write your first ouroboros program. It -will use the basic Ouroboros IPC Application Programming Interface. It -will has a client and a server that send a small message from the client -to the server. - -We will explain how to connect two applications. The server application -uses the flow_accept() call to accept incoming connections and the -client uses the flow_alloc() call to connect to the server. The -flow_accept and flow_alloc call have the following definitions: - -``` -int flow_accept(qosspec_t * qs, const struct timespec * timeo); -int flow_alloc(const char * dst, qosspec_t * qs, const struct -timespec * timeo); -``` - -On the server side, the flow_accept() call is a blocking call that will -wait for an incoming flow from a client. On the client side, the -flow_alloc() call is a blocking call that allocates a flow to *dst*. -Both calls return an non-negative integer number describing a "flow -descriptor", which is very similar to a file descriptor. On error, they -will return a negative error code. (See the [man -page](/man/man3/flow_alloc.html) for all details). If the *timeo* -parameter supplied is NULL, the calls will block indefinitely, otherwise -flow_alloc() will return -ETIMEDOUT when the time interval provided by -*timeo* expires. We are working on implementing non-blocking versions if -the provided *timeo* is 0. - -After the flow is allocated, the flow_read() and flow_write() calls -are used to read from the flow descriptor. They operate just like the -read() and write() POSIX calls. The default behaviour is that these -calls will block. To release the resource, the flow can be deallocated -using flow_dealloc. - -``` -ssize_t flow_write(int fd, const void * buf, size_t count); -ssize_t flow_read(int fd, void * buf, size_t count); int -flow_dealloc(int fd); -``` - -So a very simple application would just need a couple of lines of code -for both the server and the client: - -``` -/* server side */ -char msg[BUF_LEN]; -int fd = flow_accept(NULL, NULL); -flow_read(fd, msg, BUF_LEN); -flow_dealloc(fd); - -/* client side */ -char * msg = "message"; -int fd = flow_alloc("server", NULL, NULL); -flow_write(fd, msg, strlen(msg)); -flow_dealloc(fd); -``` - -The full code for an example is the -[oecho](/cgit/ouroboros/tree/src/tools/oecho/oecho.c) -application in the tools directory. - -To compile your C program from the command line, you have to link --lourobos-dev. For instance, in the Ouroboros repository, you can do - -``` -cd src/tools/oecho -gcc -louroboros-dev oecho.c -o oecho -``` \ No newline at end of file diff --git a/content/docs/_index.md b/content/docs/_index.md new file mode 100644 index 0000000..f2a842a --- /dev/null +++ b/content/docs/_index.md @@ -0,0 +1,6 @@ +--- +title: Documentation +date: 2019-06-22 +type: page +draft: false +--- diff --git a/content/docs/compopt.html b/content/docs/compopt.html new file mode 100644 index 0000000..4c4459c --- /dev/null +++ b/content/docs/compopt.html @@ -0,0 +1,435 @@ +--- +title: "Compilation options" +date: 2019-06-22 +draft: false +--- + +

+ Below is a list of the compile-time configuration options for + Ouroboros. These can be set using +

+
$ cmake -D<option>=<value> ..
+

or using

+
ccmake .
+

+ Options will only show up in ccmake if they are relevant for + your system configuration. The default value for each option + is underlined. Boolean values will print as ON/OFF in + ccmake instead of True/False. +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OptionDescriptionValues
Compilation options
CMAKE_BUILD_TYPE + Set the build type for Ouroboros. Debug builds will add some + extra logging. The debug build can further enable the + address sanitizer (ASan) thread sanitizer (TSan) and leak + sanitizer (LSan) options. + + Release, Debug, DebugASan, DebugTSan, DebugLSan +
CMAKE_INSTALL_PREFIX + Set a path prefix in order to install Ouroboros in a + sandboxed environment. Default is a system-wide install. + + <path> +
DISABLE_SWIG + Disable SWIG support. + + True, False +
Library options
DISABLE_FUSE + Disable FUSE support, removing the virtual filesystem under + <FUSE_PREFIX>. + + True, False +
FUSE_PREFIX + Set the path where the fuse system should be + mounted. Default is /tmp/ouroboros. + + <path> +
DISABLE_LIBGCRYPT + Disable support for using the libgcrypt library for + cryptographically secure random number generation and + hashing. + + True, False +
DISABLE_OPENSSL + Disable support for the libssl library for cryptographic + random number generation and hashing. + + True, False +
DISABLE_ROBUST_MUTEXES + Disable + + robust mutex + + support. Without robust mutex support, Ouroboros may lock up + if processes are killed using SIGKILL. + + True, False +
PTHREAD_COND_CLOCK + Set the + + clock type + + to use for timeouts for pthread condition variables. Default + on Linux/FreeBSD: CLOCK_MONOTONIC. Default on OS X: + CLOCK_REALTIME. + + <clock_id_t> +
Shared memory system options
SHM_PREFIX + Set a prefix for the shared memory filenames. The mandatory + leading + + slash + + is added by the build system. Default is "ouroboros". + + <size_t> +
SHM_BUFFER_SIZE + Set the maximum total number of packet blocks Ouroboros + can buffer at any point in time. Must be a power of 2. + + <size_t> +
SHM_RDRB_BLOCK_SIZE + Set the size of a packet block. Default: page size of the + system. + + <size_t> +
SHM_RDRB_MULTI-BLOCK + Allow packets that are larger than a single packet block. + + True, False +
DU_BUFF_HEADSPACE + Set the amount of space to allow for the addition of + protocol headers when a new packet buffer is passed to the + system. Default: 128 bytes. + + <size_t> +
DU_BUFF_TAILSPACE + Set the amount of space to allow for the addition of + protocol tail information (CRCs) when a new packet buffer + is passed to the system. Default: 32 bytes. + + <size_t> +
IRMd options
SYS_MAX_FLOWS + The maximum number of flows this Ouroboros system can + allocate. Default: 10240. + + <size_t> +
SOCKET_TIMEOUT + The IRMd sends commands to IPCPs over UNIX sockets. This + sets the timeout for such commands in milliseconds. Some + commands can be set independently. Default: 1000. + + <time_t> +
BOOTSTRAP_TIMEOUT + Timeout for the IRMd to wait for a response to a bootstrap + command from an IPCP in milliseconds. Default: 5000. + + <time_t> +
ENROLL_TIMEOUT + Timeout for the IRMd to wait for a response to an enroll + command from an IPCP in milliseconds. Default: 60000. + + <time_t> +
CONNECT_TIMEOUT + Timeout for the IRMd to wait for a response to a connect + command from an IPCP in milliseconds. Default: 5000. + + <time_t> +
REG_TIMEOUT + Timeout for the IRMd to wait for a response to a register + command from an IPCP in milliseconds. Default: 3000. + + <time_t> +
QUERY_TIMEOUT + Timeout for the IRMd to wait for a response to a query + command from an IPCP in milliseconds. Default: 3000. + + <time_t> +
IRMD_MIN_THREADS + The minimum number of threads in the threadpool the IRMd + keeps waiting for commands. Default: 8. + + <size_t> +
IRMD_ADD_THREADS + The number of threads the IRMd will create if the current + available threadpool is lower than + IRMD_MIN_THREADS. Default: 8. + + <size_t> +
IPCP options
DISABLE_RAPTOR + Disable support for the raptor NetFPGA implementation. + + True, False +
DISABLE_BPF + Disable support for the Berkeley Packet Filter device + interface for the Ethernet LLC layer. If no suitable + interface is found, the LLC layer will not be built. + + True, False +
DISABLE_NETMAP + Disable netmap + support for the Ethernet LLC layer. If no suitable interface + is found, the LLC layer will not be built. + + True, False +
DISABLE_RAW_SOCKETS + Disable raw sockets support for the Ethernet LLC layer. If + no suitable interface is found,the LLC layer will not be + built. + + True, False +
DISABLE_DDNS + Disable Dynamic Domain Name System support for the UDP + layer. + + True, False +
IPCP_SCHED_THR_MUL + The number of scheduler threads an IPCP runs per QoS + cube. Default is 2. + + <size_t> +
IPCP_QOS_CUBE_BE_PRIORITY + Priority for the best effort qos cube scheduler + thread. This is mapped to a system value. Scheduler + threads have at least half the system max priority value. + + 0..99 +
IPCP_QOS_CUBE_VIDEO_PRIORITY + Priority for the video qos cube scheduler thread. This is + mapped to a system value. Scheduler threads have at least + half the system max priority value. + + 0..90..99 +
IPCP_QOS_CUBE_VOICE_PRIORITY + Priority for the voice qos cube scheduler thread. This is + mapped to a system value. Scheduler threads have at least + half the system max priority value. + + 0..99 +
IPCP_FLOW_STATS + Enable statistics for the data transfer component. + + True, False +
PFT_SIZE + The forwarding table in the normal IPCP uses a + hashtable. This sets the size of this hash table. Default: 4096. + + <size_t> +
IPCP_MIN_THREADS + The minimum number of threads in the threadpool the IPCP + keeps waiting for commands. Default: 4. + + <size_t> +
IPCP_ADD_THREADS + The number of threads the IPCP will create if the current + available threadpool is lower than + IPCP_MIN_THREADS. Default:4. + + <size_t> +
diff --git a/content/docs/development/_index.md b/content/docs/development/_index.md new file mode 100644 index 0000000..0a5257f --- /dev/null +++ b/content/docs/development/_index.md @@ -0,0 +1,6 @@ +--- +title: Development +date: 2019-06-22 +#description: Ouroboros development blog +draft: false +--- diff --git a/content/docs/documentation.md b/content/docs/documentation.md new file mode 100644 index 0000000..f48e03c --- /dev/null +++ b/content/docs/documentation.md @@ -0,0 +1,41 @@ +--- +title: "Documentation" +date: 2019-06-22 +type: page +draft: false +--- + +# Getting started + +* [Requirements](/requirements/) +* [Download Ouroboros](/download/) +* [Installing Ouroboros](/install/) +* [Compilation options](/compopt/) + +# User tutorials + +These tutorials will be kept up-to-date for the latest version of +Ouroboros. Check the version that is installed on your system using: + +``` +$ irmd --version +``` + +The output shown in the tutorials uses a [*debug*](/compopt) build +of Ouroboros, with FUSE installed and IPCP\_FLOW\_STATS enabled to show +some additional details of what is happening. + +* [Tutorial 1: Local test](/tutorial-1/) +* [Tutorial 2: Adding a layer](/tutorial-2/) +* [Tutorial 3: IPCP statistics](/tutorial-3/) +* [Tutorial 4: Connecting two machines over Ethernet](/tutorial-4/) + +# Developer tutorials + +* [Developer tutorial 1: Writing your first Ouroboros C program](/dev-tut-1/) + +# Extra info + +* [Manual pages](/manuals/) +* [Frequently Asked Questions (FAQ)](/faq/) +* [Performance tests](/performance/) diff --git a/content/docs/faq.md b/content/docs/faq.md new file mode 100644 index 0000000..b3ac687 --- /dev/null +++ b/content/docs/faq.md @@ -0,0 +1,122 @@ +--- +title: "Frequently Asked Questions (FAQ)" +date: 2019-06-22 +draft: false +--- + +Got a question that is not listed here? Just pop it on our IRC channel +or mailing list and we will be happy to answer it! + +[What is Ouroboros?](#what)\ +[Is Ouroboros the same as the Recursive InterNetwork Architecture +(RINA)?](#rina)\ +[How can I use Ouroboros right now?](#deploy)\ +[What are the benefits of Ouroboros?](#benefits)\ +[How do you manage the namespaces?](#namespaces)\ + +### What is Ouroboros? + +Ouroboros is a packet-based IPC mechanism. It allows programs to +communicate by sending messages, and provides a very simple API to do +so. At its core, it's an implementation of a recursive network +architecture. It can run next to, or over, common network technologies +such as Ethernet and IP. + +[[back to top](#top)] + +### Is Ouroboros the same as the Recursive InterNetwork Architecture (RINA)? + +No. Ouroboros is a recursive network, and is born as part of our +research into RINA networks. Without the pioneering work of John Day and +others on RINA, Ouroboros would not exist. We consider the RINA model an +elegant way to think about distributed applications and networks. + +However, there are major architectural differences between Ouroboros and +RINA. The most important difference is the location of the "transport +functions" which are related to connection management, such as +fragmentation, packet ordering and automated repeat request (ARQ). RINA +places these functions in special applications called IPCPs that form +layers known as Distributed IPC Facilities (DIFs) as part of a protocol +called EFCP. This allows a RINA DIF to provide an *IPC service* to the +layer on top. + +Ouroboros has those functions in *every* application. The benefit of +this approach is that it is possible to multi-home applications in +different networks, and still have a reliable connection. It is also +more resilient since every connection is - at least in theory - +recoverable unless the application itself crashes. So, Ouroboros IPCPs +form a layer that only provides *IPC resources*. The application does +its connection management, which is implemented in the Ouroboros +library. This architectural difference impact the components and +protocols that underly the network, which are all different from RINA. + +This change has a major impact on other components and protocols. We are +preparing a research paper on Ouroboros that will contain all these +details and more. + +[[back to top](#top)] + +### How can I use Ouroboros right now? + +At this point, Ouroboros is a useable prototype. You can use it to build +small deployments for personal use. There is no global Ouroboros network +yet, but if you're interested in helping us set that up, contact us on +our channel or mailing list. + +[[back to top](#top)] + +### What are the benefits of Ouroboros? + +We get this question a lot, and there is no single simple answer to +it. Its benefits are those of a RINA network and more. In general, if +two systems provide the same service, simpler systems tend to be the +more robust and reliable ones. This is why we designed Ouroboros the +way we did. It has a bunch of small improvements over current networks +which may not look like anything game-changing by themselves, but do +add up. The reaction we usually get when demonstrating Ouroboros, is +that it makes everything really really easy. + +Some benefits are improved anonymity as we do not send source addresses +in our data transfer packets. This also prevents all kinds of swerve and +amplification attacks. The packet structures are not fixed (as the +number of layers is not fixed), so there is no fast way to decode a +packet when captured "raw" on the wire. It also makes Deep Packet +Inspection harder to do. By attaching names to data transfer components +(so there can be multiple of these to form an "address"), we can +significantly reduce routing table sizes. + +The API is very simple and universal, so we can run applications as +close to the hardware as possible to reduce latency. Currently it +requires quite some work from the application programmer to create +programs that run directly over Ethernet or over UDP or over TCP. With +the Ouroboros API, the application doesn't need to be changed. Even if +somebody comes up with a different transmission technology, the +application will never need to be modified to run over it. + +Ouroboros also makes it easy to run different instances of the same +application on the same server and load-balance them. In IP networks +this requires at least some NAT trickery (since each application is tied +to an interface:port). For instance, it takes no effort at all to run +three different webserver implementations and load-balance flows between +them for resiliency and seamless attack mitigation. + +The architecture still needs to be evaluated at scale. Ultimately, the +only way to get the numbers, are to get a large (pre-)production +deployment with real users. + +[[back to top](#top)] + +### How do you manage the namespaces? + +Ouroboros uses names that are attached to programs and processes. The +layer API always uses hashes and the network maps hashes to addresses +for location. This function is similar to a DNS lookup. The current +implementation uses a DHT for that function in the ipcp-normal (the +ipcp-udp uses a DynDNS server, the eth-llc and eth-dix use a local +database with broadcast queries). + +But this leaves the question how we assign names. Currently this is +ad-hoc, but eventually we will need an organized way for a global +namespace so that application names are unique. If we want to avoid a +central authority like ICANN, a distributed ledger would be a viable +technology to implement this, similar to, for instance, namecoin. diff --git a/content/docs/manuals.md b/content/docs/manuals.md new file mode 100644 index 0000000..4ce3bce --- /dev/null +++ b/content/docs/manuals.md @@ -0,0 +1,18 @@ +--- +title: "Manuals" +date: 2019-06-22 +draft: false +--- + +These are the man pages for ouroboros. If ouroboros is installed on your +system, you can also access them using "man". + +For general use of Ouroboros, refer to the [Ouroboros User +Manual](/man/man8/ouroboros.8.html). + +For use of the API, refer to the [Ouroboros Programmer's +Manual](/man/man3/flow_alloc.3.html). + +The man section also contains a +[tutorial](man/man7/ouroboros-tutorial.7.html) and a +[glossary](man/man7/ouroboros-glossary.7.html). diff --git a/content/docs/performance.md b/content/docs/performance.md new file mode 100644 index 0000000..5cd2dc0 --- /dev/null +++ b/content/docs/performance.md @@ -0,0 +1,74 @@ +--- +title: "Performance tests" +date: 2019-06-22 +draft: false +--- + +Below you will find some measurements on the performance of Ouroboros. + +### Local IPC performance test + +This test uses the *oping* tool to measure round trip time. This tools +generates traffic from a single thread. The server has a single thread +that handles ping requests and sends responses. + +``` +$ oping -n oping -i 0 -s +``` + +The figure below shows the round-trip-time (rtt) in milliseconds (ms) +for IPC over a local layer for different packet sizes, measured on an +Intel Core i7 4500U (2 cores @ 2.4GHz). For small payloads (up to 1500 +bytes), the rtt is quite stable at around 30 µs. This will mostly depend +on CPU frequency and to a lesser extent the OS scheduler. + +![Ouroboros local rtt](/images/avgrttlocal.png) + +This test uses the *ocbr* tool to measure goodput between a sender and +receiver. The sender generates traffic from a single thread. The +receiver handles traffic from a single thread. The performance will +heavily depend on your system's memory layout (cache sizes etc). This +test was run on a Dell XPS13 9333 (2013 model). + +``` +$ ocbr -n ocbr -f -s +``` + +![Ouroboros local pps](/images/throughputlocalpps.png) + +The goodput (Mb/s) is shown below: + +![ouroboros local mbits](/images/goodputlocalmbits.png) + +### Ethernet + Normal test + +This connects 2 machines over a Gb LAN using the eth-dix and a normal +layer. The oping server is registered in the dix as oping.dix and in the +normal as oping.normal. The machines (dual-socket Intel Xeon E5520) are +connected over a non-blocking switch. + +Latency test: + +ICMP ping: + +``` +--- 192.168.1.2 ping statistics --- +1000 packets transmitted, 1000 received, 0% packet loss, time 65ms +rtt min/avg/max/mdev = 0.046/0.049/0.083/0.002 ms, ipg/ewma 0.065/0.049 ms +``` + +oping over eth-dix: + +``` +--- oping.dix ping statistics --- +1000 SDUs transmitted, 1000 received, 0% packet loss, time: 66.142 ms +rtt min/avg/max/mdev = 0.098/0.112/0.290/0.010 ms +``` + +oping over eth-normal: + +``` +--- oping.normal ping statistics --- +1000 SDUs transmitted, 1000 received, 0% packet loss, time: 71.532 ms +rtt min/avg/max/mdev = 0.143/0.180/0.373/0.020 ms +``` \ No newline at end of file diff --git a/content/docs/quickstart.md b/content/docs/quickstart.md new file mode 100644 index 0000000..a1bb44b --- /dev/null +++ b/content/docs/quickstart.md @@ -0,0 +1,11 @@ +--- +title: "Quick Start" +linktitle: "Quick Start" +date: 2019-06-22 +type: page +draft: false +description: "Quick Start Guide" +--- + + +This quickstart guide is under construction. \ No newline at end of file diff --git a/content/docs/tutorials/_index.md b/content/docs/tutorials/_index.md new file mode 100644 index 0000000..b35d0b8 --- /dev/null +++ b/content/docs/tutorials/_index.md @@ -0,0 +1,5 @@ +--- +title: "Ouroboros Tutorials" +date: 2019-06-22 +draft: false +--- \ No newline at end of file diff --git a/content/docs/tutorials/dev-tut-1.md b/content/docs/tutorials/dev-tut-1.md new file mode 100644 index 0000000..ceac8b6 --- /dev/null +++ b/content/docs/tutorials/dev-tut-1.md @@ -0,0 +1,73 @@ +--- +title: "Developer tutorial 1: Writing your first Ouroboros C program" +draft: false +--- + +This tutorial will guide you to write your first ouroboros program. It +will use the basic Ouroboros IPC Application Programming Interface. It +will has a client and a server that send a small message from the client +to the server. + +We will explain how to connect two applications. The server application +uses the flow_accept() call to accept incoming connections and the +client uses the flow_alloc() call to connect to the server. The +flow_accept and flow_alloc call have the following definitions: + +``` +int flow_accept(qosspec_t * qs, const struct timespec * timeo); +int flow_alloc(const char * dst, qosspec_t * qs, const struct +timespec * timeo); +``` + +On the server side, the flow_accept() call is a blocking call that will +wait for an incoming flow from a client. On the client side, the +flow_alloc() call is a blocking call that allocates a flow to *dst*. +Both calls return an non-negative integer number describing a "flow +descriptor", which is very similar to a file descriptor. On error, they +will return a negative error code. (See the [man +page](/man/man3/flow_alloc.html) for all details). If the *timeo* +parameter supplied is NULL, the calls will block indefinitely, otherwise +flow_alloc() will return -ETIMEDOUT when the time interval provided by +*timeo* expires. We are working on implementing non-blocking versions if +the provided *timeo* is 0. + +After the flow is allocated, the flow_read() and flow_write() calls +are used to read from the flow descriptor. They operate just like the +read() and write() POSIX calls. The default behaviour is that these +calls will block. To release the resource, the flow can be deallocated +using flow_dealloc. + +``` +ssize_t flow_write(int fd, const void * buf, size_t count); +ssize_t flow_read(int fd, void * buf, size_t count); int +flow_dealloc(int fd); +``` + +So a very simple application would just need a couple of lines of code +for both the server and the client: + +``` +/* server side */ +char msg[BUF_LEN]; +int fd = flow_accept(NULL, NULL); +flow_read(fd, msg, BUF_LEN); +flow_dealloc(fd); + +/* client side */ +char * msg = "message"; +int fd = flow_alloc("server", NULL, NULL); +flow_write(fd, msg, strlen(msg)); +flow_dealloc(fd); +``` + +The full code for an example is the +[oecho](/cgit/ouroboros/tree/src/tools/oecho/oecho.c) +application in the tools directory. + +To compile your C program from the command line, you have to link +-lourobos-dev. For instance, in the Ouroboros repository, you can do + +``` +cd src/tools/oecho +gcc -louroboros-dev oecho.c -o oecho +``` \ No newline at end of file diff --git a/content/docs/tutorials/tutorial-1.md b/content/docs/tutorials/tutorial-1.md new file mode 100644 index 0000000..d1ac3c6 --- /dev/null +++ b/content/docs/tutorials/tutorial-1.md @@ -0,0 +1,153 @@ +--- +title: "Tutorial 1: local test" +draft: false +--- + +This tutorial runs through the basics of Ouroboros. Here, we will see +the general use of two core components of Ouroboros, the IPC Resource +Manager daemon (IRMd) and an IPC Process (IPCP). + +![Tutorial 1 setup](/images/ouroboros_tut1_overview.png) + +We will start the IRMd, create a local IPCP, start a ping server and +connect a client. This will involve **binding (1)** that server to a +name and **registering (2)** that name into the local layer. After that +the client will be able to **allocate a flow (3)** to that name for +which the server will respond. + +We recommend to open 3 terminal windows for this tutorial. In the first +window, start the IRMd (as a superuser) in stdout mode. The output shows +the process id (pid) of the IRMd, which will be different on your +machine. + +``` +$ sudo irmd --stdout +==02301== irmd(II): Ouroboros IPC Resource Manager daemon started\... +``` + +The type of IPCP we will create is a "local" IPCP. The local IPCP is a +kind of loopback interface that is native to Ouroboros. It implements +all the functions that the Ouroboros API provides, but only for a local +scope. The IPCP create function will instantiate a new local IPC +process, which in our case has pid 2324. The "ipcp create" command +merely creates the IPCP. At this point it is not a part of a layer. We +will also need to bootstrap this IPCP in a layer, we will name it +"local_layer". As a shortcut, the bootstrap command will +automatically create an IPCP if no IPCP by than name exists, so in this +case, the IPCP create command is optional. In the second terminal, enter +the commands: + +``` +$ irm ipcp create type local name local_ipcp +$ irm ipcp bootstrap type local name local_ipcp layer local_layer +``` + +The IRMd and ipcpd output in the first terminal reads: + +``` +==02301== irmd(II): Created IPCP 2324. +==02324== ipcpd-local(II): Bootstrapped local IPCP with pid 2324. +==02301== irmd(II): Bootstrapped IPCP 2324 in layer local_layer. +``` + +From the third terminal window, let's start our oping application in +server mode ("oping --help" shows oping command line parameters): + +``` +$ oping --listen +Ouroboros ping server started. +``` + +The IRMd will notice that an oping server with pid 10539 has started: + +``` +==02301== irmd(DB): New instance (10539) of oping added. +==02301== irmd(DB): This process accepts flows for: +``` + +The server application is not yet reachable by clients. Next we will +bind the server to a name and register that name in the +"local_layer". The name for the server can be chosen at will, let's +take "oping_server". In the second terminal window, execute: + +``` +$ irm bind proc 2337 name oping_server +$ irm register name oping_server layer local_layer +``` + +The IRMd and IPCPd in terminal one will now acknowledge that the name is +bound and registered: + +``` +==02301== irmd(II): Bound process 2337 to name oping_server. +==02324== ipcpd-local(II): Registered 4721372d. +==02301== irmd(II): Registered oping_server in local_layer as +4721372d. +``` + +Ouroboros registers name not in plaintext but using a (configurable) +hashing algorithm. The default hash is a 256 bit SHA3 hash. The output +in the logs is truncated to the first 4 bytes in a HEX notation. + +Now that we have bound and registered our server, we can connect from +the client. In the second terminal window, start an oping client with +destination oping_server and it will begin pinging: + +``` +$ oping -n oping_server -c 5 +Pinging oping_server with 64 bytes of data: + +64 bytes from oping_server: seq=0 time=0.694 ms +64 bytes from oping_server: seq=1 time=0.364 ms +64 bytes from oping_server: seq=2 time=0.190 ms +64 bytes from oping_server: seq=3 time=0.269 ms +64 bytes from oping_server: seq=4 time=0.351 ms + +--- oping_server ping statistics --- +5 SDUs transmitted, 5 received, 0% packet loss, time: 5001.744 ms +rtt min/avg/max/mdev = 0.190/0.374/0.694/0.192 ms +``` + +The server will acknowledge that it has a new flow connected on flow +descriptor 64, which will time out a few seconds after the oping client +stops sending: + +``` +New flow 64. +Flow 64 timed out. +``` + +The IRMd and IPCP logs provide some additional output detailing the flow +allocation process: + +``` +==02324== ipcpd-local(DB): Allocating flow to 4721372d on fd 64. +==02301== irmd(DB): Flow req arrived from IPCP 2324 for 4721372d. +==02301== irmd(II): Flow request arrived for oping_server. +==02324== ipcpd-local(II): Pending local allocation request on fd 64. +==02301== irmd(II): Flow on port_id 0 allocated. +==02324== ipcpd-local(II): Flow allocation completed, fds (64, 65). +==02301== irmd(II): Flow on port_id 1 allocated. +==02301== irmd(DB): New instance (2337) of oping added. +==02301== irmd(DB): This process accepts flows for: +==02301== irmd(DB): oping_server +``` + +First, the IPCPd shows that it will allocate a flow towards a +destination hash "4721372d" (truncated). The IRMd logs that IPCPd 2324 +(our local IPCPd) requests a flow towards any process that is listening +for "4721372d", and resolves it to "oping_server", as that is a +process that is bound to that name. At this point, the local IPCPd has a +pending flow on the client side. Since this is the first port_id in the +system, it has port_id 0. The server will accept the flow and the other +end of the flow gets port_id 1. The local IPCPd sees that the flow +allocation is completed. Internally it sees the endpoints as flow +descriptors 64 and 65 which map to port_id 0 and port_id 1. The IPCP +cannot directly access port_ids, they are assigned and managed by the +IRMd. After it has accepted the flow, the oping server enters +flow_accept() again. The IRMd notices the instance and reports that it +accepts flows for "oping_server". + +This concludes this first short tutorial. All running processes can be +terminated by issuing a Ctrl-C command in their respective terminals or +you can continue with the next tutorial. diff --git a/content/docs/tutorials/tutorial-2.md b/content/docs/tutorials/tutorial-2.md new file mode 100644 index 0000000..392a659 --- /dev/null +++ b/content/docs/tutorials/tutorial-2.md @@ -0,0 +1,297 @@ +--- +title: "Tutorial 2: Adding a layer" +draft: false +--- + +In this tutorial we will add a *normal layer* on top of the local layer. +Make sure you have a local layer running. The network will look like +this: + +![Tutorial 2 setup](/images/ouroboros_tut2_overview.png) + +Let's start adding the normal layer. We will first bootstrap a normal +IPCP, with name "normal_1" into the "normal_layer" (using default +options). In terminal 2, type: + +``` +$ irm ipcp bootstrap type normal name normal_1 layer normal_layer +``` + +The IRMd and IPCP will report the bootstrap: + +``` +==02301== irmd(II): Created IPCP 4363. +==04363== normal-ipcp(DB): IPCP got address 465922905. +==04363== directory(DB): Bootstrapping directory. +==04363== directory(II): Directory bootstrapped. +==04363== normal-ipcp(DB): Bootstrapped in layer normal_layer. +==02301== irmd(II): Bootstrapped IPCP 4363 in layer normal_layer. +==02301== irmd(DB): New instance (4363) of ipcpd-normal added. +==02301== irmd(DB): This process accepts flows for: +``` + +The new IPCP has pid 4363. It also generated an *address* for itself, +465922905. Then it bootstrapped a directory. The directory will map +registered names to an address or a set of addresses. In the normal DHT +the current default (and only option) for the directory is a Distributed +Hash Table (DHT) based on the Kademlia protocol, similar to the DHT used +in the mainline BitTorrent as specified by the +[BEP5](http://www.bittorrent.org/beps/bep_0005.html). This DHT will use +the hash algorithm specified for the layer (default is 256-bit SHA3) +instead of the SHA1 algorithm used by Kademlia. Just like any +Ouroboros-capable process, the IRMd will notice a new instance of the +normal IPCP. We will now bind this IPCP to some names and register them +in the local_layer: + +``` +$ irm bind ipcp normal_1 name normal_1 +$ irm bind ipcp normal_1 name normal_layer +$ irm register name normal_1 layer local_layer +$ irm register name normal_layer layer local_layer +``` + +The "irm bind ipcp" call is a shorthand for the "irm bind proc" call +that uses the ipcp name instead of the pid for convenience. Note that +we have bound the same process to two different names. This is to +allow enrollment using a layer name (anycast) instead of a specific +ipcp_name. The IRMd and local IPCP should log the following, just as +in tutorial 1: + +``` +==02301== irmd(II): Bound process 4363 to name normal_1. +==02301== irmd(II): Bound process 4363 to name normal_layer. +==02324== ipcpd-local(II): Registered e9504761. +==02301== irmd(II): Registered normal_1 in local_layer as e9504761. +==02324== ipcpd-local(II): Registered f40ee0f0. +==02301== irmd(II): Registered normal_layer in local_layer as +f40ee0f0. +``` + +We will now create a second IPCP and enroll it in the normal_layer. +Like the "irm ipcp bootstrap command", the "irm ipcp enroll" command +will create the IPCP if an IPCP with that name does not yet exist in the +system. An "autobind" option is a shorthand for binding the IPCP to +the IPCP name and the layer name. + +``` +$ irm ipcp enroll name normal_2 layer normal_layer autobind +``` + +The activity is shown by the output of the IRMd and the IPCPs. Let's +break it down. First, the new normal IPCP is created and bound to its +process name: + +``` +==02301== irmd(II): Created IPCP 13569. +==02301== irmd(II): Bound process 13569 to name normal_2. +``` + +Next, that IPCP will *enroll* with an existing member of the layer +"normal_layer". To do that it first allocates a flow over the local +layer: + +``` +==02324== ipcpd-local(DB): Allocating flow to f40ee0f0 on fd 64. +==02301== irmd(DB): Flow req arrived from IPCP 2324 for f40ee0f0. +==02301== irmd(II): Flow request arrived for normal_layer. +==02324== ipcpd-local(II): Pending local allocation request on fd 64. +==02301== irmd(II): Flow on port_id 0 allocated. +==02324== ipcpd-local(II): Flow allocation completed, fds (64, 65). +==02301== irmd(II): Flow on port_id 1 allocated. +``` + +Over this flow, it connects to the enrollment component of the normal_1 +IPCP. It sends some information that it will speak the Ouroboros +Enrollment Protocol (OEP). Then it will receive boot information from +normal_1 (the configuration of the layer that was provided when we +bootstrapped the normal_1 process), such as the hash it will use for +the directory. It signals normal_1 that it got the information so that +normal_1 knows this was successful. It will also get an address. After +enrollment is complete, both normal_1 and normal_2 will be ready to +accept incoming flows: + +``` +==13569== connection-manager(DB): Sending cacep info for protocol OEP to +fd 64. +==13569== enrollment(DB): Getting boot information. +==02301== irmd(DB): New instance (4363) of ipcpd-normal added. +==02301== irmd(DB): This process accepts flows for: +==02301== irmd(DB): normal_layer +==02301== irmd(DB): normal_1 +==04363== enrollment(DB): Enrolling a new neighbor. +==04363== enrollment(DB): Sending enrollment info (49 bytes). +==13569== enrollment(DB): Received enrollment info (49 bytes). +==13569== normal-ipcp(DB): IPCP got address 416743497. +==04363== enrollment(DB): Neighbor enrollment successful. +==02301== irmd(DB): New instance (13569) of ipcpd-normal added. +==02301== irmd(DB): This process accepts flows for: +==02301== irmd(DB): normal_2 +``` + +Now that the member is enrolled, normal_1 and normal_2 will deallocate +the flow over which it enrolled and signal the IRMd that the enrollment +was successful: + +``` +==02301== irmd(DB): Partial deallocation of port_id 0 by process +13569. +==02301== irmd(DB): Partial deallocation of port_id 1 by process 4363. +==02301== irmd(II): Completed deallocation of port_id 0 by process +2324. +==02301== irmd(II): Completed deallocation of port_id 1 by process +2324. +==02324== ipcpd-local(II): Flow with fd 64 deallocated. +==02324== ipcpd-local(II): Flow with fd 65 deallocated. +==13569== normal-ipcp(II): Enrolled with normal_layer. +==02301== irmd(II): Enrolled IPCP 13569 in layer normal_layer. +``` + +Now that normal_2 is a full member of the layer, the irm tool will +complete the autobind option and bind normal_2 to the name +"normal_layer" so it can also enroll new members. + +``` +==02301== irmd(II): Bound process 13569 to name normal_layer. +``` + +![Tutorial 2 after enrolment](/images/ouroboros_tut2_enrolled.png) + +At this point, have two enrolled members of the normal_layer. What we +need to do next is connect them. We will need a *management flow*, for +the management network, which is used to distribute point-to-point +information (such as routing information) and a *data transfer flow* +over which the layer will forward traffic coming either from higher +layers or internal components (such as the DHT and flow allocator). They +can be established in any order, but it is recommended to create the +management network first to achieve the minimal setup times for the +network layer: + +``` +$ irm ipcp connect name normal_2 dst normal_1 comp mgmt +$ irm ipcp connect name normal_2 dst normal_1 comp dt +``` + +The IPCP and IRMd log the flow and connection establishment: + +``` +==02301== irmd(DB): Connecting Management to normal_1. +==02324== ipcpd-local(DB): Allocating flow to e9504761 on fd 64. +==02301== irmd(DB): Flow req arrived from IPCP 2324 for e9504761. +==02301== irmd(II): Flow request arrived for normal_1. +==02324== ipcpd-local(II): Pending local allocation request on fd 64. +==02301== irmd(II): Flow on port_id 0 allocated. +==02324== ipcpd-local(II): Flow allocation completed, fds (64, 65). +==02301== irmd(II): Flow on port_id 1 allocated. +==13569== connection-manager(DB): Sending cacep info for protocol LSP to +fd 64. +==04363== link-state-routing(DB): Type mgmt neighbor 416743497 added. +==02301== irmd(DB): New instance (4363) of ipcpd-normal added. +==02301== irmd(DB): This process accepts flows for: +==02301== irmd(DB): normal_layer +==02301== irmd(DB): normal_1 +==13569== link-state-routing(DB): Type mgmt neighbor 465922905 added. +==02301== irmd(II): Established Management connection between IPCP 13569 +and normal_1. +``` + +The IPCPs established a management flow between the link-state routing +components (currently that is the only component that needs a management +flow). The output is similar for the data transfer flow, however, +creating a data transfer flow triggers some additional activity: + +``` +==02301== irmd(DB): Connecting Data Transfer to normal_1. +==02324== ipcpd-local(DB): Allocating flow to e9504761 on fd 66. +==02301== irmd(DB): Flow req arrived from IPCP 2324 for e9504761. +==02301== irmd(II): Flow request arrived for normal_1. +==02324== ipcpd-local(II): Pending local allocation request on fd 66. +==02301== irmd(II): Flow on port_id 2 allocated. +==02324== ipcpd-local(II): Flow allocation completed, fds (66, 67). +==02301== irmd(II): Flow on port_id 3 allocated. +==13569== connection-manager(DB): Sending cacep info for protocol dtp to +fd 65. +==04363== dt(DB): Added fd 65 to SDU scheduler. +==04363== link-state-routing(DB): Type dt neighbor 416743497 added. +==02301== irmd(DB): New instance (4363) of ipcpd-normal added. +==02301== irmd(DB): This process accepts flows for: +==02301== irmd(DB): normal_layer +==02301== irmd(DB): normal_1 +==13569== dt(DB): Added fd 65 to SDU scheduler. +==13569== link-state-routing(DB): Type dt neighbor 465922905 added. +==13569== dt(DB): Could not get nhop for addr 465922905. +==02301== irmd(II): Established Data Transfer connection between IPCP +13569 and normal_1. +==13569== dt(DB): Could not get nhop for addr 465922905. +==13569== dht(DB): Enrollment of DHT completed. +``` + +First, the data transfer flow is added to the SDU scheduler. Next, the +neighbor's address is added to the link-state database and a Link-State +Update message is broadcast over the management network. Finally, if the +DHT is not yet enrolled, it will try to do so when it detects a new data +transfer flow. Since this is the first data transfer flow in the +network, the DHT will try to enroll. It may take some time for the +routing entry to get inserted to the forwarding table, so the DHT +re-tries a couple of times (this is the "could not get nhop" message +in the debug log). + +Our oping server is not registered yet in the normal layer. Let's +register it in the normal layer as well, and connect the client: + +``` +$ irm r n oping_server layer normal_layer +$ oping -n oping_server -c 5 +``` + +The IRMd and IPCP will log: + +``` +==02301== irmd(II): Registered oping_server in normal_layer as +465bac77. +==02301== irmd(II): Registered oping_server in normal_layer as +465bac77. +==02324== ipcpd-local(DB): Allocating flow to 4721372d on fd 68. +==02301== irmd(DB): Flow req arrived from IPCP 2324 for 4721372d. +==02301== irmd(II): Flow request arrived for oping_server. +==02324== ipcpd-local(II): Pending local allocation request on fd 68. +==02301== irmd(II): Flow on port_id 4 allocated. +==02324== ipcpd-local(II): Flow allocation completed, fds (68, 69). +==02301== irmd(II): Flow on port_id 5 allocated. +==02301== irmd(DB): New instance (2337) of oping added. +==02301== irmd(DB): This process accepts flows for: +==02301== irmd(DB): oping_server +==02301== irmd(DB): Partial deallocation of port_id 4 by process 749. +==02301== irmd(II): Completed deallocation of port_id 4 by process +2324. +==02324== ipcpd-local(II): Flow with fd 68 deallocated. +==02301== irmd(DB): Dead process removed: 749. +==02301== irmd(DB): Partial deallocation of port_id 5 by process 2337. +==02301== irmd(II): Completed deallocation of port_id 5 by process +2324. +==02324== ipcpd-local(II): Flow with fd 69 deallocated. +``` + +The client connected over the local layer instead of the normal layer. +This is because the IRMd prefers the local layer. If we unregister the +name from the local layer, the client will connect over the normal +layer: + +``` +$ irm unregister name oping_server layer local_layer +$ oping -n oping_server -c 5 +``` + +As shown by the logs (the normal IPCP doesn't log the flow allocation): + +``` +==02301== irmd(DB): Flow req arrived from IPCP 13569 for 465bac77. +==02301== irmd(II): Flow request arrived for oping_server. +==02301== irmd(II): Flow on port_id 5 allocated. +==02301== irmd(II): Flow on port_id 4 allocated. +==02301== irmd(DB): New instance (2337) of oping added. +==02301== irmd(DB): This process accepts flows for: +==02301== irmd(DB): oping_server +``` + +This concludes tutorial 2. You can shut down everything or continue with +tutorial 3. diff --git a/content/docs/tutorials/tutorial-3.md b/content/docs/tutorials/tutorial-3.md new file mode 100644 index 0000000..2dd0645 --- /dev/null +++ b/content/docs/tutorials/tutorial-3.md @@ -0,0 +1,210 @@ +--- +title: "Tutorial 3: IPCP statistics" +draft: false +--- + +For this tutorial, you should have a local layer, a normal layer and a +ping server registered in the normal layer. You will need to have the +FUSE libraries installed and Ouroboros compiled with FUSE support. We +will show you how to get some statistics from the network layer which is +exported by the IPCPs at /tmp/ouroboros (this mountpoint can be set at +compile time): + +``` +$ tree /tmp/ouroboros +/tmp/ouroboros/ +|-- ipcpd-normal.13569 +| |-- dt +| | |-- 0 +| | |-- 1 +| | `-- 65 +| `-- lsdb +| |-- 416743497.465922905 +| |-- 465922905.416743497 +| |-- dt.465922905 +| `-- mgmt.465922905 +`-- ipcpd-normal.4363 + |-- dt + | |-- 0 + | |-- 1 + | `-- 65 + `-- lsdb + |-- 416743497.465922905 + |-- 465922905.416743497 + |-- dt.416743497 + `-- mgmt.416743497 + +6 directories, 14 files +``` + +There are two filesystems, one for each normal IPCP. Currently, it shows +information for two components: data transfer and the link-state +database. The data transfer component lists flows on known flow +descriptors. The flow allocator component will usually be on fd 0 and +the directory (DHT). There is a single (N-1) data transfer flow on fd 65 +that the IPCPs can use to send data (these fd's will usually not be the +same). The routing component sees that data transfer flow as two +unidirectional links. It has a management flow and data transfer flow to +its neighbor. Let's have a look at the data transfer flow in the +network: + +``` +$ cat /tmp/ouroboros/ipcpd-normal.13569/dt/65 +Flow established at: 2018-03-07 18:47:43 +Endpoint address: 465922905 +Queued packets (rx): 0 +Queued packets (tx): 0 + +Qos cube 0: + sent (packets): 4 + sent (bytes): 268 + rcvd (packets): 3 + rcvd (bytes): 298 + local sent (packets): 4 + local sent (bytes): 268 + local rcvd (packets): 3 + local rcvd (bytes): 298 + dropped ttl (packets): 0 + dropped ttl (bytes): 0 + failed writes (packets): 0 + failed writes (bytes): 0 + failed nhop (packets): 0 + failed nhop (bytes): 0 + + +``` + +The above output shows the statistics for the data transfer component of +the IPCP that enrolled into the layer. It shows the time the flow was +established, the endpoint address and the number of packets that are in +the incoming and outgoing queues. Then it lists packet statistics per +QoS cube. It sent 4 packets, and received 3 packets. All the packets +came from local sources (internal components of the IPCP) and were +delivered to local destinations. Let's have a look where they went. + +``` +$ cat /tmp/ouroboros/ipcpd-normal.13569/dt/1 +Flow established at: 2018-03-07 18:47:43 +Endpoint address: flow-allocator +Queued packets (rx): 0 +Queued packets (tx): 0 + + +``` + +There is no traffic on fd 0, which is the flow allocator component. This +will only be used when higher layer applications will use this normal +layer. Let's have a look at fd 1. + +``` +$ cat /tmp/ouroboros/ipcpd-normal.13569/dt/1 +Flow established at: 2018-03-07 18:47:43 +Endpoint address: dht +Queued packets (rx): 0 +Queued packets (tx): 0 + +Qos cube 0: + sent (packets): 3 + sent (bytes): 298 + rcvd (packets): 0 + rcvd (bytes): 0 + local sent (packets): 0 + local sent (bytes): 0 + local rcvd (packets): 6 + local rcvd (bytes): 312 + dropped ttl (packets): 0 + dropped ttl (bytes): 0 + failed writes (packets): 0 + failed writes (bytes): 0 + failed nhop (packets): 2 + failed nhop (bytes): 44 + + +``` + +The traffic for the directory (DHT) is on fd1. Take note that this is +from the perspective of the data transfer component. The data transfer +component sent 3 packets to the DHT, these are the 3 packets it received +from the data transfer flow. The data transfer component received 6 +packets from the DHT. It only sent 4 on fd 65. 2 packets failed because +of nhop. This is because the forwarding table was being updated from the +routing table. Let's send some traffic to the oping server. + +``` +$ oping -n oping_server -i 0 +Pinging oping_server with 64 bytes of data: + +64 bytes from oping_server: seq=0 time=0.547 ms +... +64 bytes from oping_server: seq=999 time=0.184 ms + +--- oping_server ping statistics --- +1000 SDUs transmitted, 1000 received, 0% packet loss, time: 106.538 ms +rtt min/avg/max/mdev = 0.151/0.299/2.269/0.230 ms +``` + +This sent 1000 packets to the server. Let's have a look at the flow +allocator: + +``` +$ cat /tmp/ouroboros/ipcpd-normal.13569/dt/0 +Flow established at: 2018-03-07 18:47:43 +Endpoint address: flow-allocator +Queued packets (rx): 0 +Queued packets (tx): 0 + +Qos cube 0: + sent (packets): 1 + sent (bytes): 59 + rcvd (packets): 0 + rcvd (bytes): 0 + local sent (packets): 0 + local sent (bytes): 0 + local rcvd (packets): 1 + local rcvd (bytes): 51 + dropped ttl (packets): 0 + dropped ttl (bytes): 0 + failed writes (packets): 0 + failed writes (bytes): 0 + failed nhop (packets): 0 + failed nhop (bytes): 0 + + +``` + +The flow allocator has sent and received a message: a request and a +response for the flow allocation between the oping client and server. +The data transfer flow will also have additional traffic: + +``` +$ cat /tmp/ouroboros/ipcpd-normal.13569/dt/65 +Flow established at: 2018-03-07 18:47:43 +Endpoint address: 465922905 +Queued packets (rx): 0 +Queued packets (tx): 0 + +Qos cube 0: + sent (packets): 1013 + sent (bytes): 85171 + rcvd (packets): 1014 + rcvd (bytes): 85373 + local sent (packets): 13 + local sent (bytes): 1171 + local rcvd (packets): 14 + local rcvd (bytes): 1373 + dropped ttl (packets): 0 + dropped ttl (bytes): 0 + failed writes (packets): 0 + failed writes (bytes): 0 + failed nhop (packets): 0 + failed nhop (bytes): 0 +``` + +This shows the traffic from the oping application. The additional +traffic (the oping sent 1000, the flow allocator 1 and the DHT +previously sent 3) is additional DHT traffic (the DHT periodically +updates). Also note that the traffic reported on the link includes the +FRCT and data transfer headers which in the default configuration is 20 +bytes per packet. + +This concludes tutorial 3. diff --git a/content/docs/tutorials/tutorial-4.md b/content/docs/tutorials/tutorial-4.md new file mode 100644 index 0000000..fd7db3a --- /dev/null +++ b/content/docs/tutorials/tutorial-4.md @@ -0,0 +1,123 @@ +--- +title: "Tutorial 4: Connecting two machines over Ethernet" +draft: false +--- + +In this tutorial we will connect two machines over an Ethernet network +using the eth-llc or eth-dix IPCPs. The eth-llc use of the IEEE 802.2 +Link Layer Control (LLC) service type 1 frame header. The eth-dix IPCP +uses DIX (DEC, Intel, Xerox) Ethernet, also known as Ethernet II. Both +provide a connectionless packet service with unacknowledged delivery. + +Make sure that you have an Ouroboros IRM daemon running on both +machines: + +``` +$ sudo irmd --stdout +``` + +The eth-llc and eth-dix IPCPs attach to an ethernet interface, which is +specified by its device name. The device name can be found in a number +of ways, we'll use the "ip" command here: + +``` +$ ip a +1: lo: mtu 65536 qdisc noqueue state UNKNOWN +group default qlen 1 +link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 +... +2: ens3: mtu 1500 qdisc pfifo_fast +state UP group default qlen 1000 +link/ether fa:16:3e:42:00:38 brd ff:ff:ff:ff:ff:ff +... +3: ens6: mtu 1500 qdisc pfifo_fast +state UP group default qlen 1000 +link/ether fa:16:3e:00:76:c2 brd ff:ff:ff:ff:ff:ff +... +``` + +The output of this command differs between operating systems and +distributions. The interface we need to use in our setup is "ens3" on +both machines, but for you it may be something like "eth0" or +"enp0s7f1" if you are on a wired LAN, or something like "wlan0" or +"wlp2s0" if you are on a Wi-Fi network. For Wi-Fi networks, we +recommend using the eth-dix. + +Usually the interface you will use is the one that has an IP address for +your LAN set. Note that you do not need to have an IP address for this +tutorial, but do make sure the interface is UP. + +Now that we know the interfaces to connect to the network with, let's +start the eth-llc/eth-dix IPCPs. The eth-llc/eth-dix layers don't have +an enrollment phase, all eth-llc IPCPs that are connected to the same +Ethernet, will be part of the layer. For eth-dix IPCPs the layers can be +separated by ethertype. The eth-llc and eth-dix IPCPs can only be +bootstrapped, so care must be taken by to provide the same hash +algorithm to all eth-llc and eth-dix IPCPs that should be in the same +network. We use the default (256-bit SHA3) for the hash and 0xa000 for +the Ethertype for the DIX IPCP. For our setup, it's the exact same +command on both machines. You will likely need to set a different +interface name on each machine. The irm tool allows abbreviated commands +(it is modelled after the "ip" command), which we show here (both +commands do the same): + +``` +node0: $ irm ipcp bootstrap type eth-llc name llc layer eth dev ens3 +node1: $ irm i b t eth-llc n llc l eth if ens3 +``` + +Both IRM daemons should acknowledge the creation of the IPCP: + +``` +==26504== irmd(II): Ouroboros IPC Resource Manager daemon started... +==26504== irmd(II): Created IPCP 27317. +==27317== ipcpd/eth-llc(II): Using raw socket device. +==27317== ipcpd/eth-llc(DB): Bootstrapped IPCP over Ethernet with LLC +with pid 27317. +==26504== irmd(II): Bootstrapped IPCP 27317 in layer eth. +``` + +If it failed, you may have mistyped the interface name, or your system +may not have a valid raw packet API. We are using GNU/Linux machines, so +the IPCP announces that it is using a [raw +socket](http://man7.org/linux/man-pages/man2/socket.2.html) device. On +OS X, the default is a [Berkeley Packet Filter +(BPF)](http://www.manpages.info/macosx/bpf.4.html) device, and on +FreeBSD, the default is a +[netmap](http://info.iet.unipi.it/~luigi/netmap/) device. See the +[compilation options](/compopt) for more information on choosing the +raw packet API. + +The Ethernet layer is ready to use. We will now create a normal layer +on top of it, just like we did over the local layer in the second +tutorial. We are showing some different ways of entering these +commands on the two machines: + +``` +node0: +$ irm ipcp bootstrap type normal name normal_0 layer normal_layer +$ irm bind ipcp normal_0 name normal_0 +$ irm b i normal_0 n normal_layer +$ irm register name normal_layer layer eth +$ irm r n normal_0 l eth +node1: +$ irm ipcp enroll name normal_1 layer normal_layer autobind +$ irm r n normal_layer l eth +$ irm r n normal_1 l eth +``` + +The IPCPs should acknowledge the enrollment in their logs: + +``` +node0: +==27452== enrollment(DB): Enrolling a new neighbor. +==27452== enrollment(DB): Sending enrollment info (47 bytes). +==27452== enrollment(DB): Neighbor enrollment successful. +node1: +==27720== enrollment(DB): Getting boot information. +==27720== enrollment(DB): Received enrollment info (47 bytes). +``` + +You can now continue to set up a management flow and data transfer +flow for the normal layer, like in tutorial 2. This concludes the +fourth tutorial. diff --git a/content/documentation.md b/content/documentation.md deleted file mode 100644 index ed1c3d3..0000000 --- a/content/documentation.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: "Documentation" -draft: false -menu: "main" -menu: - main: - weight: 10 ---- - -# Getting started - -* [Requirements](/requirements/) -* [Download Ouroboros](/download/) -* [Installing Ouroboros](/install/) -* [Compilation options](/compopt/) - -# User tutorials - -These tutorials will be kept up-to-date for the latest version of -Ouroboros. Check the version that is installed on your system using: - -``` -$ irmd --version -``` - -The output shown in the tutorials uses a [*debug*](/compopt) build -of Ouroboros, with FUSE installed and IPCP\_FLOW\_STATS enabled to show -some additional details of what is happening. - -* [Tutorial 1: Local test](/tutorial-1/) -* [Tutorial 2: Adding a layer](/tutorial-2/) -* [Tutorial 3: IPCP statistics](/tutorial-3/) -* [Tutorial 4: Connecting two machines over Ethernet](/tutorial-4/) - -# Developer tutorials - -* [Developer tutorial 1: Writing your first Ouroboros C program](/dev-tut-1/) - -# Extra info - -* [Manual pages](/manuals/) -* [Frequently Asked Questions (FAQ)](/faq/) -* [Performance tests](/performance/) diff --git a/content/download.md b/content/download.md deleted file mode 100644 index 348e7d4..0000000 --- a/content/download.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: "Download Ouroboros" -draft: false ---- - -### Get Ouroboros - -**Packages:** - -For ArchLinux users, the easiest way to try Ouroboros is via the [Arch -User Repository](https://aur.archlinux.org/packages/ouroboros-git/), -which will also install all dependencies. - -**Source:** - -You can clone the [repository](/cgit/ouroboros) over http or https or -git: - -``` -$ git clone http://ouroboros.rocks/git/ouroboros -$ git clone https://ouroboros.rocks/git/ouroboros -$ git clone git://ouroboros.rocks/ouroboros -``` - -Or download a [snapshot](/cgit/ouroboros/). diff --git a/content/download/_index.md b/content/download/_index.md new file mode 100644 index 0000000..f7cd806 --- /dev/null +++ b/content/download/_index.md @@ -0,0 +1,6 @@ +--- +title: Download Ouroboros +date: 2019-06-22 +type: page +draft: false +--- diff --git a/content/download/download.md b/content/download/download.md new file mode 100644 index 0000000..226a921 --- /dev/null +++ b/content/download/download.md @@ -0,0 +1,26 @@ +--- +title: "Download Ouroboros" +date: 2019-06-22 +draft: false +--- + +### Get Ouroboros + +**Packages:** + +For ArchLinux users, the easiest way to try Ouroboros is via the [Arch +User Repository](https://aur.archlinux.org/packages/ouroboros-git/), +which will also install all dependencies. + +**Source:** + +You can clone the [repository](/cgit/ouroboros) over http or https or +git: + +``` +$ git clone http://ouroboros.rocks/git/ouroboros +$ git clone https://ouroboros.rocks/git/ouroboros +$ git clone git://ouroboros.rocks/ouroboros +``` + +Or download a [snapshot](/cgit/ouroboros/). diff --git a/content/download/install.md b/content/download/install.md new file mode 100644 index 0000000..ef8220c --- /dev/null +++ b/content/download/install.md @@ -0,0 +1,52 @@ +--- +title: "Install Ouroboros" +draft: false +--- + +We recommend creating a build directory: + +``` +$ mkdir build && cd build +``` + +Run cmake providing the path to where you cloned the Ouroboros +repository. Assuming you created the build directory inside the +repository directory, do: + +``` +$ cmake .. +``` + +Build and install Ouroboros: + +``` +$ sudo make install +``` + +### Advanced options + +Ouroboros can be configured by providing parameters to the cmake +command: + +``` +$ cmake -D