From 7b329bcdecfd820db98f015fbdd670c49dbdc777 Mon Sep 17 00:00:00 2001 From: Sander Vrijders Date: Tue, 19 Feb 2019 11:48:45 +0100 Subject: Initial commit This adds the initial files for the website, powered by Hugo. Signed-off-by: Sander Vrijders --- .gitignore | 4 + .gitmodules | 3 + archetypes/default.md | 10 + archetypes/page.md | 8 + archetypes/section.md | 6 + config.toml | 23 ++ content/_index.md | 19 ++ content/about.md | 35 +++ content/compopt.html | 434 ++++++++++++++++++++++++++++++ content/contribute.md | 83 ++++++ content/dev-tut-1.md | 73 +++++ content/documentation.md | 43 +++ content/download.md | 25 ++ content/extra.md | 169 ++++++++++++ content/faq.md | 121 +++++++++ content/install.md | 52 ++++ content/manuals.md | 17 ++ content/performance.md | 73 +++++ content/requirements.md | 71 +++++ content/tutorial-1.md | 153 +++++++++++ content/tutorial-2.md | 297 ++++++++++++++++++++ content/tutorial-3.md | 210 +++++++++++++++ content/tutorial-4.md | 123 +++++++++ static/images/avgrttlocal.png | Bin 0 -> 45270 bytes static/images/goodputlocalmbits.png | Bin 0 -> 47697 bytes static/images/icon.png | Bin 0 -> 922 bytes static/images/ouroboros_tut1_overview.png | Bin 0 -> 35029 bytes static/images/ouroboros_tut2_enrolled.png | Bin 0 -> 10816 bytes static/images/ouroboros_tut2_overview.png | Bin 0 -> 9310 bytes static/images/throughputlocalpps.png | Bin 0 -> 47844 bytes static/patches/ouroboros-ioq3.patch | 415 ++++++++++++++++++++++++++++ themes/terrassa | 1 + 32 files changed, 2468 insertions(+) create mode 100644 .gitignore create mode 100644 .gitmodules create mode 100644 archetypes/default.md create mode 100644 archetypes/page.md create mode 100644 archetypes/section.md create mode 100644 config.toml create mode 100644 content/_index.md create mode 100644 content/about.md create mode 100644 content/compopt.html create mode 100644 content/contribute.md create mode 100644 content/dev-tut-1.md create mode 100644 content/documentation.md create mode 100644 content/download.md create mode 100644 content/extra.md create mode 100644 content/faq.md create mode 100644 content/install.md create mode 100644 content/manuals.md create mode 100644 content/performance.md create mode 100644 content/requirements.md create mode 100644 content/tutorial-1.md create mode 100644 content/tutorial-2.md create mode 100644 content/tutorial-3.md create mode 100644 content/tutorial-4.md create mode 100644 static/images/avgrttlocal.png create mode 100644 static/images/goodputlocalmbits.png create mode 100644 static/images/icon.png create mode 100644 static/images/ouroboros_tut1_overview.png create mode 100644 static/images/ouroboros_tut2_enrolled.png create mode 100644 static/images/ouroboros_tut2_overview.png create mode 100644 static/images/throughputlocalpps.png create mode 100644 static/patches/ouroboros-ioq3.patch create mode 160000 themes/terrassa diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..3c5ae86 --- /dev/null +++ b/.gitignore @@ -0,0 +1,4 @@ +_site/ +.sass-cache/ +public/ +*~ \ No newline at end of file diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..30b532e --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "themes/terrassa"] + path = themes/terrassa + url = https://github.com/danielkvist/hugo-terrassa-theme.git diff --git a/archetypes/default.md b/archetypes/default.md new file mode 100644 index 0000000..33b7e3d --- /dev/null +++ b/archetypes/default.md @@ -0,0 +1,10 @@ +--- +title: "{{ replace .Name "-" " " | title }}" +description: "" +date: {{ .Date }} +publishDate: {{ .Date }} +author: "John Doe" +images: [] +draft: true +tags: [] +--- \ No newline at end of file diff --git a/archetypes/page.md b/archetypes/page.md new file mode 100644 index 0000000..2789892 --- /dev/null +++ b/archetypes/page.md @@ -0,0 +1,8 @@ +--- +title: "{{ replace .Name "-" " " | title }}" +description: "" +images: [] +draft: true +menu: main +weight: 0 +--- \ No newline at end of file diff --git a/archetypes/section.md b/archetypes/section.md new file mode 100644 index 0000000..efe83a1 --- /dev/null +++ b/archetypes/section.md @@ -0,0 +1,6 @@ +--- +title : "{{ replace .Name "-" " " | title }}" +description: "" +draft: true +weight: 0 +--- \ No newline at end of file diff --git a/config.toml b/config.toml new file mode 100644 index 0000000..dfc0b79 --- /dev/null +++ b/config.toml @@ -0,0 +1,23 @@ +baseURL = "https://ouroboros.rocks/" +languageCode = "en-us" +title = "Ouroboros" +theme = "terrassa" +enableRobotsTXT = true +DefaultContentLanguage = "en" + +[params] +description = "Ouroboros is a decentralized packet network" +favicon = "/images/icon.png" +logo = "/images/icon.png" + +[params.contact] +email = "ouroboros@freelists.org" + +[params.copy] +copy = "" + +[menu] +[[menu.main]] +name = "Repository" +weight = 40 +url = "/cgit" diff --git a/content/_index.md b/content/_index.md new file mode 100644 index 0000000..6a089f1 --- /dev/null +++ b/content/_index.md @@ -0,0 +1,19 @@ +--- +title: "A decentralized packet network" +--- + +Ouroboros is a decentralized packet network for POSIX operating +systems. + +Ouroboros provides a simple and minimal API for synchronous and +asynchronous IPC. Ouroboros can use IP, Ethernet LLC, Ethernet DIX or +Ethernet PHY (using the experimental raptor NetFPGA implementation) at +the lowest layer. + +The best place to start exploring Ouroboros is this introduction +presented at [FOSDEM +2018](https://www.fosdem.org/2018/schedule/event/ipc/). + +This website is currently under construction and undergoing frequent +updates. The documentation is still sparse, please don't hesitate to +[contact us](/contribute) with any questions you might have. diff --git a/content/about.md b/content/about.md new file mode 100644 index 0000000..0ac9966 --- /dev/null +++ b/content/about.md @@ -0,0 +1,35 @@ +--- +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/compopt.html b/content/compopt.html new file mode 100644 index 0000000..93ad1c4 --- /dev/null +++ b/content/compopt.html @@ -0,0 +1,434 @@ +--- +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/contribute.md b/content/contribute.md new file mode 100644 index 0000000..8cd6b56 --- /dev/null +++ b/content/contribute.md @@ -0,0 +1,83 @@ +--- +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 new file mode 100644 index 0000000..ceac8b6 --- /dev/null +++ b/content/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/documentation.md b/content/documentation.md new file mode 100644 index 0000000..ed1c3d3 --- /dev/null +++ b/content/documentation.md @@ -0,0 +1,43 @@ +--- +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 new file mode 100644 index 0000000..5afb6c3 --- /dev/null +++ b/content/download.md @@ -0,0 +1,25 @@ +--- +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/extra.md b/content/extra.md new file mode 100644 index 0000000..4cdddab --- /dev/null +++ b/content/extra.md @@ -0,0 +1,169 @@ +--- +title: "Extra" +draft: false +menu: "main" +menu: + main: + weight: 40 +--- + +Raptor +------ + +Raptor is a proof-of-concept FPGA demonstrator for running Ouroboros +directly over Ethernet PHY (OSI L1). For this, it uses the [NetFPGA +10G](http://netfpga.org/site/#/systems/3netfpga-10g/details/) platform, +which has Broadcom AEL2005 PHY 10G Ethernet devices. Raptor is +point-to-point and does not use addresses. It is available for Linux +only and support is minimal. If you are interested in trying it out, +please contact us via the ouroboros mailing list or the IRC channel. + +You can clone the [raptor repository](/cgit/raptor/): + +``` +$ git clone http://ouroboros.rocks/git/raptor +$ git clone https://ouroboros.rocks/git/raptor +$ git clone git://ouroboros.rocks/raptor +``` + +There are two directories. The *linux* directory contains the kernel +module, the *netfpga10g* directory contains the files necessary to build +the FPGA design. + +To build and install the kernel module: + +``` +$ make +$ sudo make install +``` + +You can now load/unload the raptor kernel module: + +``` +$ sudo modprobe raptor +$ sudo rmmod raptor +``` + +To uninstall the module: + +``` +$ sudo make uninstall +``` + +You will need to get some cores (such as PCIe and XAUI) from Xilinx in +order to build this project using the provided tcl script. Detailed +instructions on how to build the NetFPGA project under construction. + +Raptor is integrated in Ouroboros and the raptor IPCP will be built if +the kernel module is installed in the default location. + +Raptor was developed as part of the master thesis (in Dutch) +"Implementatie van de Recursive Internet Architecture op een FPGA +platform" by Alexander D'hoore. The kernel module is licensed under +the [GNU Public License (GPL) version +2](https://www.gnu.org/licenses/old-licenses/gpl-2.0.html). The NetFPGA +design is available under the [GNU Lesser Public License (LGPL) version +2.1](https://www.gnu.org/licenses/old-licenses/lgpl-2.1.html). + +ioq3 +---- + +As a demo, we have added Ouroboros support to the +[ioq3](https://github.com/ioquake/ioq3) game engine. ioq3 is a fork of +ID software's [Quake III Arena GPL Source +Release](https://github.com/id-Software/Quake-III-Arena). The port is +available as a [patch](/patches/ouroboros-ioq3.patch). The servers +currently only work in dedicated mode (there is no way yet to start a +server from the client). + +To get the demo, first get the latest ioq3 sources: + +``` +$ git clone https://github.com/ioquake/ioq3.git +$ cd ioq3 +``` + +Copy the patch via the link above, or get it via wget: + +``` +$ wget https://ouroboros.rocks/patches/ouroboros-ioq3.patch +``` + +Apply the patch to the ioq3 code: + +``` +$ git apply ouroboros-ioq3.patch +``` + +With Ouroboros installed, build the ioq3 project in standalone mode: + +``` +$ STANDALONE=1 make +``` + +You may need to install some dependencies like SDL2, see the [ioq3 +documentation](http://wiki.ioquake3.org/Building_ioquake3). + +The ioq3 project only supplies the game engine. To play Quake III Arena, +you need the original game files and a valid key. Various open source +games make use of the engine. We wil detail the procedure for running +OpenArena in your ioq3 build directory. + +Go to your build directory: + +``` +$ cd build// +``` + +To run OpenArena, you only need to the game files. First download the +zip archive (openarena-0.8.8.zip) from the [OpenArena +website](http://www.openarena.ws) (or via wget) and then extract the +baseoa folder: + +``` +$ wget http://www.openarena.ws/request.php?4 -O openarena-0.8.8.zip +$ unzip -j openarena-0.8.8.zip 'openarena-0.8.8/baseoa/*' -d +./baseoa +``` + +Make sure you have a local Ouroboros layer running in your system (see +[this](/tutorial-1/). + +To test the game, start a server (replace with the correct +architecture extension for your machine, eg x86_64): + +``` +$ ./ioq3ded. +set com_basegame baseoa +map aggressor +``` + +Bind the pid of the server to a name and register it in the local layer: + +``` +$ irm bind proc name my.ioq3.server +$ irm reg name my.ioq3.server layer +``` + +To connect, start a client (in a different terminal): + +``` +$ ./ioquake3. +set com_basegame baseoa +``` + +When the client starts, go to the console by typing ~ (tilde) and enter +the following command + +``` +connect -O my.ioq3.server +``` + +The client should now connect to the ioq3 dedicated server over +Ouroboros. Register the name in non-local layers to connect from other +machines. Happy Fragging! + +Rumba +----- + +Rumba is an experimentation framework for deploying recursive network +experiments in various network testbeds. It is developed as part of the +[ARCFIRE](http://ict-arcfire.eu) project, and available on +[gitlab](https://gitlab.com/arcfire/rumba) . diff --git a/content/faq.md b/content/faq.md new file mode 100644 index 0000000..954e1a2 --- /dev/null +++ b/content/faq.md @@ -0,0 +1,121 @@ +--- +title: "Frequently Asked Questions (FAQ)" +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/install.md b/content/install.md new file mode 100644 index 0000000..ef8220c --- /dev/null +++ b/content/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