Kovri Documentation

Intro

Introduction

Kovri is a free, decentralized, anonymity technology developed by Monero.

Currently based on I2P’s open specifications, Kovri uses both garlic encryption and garlic routing to create a private, protected overlay-network across the internet. This overlay-network provides users with the ability to effectively hide their geographical location and internet IP address.

Essentially, Kovri covers an application’s internet traffic to make it anonymous within the network.

A lightweight and security-focused router, Kovri is fully compatible with the I2P network. An alpha version of Kovri is in the works.

Watch development via the Kovri repo and join the community.

Building Instructions

Step 0. (Optional) Skip building and use the release binaries instead

See the README to download pre-built kovri and checksum file. Simply install and start kovri, then off you go!

Step 1. If building, minimum requirements

Linux / MacOSX / FreeBSD 11 / OpenBSD 6

  • Git 1.9.1
  • GCC 4.9.2
  • CMake 2.8.12
  • Boost 1.58 (see platform-specific version caveats)
  • OpenSSL (always the latest stable version)

Windows

Optional:

MacOSX

Note: a minimum of 1 GiB of RAM is suggested for build environments (see #403 for details)

Step 2. Install dependencies

Note: for container options (like Docker and snapcraft), see the User Guide

Ubuntu Xenial (16.04)

Required dependencies:

$ sudo apt-get install git cmake libboost-all-dev libssl-dev  # gcc/g++ and libssl installed by default

Optional dependencies:

$ sudo apt-get install clang
$ sudo apt-get install doxygen graphviz
$ sudo apt-get install libminiupnpc-dev #For users behind a restrictive NAT

Ubuntu Trusty (14.04)

You can either build Boost from source or use PPA Below are instructions for PPA:

Required dependencies:

$ sudo add-apt-repository ppa:ubuntu-toolchain-r/test
$ sudo add-apt-repository ppa:kojoley/boost
$ sudo apt-get update
$ sudo apt-get install libboost-{chrono,log,program-options,date-time,thread,system,filesystem,regex,test}1.58-dev
$ sudo apt-get install git g++-4.9 cmake libboost-all-dev libssl-dev libssl1.0.0

Optional dependencies:

$ sudo apt-get install clang-3.5
$ sudo apt-get install doxygen graphviz
$ sudo apt-get install libminiupnpc-dev #For users behind a restrictive NAT

Debian (stable)

We’ll need to pull from testing for Boost 1.58+ and because of a broken CMake. For documentation’s sake, we will pull all dependencies from testing. If you’re unfamiliar with apt-pinning, proceed with the following before installing dependencies:

  • Create and edit /etc/apt/preferences.d/custom.pref
  • Enter and save the following:
Package: *
Pin: release a=stable
Pin-Priority: 700

Package: *
Pin: release a=testing
Pin-Priority: 650
  • Create and edit /etc/apt/sources.list.d/custom.list
    # Stable
    deb [Enter your mirror here] stable main non-free contrib
    # Testing
    deb [Enter your mirror here] testing main non-free contrib
    
  • Replace [Enter your mirror here] with your mirror (see /etc/apt/sources.list)
  • Run $ sudo apt-get update
  • Install dependencies with the -t testing switch:

Required dependencies:

$ sudo apt-get -t testing install git g++ cmake libboost-all-dev libssl-dev libssl1.0.0

Optional dependencies:

$ sudo apt-get -t testing install clang
$ sudo apt-get -t testing install doxygen graphviz
$ sudo apt-get -t testing install libminiupnpc-dev #For users behind a restrictive NAT

Arch Linux

Required dependencies:

$ sudo pacman -Syu cmake boost  # gcc/g++ and openssl installed by default

Optional dependencies:

$ sudo pacman -S clang
$ sudo pacman -S doxygen graphviz
$ sudo pacman -S miniupnpc #For users behind a restrictive NAT

Mac OSX

Required dependencies:

$ brew install cmake boost openssl # clang installed by default

Optional dependencies:

$ brew install doxygen graphviz
$ brew install miniupnpc #For users behind a restrictive NAT

FreeBSD 11

Required dependencies:

$ sudo pkg install git cmake gmake clang36 boost-libs openssl

Optional dependencies:

$ sudo pkg install doxygen graphviz
$ sudo pkg install miniupnpc #For users behind a restrictive NAT

Note: see FreeBSD build instructions below

OpenBSD 6

Required dependencies:

$ sudo pkg_add bash git cmake gmake g++ llvm

Optional dependencies:

$ sudo pkg_add miniupnpc #For users behind a restrictive NAT
$ sudo pkg_add doxygen graphviz

Build latest boost

# Get latest boost
$ wget [latest boost] -O latest_boost.tar.bz2
$ tar xvjf latest_boost.tar.bz2 && cd latest_boost/

# Download and apply patches
# https://svn.boost.org/trac/boost/attachment/ticket/12575/boost-1.62-asio-libressl.patch
# https://gist.githubusercontent.com/laanwj/bf359281dc319b8ff2e1/raw/92250de8404b97bb99d72ab898f4a8cb35ae1ea3/patch-boost_test_impl_execution_monitor_ipp.patch

# Build boost
$ echo 'using gcc : : eg++ : "-fvisibility=hidden -fPIC" "" "ar" "strip"  "ranlib" "" : ;' > user-config.jam
$ config_opts="runtime-link=shared threadapi=pthread threading=multi link=static variant=release --layout=tagged --build-type=complete --user-config=user-config.jam -sNO_BZIP2=1"
$ ./bootstrap.sh --without-icu --with-libraries=chrono,log,program_options,date_time,thread,system,filesystem,regex,test
$ sudo ./b2 -d2 -d1 ${config_opts} --prefix=${BOOST_PREFIX} stage
$ sudo ./b2 -d0 ${config_opts} --prefix=${BOOST_PREFIX} install

Note: see OpenBSD build instructions below

Windows (MSYS2/MinGW-64)

  • Download the MSYS2 installer, 64-bit or 32-bit as needed, and run it.
  • Use the shortcut associated with your architecture to launch the MSYS2 environment. On 64-bit systems that would be the MinGW-w64 Win64 Shell shortcut. Note that if you are running 64-bit Windows, you will have both 64-bit and 32-bit environments.
  • Update the packages in your MSYS2 install:
    pacman -Sy
    pacman -Su --ignoregroup base
    pacman -Su
    
  • For those of you already familiar with pacman, you can run the normal pacman -Syu to update, but you may get errors and need to restart MSYS2 if pacman’s dependencies are updated.
  • Install dependencies: pacman -S make mingw-w64-x86_64-cmake mingw-w64-x86_64-gcc mingw-w64-x86_64-boost mingw-w64-x86_64-openssl
  • Optional: mingw-w64-x86_64-doxygen (you’ll need Graphviz for doxygen)
  • Note: You’ll need mingw-w64-x86_64-miniupnpc if you are behind a restrictive NAT firewall.

Step 3. Build

1. Clone the repository

$ git clone --recursive https://github.com/monero-project/kovri

2. Build kovri and submodule dependencies with one command

$ make  # to decrease build-time, run `make -j <available CPU cores>`. Example: `make -j4`

3. Install

$ make install
  • End-users MUST run make install for new installations
  • Developers SHOULD run make install after a fresh build

Other options you can use in place of step 2:

For an accurate and complete list of options, see the targets in the Makefile.

Notes

  • All build output (including Doxygen) will be in the build output directory

Clang

To build with clang, you must export the following:

$ export CC=clang CXX=clang++  # replace ```clang``` with a clang version/path of your choosing

FreeBSD

$ export CC=clang36 CXX=clang++36  # Or higher clang version
$ gmake && gmake install
  • Replace make with gmake for all other build options

OpenBSD

$ export CC=clang CXX=clang++  # clang recommended, otherwise egcc/eg++
$ gmake && gmake install
  • Replace make with gmake for all other build options

(Optional) Custom data path

You can customize Kovri’s data path to your liking. Simply export KOVRI_DATA_PATH; example:

$ export KOVRI_DATA_PATH=$HOME/.another-kovri-data-path && make && make install

Step 4. Proceed to the user guide

Read the user guide to get started

Docker

Alternatively, if you use Docker, the following will build the image for you.

$ docker build -t geti2p/kovri .

Fuzz testing

From reference : “LibFuzzer is under active development so you will need the current (or at least a very recent) version of the Clang compiler”

Get a recent version of clang:

$ cd ~/ && mkdir TMP_CLANG && git clone https://chromium.googlesource.com/chromium/src/tools/clang TMP_CLANG/clang
$ ./TMP_CLANG/clang/scripts/update.py
$ cd --

Get libFuzzer:

$ git clone https://chromium.googlesource.com/chromium/llvm-project/llvm/lib/Fuzzer contrib/Fuzzer

Build kovri with fuzz testing enabled:

$ PATH="~/third_party/llvm-build/Release+Asserts/bin:$PATH" CC=clang CXX=clang++ make fuzz-tests

Usage (Example for RouterInfo):

mkdir RI_CORPUS MIN_RI_CORPUS
find ~/.kovri/core/network_database/ -name "router_info*" -exec cp {} RI_CORPUS \;
./build/kovri-util fuzz --target=routerinfo -merge=1 MIN_RI_CORPUS RI_CORPUS
./build/kovri-util fuzz --target=routerinfo -jobs=2 -workers=2 MIN_RI_CORPUS

General Contribution Guidelines

Contributing

Quality Assurance

Compliance

  • We aim for complete C++11/14 compliance; feel free to use this to your advantage with your work
  • It is also highly recommended to use the standard library and dependency libraries when possible

Sending your work

To contribute your work, please proceed with the following:

  1. Fork Kovri
  2. Read our style guide
  3. Create a topic branch
  4. Sign your commit(s)
  5. Send a pull-request to branch master
    • We currently do not have any tags as we are in pre-alpha. For now, you can base your work off of master.
    • Commit messages should be verbose by default, consisting of a short subject line (50 chars max), a blank line, and detailed explanatory text as separate paragraph(s) - unless the title alone is self-explanatory.
    • Commit title should prepend class or aspect of project. For example, “HTTPProxy: implement User-Agent scrubber. Fixes #193.” or “Garlic: fix uninitialized padding in ElGamalBlock”.
    • If a particular commit references another issue, please add a reference. For example “See #123”, or “Fixes #123”. This will help us resolve tickets when we merge into master.
    • In general, commits should be atomic and diffs should be easy to read. For this reason, please try to not mix formatting fixes with non-formatting commits.
    • The body of the pull request should contain an accurate description of what the patch does and provide justification/reasoning for the patch (when appropriate). You should include references to any discussions such as other tickets or chats on IRC.

Proposals

To contribute a proposal, please review our open issues for existing proposals. If what you propose is not there, then open a new issue.

Even though our C4 dictates that we merge everything, we ask that you open a proposal for the following reasons:

  1. A proposal opens up communication
  2. A proposal shows that the contributor respects the input of all project collaborators
  3. A proposal allows seamless collaborator input in an open forum
  4. A proposal saves time if a collaborator is working on a similar feature/issue
  5. A proposal prevents catastrophes and mishaps or allows collaborators to prepare for catastrophes and mishaps

Not opening a proposal will not prevent you from contributing; we will merge what you PR - but a proposal is highly recommended.

TODO’s

  • Do a quick search in the codebase for TODO(unassigned): and/or pick a ticket and start patching!
  • If you create a TODO, assign it to yourself or write in TODO(unassigned):

Code of Conduct (22/C4.1)

License

Copyright (c) 2009-2015 Pieter Hintjens.

This Specification is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This Specification 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. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, see http://www.gnu.org/licenses.

Language

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

Goals

C4 is meant to provide a reusable optimal collaboration model for open source software projects. It has these specific goals:

  • To maximize the scale and diversity of the community around a project, by reducing the friction for new Contributors and creating a scaled participation model with strong positive feedbacks;
  • To relieve dependencies on key individuals by separating different skill sets so that there is a larger pool of competence in any required domain;
  • To allow the project to develop faster and more accurately, by increasing the diversity of the decision making process;
  • To support the natural life cycle of project versions from experimental through to stable, by allowing safe experimentation, rapid failure, and isolation of stable code;
  • To reduce the internal complexity of project repositories, thus making it easier for Contributors to participate and reducing the scope for error;
  • To enforce collective ownership of the project, which increases economic incentive to Contributors and reduces the risk of hijack by hostile entities.

Design

Preliminaries

  • The project SHALL use the git distributed revision control system.
  • The project SHALL be hosted on github.com or equivalent, herein called the “Platform”.
  • The project SHALL use the Platform issue tracker.
  • The project SHOULD have clearly documented guidelines for code style.
  • A “Contributor” is a person who wishes to provide a patch, being a set of commits that solve some clearly identified problem.
  • A “Maintainer” is a person who merges patches to the project. Maintainers are not developers; their job is to enforce process.
  • Contributors SHALL NOT have commit access to the repository unless they are also Maintainers.
  • Maintainers SHALL have commit access to the repository.
  • Everyone, without distinction or discrimination, SHALL have an equal right to become a Contributor under the terms of this contract.

Licensing and Ownership

  • The project SHALL use a share-alike license, such as the GPLv3 or a variant thereof (LGPL, AGPL), or the MPLv2.
  • All contributions to the project source code (“patches”) SHALL use the same license as the project.
  • All patches are owned by their authors. There SHALL NOT be any copyright assignment process.
  • The copyrights in the project SHALL be owned collectively by all its Contributors.
  • Each Contributor SHALL be responsible for identifying themselves in the project Contributor list.

Patch Requirements

  • Maintainers and Contributors MUST have a Platform account and SHOULD use their real names or a well-known alias.
  • A patch SHOULD be a minimal and accurate answer to exactly one identified and agreed problem.
  • A patch MUST adhere to the code style guidelines of the project if these are defined.
  • A patch MUST adhere to the “Evolution of Public Contracts” guidelines defined below.
  • A patch SHALL NOT include non-trivial code from other projects unless the Contributor is the original author of that code.
  • A patch MUST compile cleanly and pass project self-tests on at least the principle target platform.
  • A patch commit message SHOULD consist of a single short (less than 50 character) line summarizing the change, optionally followed by a blank line and then a more thorough description.
  • A “Correct Patch” is one that satisfies the above requirements.

Development Process

  • Change on the project SHALL be governed by the pattern of accurately identifying problems and applying minimal, accurate solutions to these problems.
  • To request changes, a user SHOULD log an issue on the project Platform issue tracker.
  • The user or Contributor SHOULD write the issue by describing the problem they face or observe.
  • The user or Contributor SHOULD seek consensus on the accuracy of their observation, and the value of solving the problem.
  • Users SHALL NOT log feature requests, ideas, suggestions, or any solutions to problems that are not explicitly documented and provable.
  • Thus, the release history of the project SHALL be a list of meaningful issues logged and solved.
  • To work on an issue, a Contributor SHALL fork the project repository and then work on their forked repository.
  • To submit a patch, a Contributor SHALL create a Platform pull request back to the project.
  • A Contributor SHALL NOT commit changes directly to the project.
  • If the Platform implements pull requests as issues, a Contributor MAY directly send a pull request without logging a separate issue.
  • To discuss a patch, people MAY comment on the Platform pull request, on the commit, or elsewhere.
  • To accept or reject a patch, a Maintainer SHALL use the Platform interface.
  • Maintainers SHOULD NOT merge their own patches except in exceptional cases, such as non-responsiveness from other Maintainers for an extended period (more than 1-2 days).
  • Maintainers SHALL NOT make value judgments on correct patches.
  • Maintainers SHALL merge correct patches from other Contributors rapidly.
  • The Contributor MAY tag an issue as “Ready” after making a pull request for the issue.
  • The user who created an issue SHOULD close the issue after checking the patch is successful.
  • Maintainers SHOULD ask for improvements to incorrect patches and SHOULD reject incorrect patches if the Contributor does not respond constructively.
  • Any Contributor who has value judgments on a correct patch SHOULD express these via their own patches.
  • Maintainers MAY commit changes to non-source documentation directly to the project.

Creating Stable Releases

  • The project SHALL have one branch (“master”) that always holds the latest in-progress version and SHOULD always build.
  • The project SHALL NOT use topic branches for any reason. Personal forks MAY use topic branches.
  • To make a stable release someone SHALL fork the repository by copying it and thus become maintainer of this repository.
  • Forking a project for stabilization MAY be done unilaterally and without agreement of project maintainers.
  • A stabilization project SHOULD be maintained by the same process as the main project.
  • A patch to a stabilization project declared “stable” SHALL be accompanied by a reproducible test case.

Evolution of Public Contracts

  • All Public Contracts (APIs or protocols) SHALL be documented.
  • All Public Contracts SHOULD have space for extensibility and experimentation.
  • A patch that modifies a stable Public Contract SHOULD not break existing applications unless there is overriding consensus on the value of doing this.
  • A patch that introduces new features to a Public Contract SHOULD do so using new names.
  • Old names SHOULD be deprecated in a systematic fashion by marking new names as “experimental” until they are stable, then marking the old names as “deprecated”.
  • When sufficient time has passed, old deprecated names SHOULD be marked “legacy” and eventually removed.
  • Old names SHALL NOT be reused by new features.
  • When old names are removed, their implementations MUST provoke an exception (assertion) if used by applications.

Project Administration

  • The project founders SHALL act as Administrators to manage the set of project Maintainers.
  • The Administrators SHALL ensure their own succession over time by promoting the most effective Maintainers.
  • A new Contributor who makes a correct patch SHALL be invited to become a Maintainer.
  • Administrators MAY remove Maintainers who are inactive for an extended period of time, or who repeatedly fail to apply this process accurately.
  • Administrators SHOULD block or ban “bad actors” who cause stress and pain to others in the project. This should be done after public discussion, with a chance for all parties to speak. A bad actor is someone who repeatedly ignores the rules and culture of the project, who is needlessly argumentative or hostile, or who is offensive, and who is unable to self-correct their behavior when asked to do so by others.

Governance Process

Governance Process

Style Guide

Style

  1. Read Google’s C++ Style Guide (particularly for non-formatting style reference)
  2. Run clang-format with -style=file (which uses our provided .clang-format)
    $ cd kovri/ && clang-format -i -style=file src/path/to/my/file
    
  3. Run cpplint (which uses our provided CPPLINT.cfg) to catch any issues that were missed by clang-format
    $ cd kovri/ && cpplint src/path/to/my/file && [edit file manually to apply fixes]
    

Plugins

Here’s what’s currently not caught by clang-format and differs from Google’s proposed C++ style

  • Avoid prepended mixed-case k and MACRO_TYPE for all constants
  • Use Doxygen three-slash /// C++ comments when documenting for Doxygen
  • Try to document all your work for Doxygen as you progress
  • If anonymity is a concern, try to blend in with a present contributor’s style

Optional Checks

  1. cppdep for component dependency, physical insulation, and include checks.
  2. cppcheck for static analysis (complementary to Coverity).
  3. lizard for code complexity checks.

Quality Assurance

Quality Assurance

The following is a proposed model for QA workflow. While linear in nature, any phase can be worked on individually if needed - as long as all phases are eventually addressed.

Phase 1: Basic Review

  • Review open issues on our Issue Tracker
  • Review our Vulnerability Response Process
  • All code must adhere to our contributing guidelines
  • Note areas that need improving (mentally or in code)
  • Create TODO’s and assign if possible

Phase 2: Specification Review / Implementation / Code Documentation

  • Complete specification review on a per module basis; e.g., Streaming, I2PControl, etc.
    • Code must be in-line with essential parts of the specification that will maintain the same (or better) level of anonymity that java I2P provides
    • Refactor/implement/patch when/where needed
  • Ensure C++11/14 compliant implementation
    • Review phase 2 if needed
  • Resolve all related TODO’s
  • Document code as much as possible with inline comments and Doxygen
    • Code should be understood by novice to experienced coders
    • Code should guide the reader to a better understanding of I2P
      • I2P is very complex so our code should act as sovereign replacement of spec documentation and not simply as a supplement (this can be a tedious objective but very rewarding in terms of maintenance and software lifespan)

Phase 3: Crypto Review / Security auditing

  • Ensure that crypto is up-to-date and properly implemented
  • Establish every vector for known exploitation
    • Keep these vectors in mind when writing tests
  • Break Kovri every which-way possible
    • Fix what you break
  • Always use trustworthy, well-written libraries when possible
    • Avoid homebrewed, ad-hoc, I’m sure I know better than the community type of code
  • Seek a 2nd (or more) opinion(s) from colleagues before proceeding to next phase

Phase 4: Bug squashing / Tests / Profiling

  • Resolve priority bugs/issues
  • Write unit-tests tests for every module
    • Run tests. Run them again
    • Full review of test results. Patch if needed. Refactor as necessary
  • Ensure that automation is running on a regular basis
    • valgrind, doxygen, clang-format
    • Patch if needed, refactor as necessary

Phase 5: Confer

  • Confer with colleagues and the community
    • Conferring should be done publicly via ticket, meetings, and/or IRC
  • Accept all feedback and, in response, produce tangible results
  • If satisfied, proceed with next phase, else repeat this phase (or start from a previous phase)

Phase 6: Repeat the cycle from the beginning

User Guide

So, you’ve installed Kovri. Now what?

Step 1. Open your NAT/Firewall

  1. Choose a port between 9111 and 30777
  2. Save this port to your configuration file (kovri.conf)
  3. Poke a hole in your NAT/Firewall to allow incoming TCP/UDP connections to that port (See notes below if you don’t have access)

Notes:

  • If you don’t save the port, kovri will randomly generate a new one on each startup (you also have the choice to pass the port with the --port flag on each startup).
  • If you do not have access to your NAT, see instructions in the building guide for your OS.
  • Don’t share your port number with anyone as it will effect your anonymity!
  • Consider creating a designated kovri user and run kovri only using that user
  • If using Linux, consider using a hardened kernel (such as grsec with RBAC)
  • After installing the appropriate resources in your kovri data path, considering setting appropriate access control with setfacl, umask, or whatever your OS uses for ACL
  • Never share your port number with anyone as it will effect your anonymity!

Note: see kovri.conf to find your data path for Linux/OSX/Windows

Step 3. Configure Kovri, setup tunnels

For a full list of options:

$ ./kovri --help

For complete options with details:

  • kovri.conf configuration file for router and client
  • tunnels.conf configuration file for client/server tunnels

Step 4. (Optional) Setup tunnels

In short, client tunnels are tunnels which you use to connect to other services and server tunnels are used for when you host service(s) (and other people connect to your service).

By default, you will have client tunnels setup for IRC (Irc2P) and email (i2pmail). To add/remove client tunnels, see tunnels.conf.

When creating server tunnel(s), you’ll need to create persistent private keys. To do so, uncomment or create keys = your-keys.dat and replace your-keys with an appropriate name. Do not share your private .dat file with anyone, and be sure to make a backup!

Once setup, your Base32 address will be shown in your log after you start kovri. You can also find the address in a text file along with the private keys file in your kovri data path in the client/keys directory. The address inside this .txt text file is safe to distribute so other people can connect to your service.

Example:

  • Private keys file: client/keys/your-keys.dat
  • Public Base32/Base64 address: client/keys/your-keys.dat.txt

Note: see kovri.conf to find your data path for Linux/OSX/Windows

Step 5. (Optional) Register your new eepsite

Stop! Until #498 is resolved, consider only registering your service with Kovri and not stats.i2p!

  • Open a request with [Subscription Request] your-host.i2p (replace your-host.i2p with your desired hostname) on the Kovri issue tracker
  • In the request body, paste the contents of your public .txt file that was mentioned in the previous step
  • After review, we will add your host and sign the subscription
  • Done!

Step 6. Run Kovri

$ cd build/ && ./kovri
  • Wait 5 minutes or so to get bootstrapped into the network before attempting to use services

Step 7. Join us on IRC

  1. Startup your IRC client
  2. Setup your client to connect to kovri’s IRC port (default 6669). This will connect you to the Irc2P network (I2P’s IRC network)
  3. Join #kovri and #kovri-dev

Step 8. Browse an I2P website (garlic-site/eepsite)

  1. Startup a browser of your choosing (preferably a browser devoted to kovri usage)
  2. Configure your browser by reading these instructions but instead of port 4444 and 4445 change HTTP proxy port to 4446 and SSL proxy port also to 4446
  3. Visit http://check.kovri.i2p

Notes:

  • Just like with Tor, one doesn’t need SSL to safely and securely use the network
  • SSL site support and outproxy service is not currently implemented
  • If someone gives you a .i2p address that’s not in your address book, use the Jump service at http://stats.i2p/i2p/lookup.html
  • Look through hosts.txt in your data directory to view a list of default sites you can easily visit
  • Overall, HTTP Proxy and address book implementation are in development and not yet feature-complete

Step 9. Enjoy!

Container Options

Snapcraft

On Linux systems, use snapcraft for easy deployment.

Step 1. Get the Kovri source repo

$ git clone --recursive https://github.com/monero-project/kovri

Step 2. Install snapcraft

  • Refer to your distribution’s package manager for snapcraft and snapd

On Ubuntu, simple run:

$ sudo apt-get install snapcraft

Step 3. Create the snap

$ cd kovri/ && snapcraft && sudo snap install *.snap --dangerous

Note: the –dangerous flag is needed only because the snap has not been signed (you built it yourself though, so this shouldn’t be an issue)

Step 4. Run Kovri with snapcraft

$ snap run kovri

Docker

Step 1. Install Docker

Installing Docker is outside the scope of this document, please see the docker documentation

Step 2. Configuring / Open Firewall

The docker image comes with the defaults of kovri, but can be configured as explained in earlier sections.

You should choose a random port and open that port (see earlier sections).

Step 3. Running

Default Settings

KOVRI_PORT=42085 && sudo docker run -p 127.0.0.1:4446:4446 -p 127.0.0.1:6669:6669 -p $KOVRI_PORT --env KOVRI_PORT=$KOVRI_PORT geti2p/kovri

Custom Settings

Where ./kovri-settings/ contains kovri.conf and tunnels.conf.

KOVRI_PORT=42085 && sudo docker run -p 127.0.0.1:4446:4446 -p 127.0.0.1:6669:6669 -p $KOVRI_PORT --env KOVRI_PORT=$KOVRI_PORT -v kovri-settings:/home/kovri/.kovri/config:ro geti2p/kovri

Kovri Documentation

Kovri is a free, decentralized, anonymity technology developed by Monero.

Currently based on I2P’s open specifications, Kovri uses both garlic encryption and garlic routing to create a private, protected overlay-network across the internet. This overlay-network provides users with the ability to effectively hide their geographical location and internet IP address.

Essentially, Kovri covers an application’s internet traffic to make it anonymous within the network.

A lightweight and security-focused router, Kovri is fully compatible with the I2P network. An alpha version of Kovri is in the works.

Watch development via the Kovri repo and join the community.

Step 0. (Optional) Skip building and use the release binaries instead

See the README to download pre-built kovri and checksum file. Simply install and start kovri, then off you go!

Step 1. If building, minimum requirements

Linux / MacOSX / FreeBSD 11 / OpenBSD 6

  • Git 1.9.1
  • GCC 4.9.2
  • CMake 2.8.12
  • Boost 1.58 (see platform-specific version caveats)
  • OpenSSL (always the latest stable version)

Windows

Optional:

MacOSX

Note: a minimum of 1 GiB of RAM is suggested for build environments (see #403 for details)

Step 2. Install dependencies

Note: for container options (like Docker and snapcraft), see the User Guide

Ubuntu Xenial (16.04)

Required dependencies:

$ sudo apt-get install git cmake libboost-all-dev libssl-dev  # gcc/g++ and libssl installed by default

Optional dependencies:

$ sudo apt-get install clang
$ sudo apt-get install doxygen graphviz
$ sudo apt-get install libminiupnpc-dev #For users behind a restrictive NAT

Ubuntu Trusty (14.04)

You can either build Boost from source or use PPA Below are instructions for PPA:

Required dependencies:

$ sudo add-apt-repository ppa:ubuntu-toolchain-r/test
$ sudo add-apt-repository ppa:kojoley/boost
$ sudo apt-get update
$ sudo apt-get install libboost-{chrono,log,program-options,date-time,thread,system,filesystem,regex,test}1.58-dev
$ sudo apt-get install git g++-4.9 cmake libboost-all-dev libssl-dev libssl1.0.0

Optional dependencies:

$ sudo apt-get install clang-3.5
$ sudo apt-get install doxygen graphviz
$ sudo apt-get install libminiupnpc-dev #For users behind a restrictive NAT

Debian (stable)

We’ll need to pull from testing for Boost 1.58+ and because of a broken CMake. For documentation’s sake, we will pull all dependencies from testing. If you’re unfamiliar with apt-pinning, proceed with the following before installing dependencies:

  • Create and edit /etc/apt/preferences.d/custom.pref
  • Enter and save the following:
Package: *
Pin: release a=stable
Pin-Priority: 700

Package: *
Pin: release a=testing
Pin-Priority: 650
  • Create and edit /etc/apt/sources.list.d/custom.list
    # Stable
    deb [Enter your mirror here] stable main non-free contrib
    # Testing
    deb [Enter your mirror here] testing main non-free contrib
    
  • Replace [Enter your mirror here] with your mirror (see /etc/apt/sources.list)
  • Run $ sudo apt-get update
  • Install dependencies with the -t testing switch:

Required dependencies:

$ sudo apt-get -t testing install git g++ cmake libboost-all-dev libssl-dev libssl1.0.0

Optional dependencies:

$ sudo apt-get -t testing install clang
$ sudo apt-get -t testing install doxygen graphviz
$ sudo apt-get -t testing install libminiupnpc-dev #For users behind a restrictive NAT

Arch Linux

Required dependencies:

$ sudo pacman -Syu cmake boost  # gcc/g++ and openssl installed by default

Optional dependencies:

$ sudo pacman -S clang
$ sudo pacman -S doxygen graphviz
$ sudo pacman -S miniupnpc #For users behind a restrictive NAT

Mac OSX

Required dependencies:

$ brew install cmake boost openssl # clang installed by default

Optional dependencies:

$ brew install doxygen graphviz
$ brew install miniupnpc #For users behind a restrictive NAT

FreeBSD 11

Required dependencies:

$ sudo pkg install git cmake gmake clang36 boost-libs openssl

Optional dependencies:

$ sudo pkg install doxygen graphviz
$ sudo pkg install miniupnpc #For users behind a restrictive NAT

Note: see FreeBSD build instructions below

OpenBSD 6

Required dependencies:

$ sudo pkg_add bash git cmake gmake g++ llvm

Optional dependencies:

$ sudo pkg_add miniupnpc #For users behind a restrictive NAT
$ sudo pkg_add doxygen graphviz

Build latest boost

# Get latest boost
$ wget [latest boost] -O latest_boost.tar.bz2
$ tar xvjf latest_boost.tar.bz2 && cd latest_boost/

# Download and apply patches
# https://svn.boost.org/trac/boost/attachment/ticket/12575/boost-1.62-asio-libressl.patch
# https://gist.githubusercontent.com/laanwj/bf359281dc319b8ff2e1/raw/92250de8404b97bb99d72ab898f4a8cb35ae1ea3/patch-boost_test_impl_execution_monitor_ipp.patch

# Build boost
$ echo 'using gcc : : eg++ : "-fvisibility=hidden -fPIC" "" "ar" "strip"  "ranlib" "" : ;' > user-config.jam
$ config_opts="runtime-link=shared threadapi=pthread threading=multi link=static variant=release --layout=tagged --build-type=complete --user-config=user-config.jam -sNO_BZIP2=1"
$ ./bootstrap.sh --without-icu --with-libraries=chrono,log,program_options,date_time,thread,system,filesystem,regex,test
$ sudo ./b2 -d2 -d1 ${config_opts} --prefix=${BOOST_PREFIX} stage
$ sudo ./b2 -d0 ${config_opts} --prefix=${BOOST_PREFIX} install

Note: see OpenBSD build instructions below

Windows (MSYS2/MinGW-64)

  • Download the MSYS2 installer, 64-bit or 32-bit as needed, and run it.
  • Use the shortcut associated with your architecture to launch the MSYS2 environment. On 64-bit systems that would be the MinGW-w64 Win64 Shell shortcut. Note that if you are running 64-bit Windows, you will have both 64-bit and 32-bit environments.
  • Update the packages in your MSYS2 install:
    pacman -Sy
    pacman -Su --ignoregroup base
    pacman -Su
    
  • For those of you already familiar with pacman, you can run the normal pacman -Syu to update, but you may get errors and need to restart MSYS2 if pacman’s dependencies are updated.
  • Install dependencies: pacman -S make mingw-w64-x86_64-cmake mingw-w64-x86_64-gcc mingw-w64-x86_64-boost mingw-w64-x86_64-openssl
  • Optional: mingw-w64-x86_64-doxygen (you’ll need Graphviz for doxygen)
  • Note: You’ll need mingw-w64-x86_64-miniupnpc if you are behind a restrictive NAT firewall.

Step 3. Build

1. Clone the repository

$ git clone --recursive https://github.com/monero-project/kovri

2. Build kovri and submodule dependencies with one command

$ make  # to decrease build-time, run `make -j <available CPU cores>`. Example: `make -j4`

3. Install

$ make install
  • End-users MUST run make install for new installations
  • Developers SHOULD run make install after a fresh build

Other options you can use in place of step 2:

For an accurate and complete list of options, see the targets in the Makefile.

Notes

  • All build output (including Doxygen) will be in the build output directory

Clang

To build with clang, you must export the following:

$ export CC=clang CXX=clang++  # replace ```clang``` with a clang version/path of your choosing

FreeBSD

$ export CC=clang36 CXX=clang++36  # Or higher clang version
$ gmake && gmake install
  • Replace make with gmake for all other build options

OpenBSD

$ export CC=clang CXX=clang++  # clang recommended, otherwise egcc/eg++
$ gmake && gmake install
  • Replace make with gmake for all other build options

(Optional) Custom data path

You can customize Kovri’s data path to your liking. Simply export KOVRI_DATA_PATH; example:

$ export KOVRI_DATA_PATH=$HOME/.another-kovri-data-path && make && make install

Step 4. Proceed to the user guide

Read the user guide to get started

Docker

Alternatively, if you use Docker, the following will build the image for you.

$ docker build -t geti2p/kovri .

Fuzz testing

From reference : “LibFuzzer is under active development so you will need the current (or at least a very recent) version of the Clang compiler”

Get a recent version of clang:

$ cd ~/ && mkdir TMP_CLANG && git clone https://chromium.googlesource.com/chromium/src/tools/clang TMP_CLANG/clang
$ ./TMP_CLANG/clang/scripts/update.py
$ cd --

Get libFuzzer:

$ git clone https://chromium.googlesource.com/chromium/llvm-project/llvm/lib/Fuzzer contrib/Fuzzer

Build kovri with fuzz testing enabled:

$ PATH="~/third_party/llvm-build/Release+Asserts/bin:$PATH" CC=clang CXX=clang++ make fuzz-tests

Usage (Example for RouterInfo):

mkdir RI_CORPUS MIN_RI_CORPUS
find ~/.kovri/core/network_database/ -name "router_info*" -exec cp {} RI_CORPUS \;
./build/kovri-util fuzz --target=routerinfo -merge=1 MIN_RI_CORPUS RI_CORPUS
./build/kovri-util fuzz --target=routerinfo -jobs=2 -workers=2 MIN_RI_CORPUS

Contributing

Quality Assurance

Compliance

  • We aim for complete C++11/14 compliance; feel free to use this to your advantage with your work
  • It is also highly recommended to use the standard library and dependency libraries when possible

Sending your work

To contribute your work, please proceed with the following:

  1. Fork Kovri
  2. Read our style guide
  3. Create a topic branch
  4. Sign your commit(s)
  5. Send a pull-request to branch master
    • We currently do not have any tags as we are in pre-alpha. For now, you can base your work off of master.
    • Commit messages should be verbose by default, consisting of a short subject line (50 chars max), a blank line, and detailed explanatory text as separate paragraph(s) - unless the title alone is self-explanatory.
    • Commit title should prepend class or aspect of project. For example, “HTTPProxy: implement User-Agent scrubber. Fixes #193.” or “Garlic: fix uninitialized padding in ElGamalBlock”.
    • If a particular commit references another issue, please add a reference. For example “See #123”, or “Fixes #123”. This will help us resolve tickets when we merge into master.
    • In general, commits should be atomic and diffs should be easy to read. For this reason, please try to not mix formatting fixes with non-formatting commits.
    • The body of the pull request should contain an accurate description of what the patch does and provide justification/reasoning for the patch (when appropriate). You should include references to any discussions such as other tickets or chats on IRC.

Proposals

To contribute a proposal, please review our open issues for existing proposals. If what you propose is not there, then open a new issue.

Even though our C4 dictates that we merge everything, we ask that you open a proposal for the following reasons:

  1. A proposal opens up communication
  2. A proposal shows that the contributor respects the input of all project collaborators
  3. A proposal allows seamless collaborator input in an open forum
  4. A proposal saves time if a collaborator is working on a similar feature/issue
  5. A proposal prevents catastrophes and mishaps or allows collaborators to prepare for catastrophes and mishaps

Not opening a proposal will not prevent you from contributing; we will merge what you PR - but a proposal is highly recommended.

TODO’s

  • Do a quick search in the codebase for TODO(unassigned): and/or pick a ticket and start patching!
  • If you create a TODO, assign it to yourself or write in TODO(unassigned):

Code of Conduct (22/C4.1)

License

Copyright (c) 2009-2015 Pieter Hintjens.

This Specification is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This Specification 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. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, see http://www.gnu.org/licenses.

Language

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

Goals

C4 is meant to provide a reusable optimal collaboration model for open source software projects. It has these specific goals:

  • To maximize the scale and diversity of the community around a project, by reducing the friction for new Contributors and creating a scaled participation model with strong positive feedbacks;
  • To relieve dependencies on key individuals by separating different skill sets so that there is a larger pool of competence in any required domain;
  • To allow the project to develop faster and more accurately, by increasing the diversity of the decision making process;
  • To support the natural life cycle of project versions from experimental through to stable, by allowing safe experimentation, rapid failure, and isolation of stable code;
  • To reduce the internal complexity of project repositories, thus making it easier for Contributors to participate and reducing the scope for error;
  • To enforce collective ownership of the project, which increases economic incentive to Contributors and reduces the risk of hijack by hostile entities.

Design

Preliminaries

  • The project SHALL use the git distributed revision control system.
  • The project SHALL be hosted on github.com or equivalent, herein called the “Platform”.
  • The project SHALL use the Platform issue tracker.
  • The project SHOULD have clearly documented guidelines for code style.
  • A “Contributor” is a person who wishes to provide a patch, being a set of commits that solve some clearly identified problem.
  • A “Maintainer” is a person who merges patches to the project. Maintainers are not developers; their job is to enforce process.
  • Contributors SHALL NOT have commit access to the repository unless they are also Maintainers.
  • Maintainers SHALL have commit access to the repository.
  • Everyone, without distinction or discrimination, SHALL have an equal right to become a Contributor under the terms of this contract.

Licensing and Ownership

  • The project SHALL use a share-alike license, such as the GPLv3 or a variant thereof (LGPL, AGPL), or the MPLv2.
  • All contributions to the project source code (“patches”) SHALL use the same license as the project.
  • All patches are owned by their authors. There SHALL NOT be any copyright assignment process.
  • The copyrights in the project SHALL be owned collectively by all its Contributors.
  • Each Contributor SHALL be responsible for identifying themselves in the project Contributor list.

Patch Requirements

  • Maintainers and Contributors MUST have a Platform account and SHOULD use their real names or a well-known alias.
  • A patch SHOULD be a minimal and accurate answer to exactly one identified and agreed problem.
  • A patch MUST adhere to the code style guidelines of the project if these are defined.
  • A patch MUST adhere to the “Evolution of Public Contracts” guidelines defined below.
  • A patch SHALL NOT include non-trivial code from other projects unless the Contributor is the original author of that code.
  • A patch MUST compile cleanly and pass project self-tests on at least the principle target platform.
  • A patch commit message SHOULD consist of a single short (less than 50 character) line summarizing the change, optionally followed by a blank line and then a more thorough description.
  • A “Correct Patch” is one that satisfies the above requirements.

Development Process

  • Change on the project SHALL be governed by the pattern of accurately identifying problems and applying minimal, accurate solutions to these problems.
  • To request changes, a user SHOULD log an issue on the project Platform issue tracker.
  • The user or Contributor SHOULD write the issue by describing the problem they face or observe.
  • The user or Contributor SHOULD seek consensus on the accuracy of their observation, and the value of solving the problem.
  • Users SHALL NOT log feature requests, ideas, suggestions, or any solutions to problems that are not explicitly documented and provable.
  • Thus, the release history of the project SHALL be a list of meaningful issues logged and solved.
  • To work on an issue, a Contributor SHALL fork the project repository and then work on their forked repository.
  • To submit a patch, a Contributor SHALL create a Platform pull request back to the project.
  • A Contributor SHALL NOT commit changes directly to the project.
  • If the Platform implements pull requests as issues, a Contributor MAY directly send a pull request without logging a separate issue.
  • To discuss a patch, people MAY comment on the Platform pull request, on the commit, or elsewhere.
  • To accept or reject a patch, a Maintainer SHALL use the Platform interface.
  • Maintainers SHOULD NOT merge their own patches except in exceptional cases, such as non-responsiveness from other Maintainers for an extended period (more than 1-2 days).
  • Maintainers SHALL NOT make value judgments on correct patches.
  • Maintainers SHALL merge correct patches from other Contributors rapidly.
  • The Contributor MAY tag an issue as “Ready” after making a pull request for the issue.
  • The user who created an issue SHOULD close the issue after checking the patch is successful.
  • Maintainers SHOULD ask for improvements to incorrect patches and SHOULD reject incorrect patches if the Contributor does not respond constructively.
  • Any Contributor who has value judgments on a correct patch SHOULD express these via their own patches.
  • Maintainers MAY commit changes to non-source documentation directly to the project.

Creating Stable Releases

  • The project SHALL have one branch (“master”) that always holds the latest in-progress version and SHOULD always build.
  • The project SHALL NOT use topic branches for any reason. Personal forks MAY use topic branches.
  • To make a stable release someone SHALL fork the repository by copying it and thus become maintainer of this repository.
  • Forking a project for stabilization MAY be done unilaterally and without agreement of project maintainers.
  • A stabilization project SHOULD be maintained by the same process as the main project.
  • A patch to a stabilization project declared “stable” SHALL be accompanied by a reproducible test case.

Evolution of Public Contracts

  • All Public Contracts (APIs or protocols) SHALL be documented.
  • All Public Contracts SHOULD have space for extensibility and experimentation.
  • A patch that modifies a stable Public Contract SHOULD not break existing applications unless there is overriding consensus on the value of doing this.
  • A patch that introduces new features to a Public Contract SHOULD do so using new names.
  • Old names SHOULD be deprecated in a systematic fashion by marking new names as “experimental” until they are stable, then marking the old names as “deprecated”.
  • When sufficient time has passed, old deprecated names SHOULD be marked “legacy” and eventually removed.
  • Old names SHALL NOT be reused by new features.
  • When old names are removed, their implementations MUST provoke an exception (assertion) if used by applications.

Project Administration

  • The project founders SHALL act as Administrators to manage the set of project Maintainers.
  • The Administrators SHALL ensure their own succession over time by promoting the most effective Maintainers.
  • A new Contributor who makes a correct patch SHALL be invited to become a Maintainer.
  • Administrators MAY remove Maintainers who are inactive for an extended period of time, or who repeatedly fail to apply this process accurately.
  • Administrators SHOULD block or ban “bad actors” who cause stress and pain to others in the project. This should be done after public discussion, with a chance for all parties to speak. A bad actor is someone who repeatedly ignores the rules and culture of the project, who is needlessly argumentative or hostile, or who is offensive, and who is unable to self-correct their behavior when asked to do so by others.

Governance Process

Governance Process

Style

  1. Read Google’s C++ Style Guide (particularly for non-formatting style reference)
  2. Run clang-format with -style=file (which uses our provided .clang-format)
    $ cd kovri/ && clang-format -i -style=file src/path/to/my/file
    
  3. Run cpplint (which uses our provided CPPLINT.cfg) to catch any issues that were missed by clang-format
    $ cd kovri/ && cpplint src/path/to/my/file && [edit file manually to apply fixes]
    

Plugins

Here’s what’s currently not caught by clang-format and differs from Google’s proposed C++ style

  • Avoid prepended mixed-case k and MACRO_TYPE for all constants
  • Use Doxygen three-slash /// C++ comments when documenting for Doxygen
  • Try to document all your work for Doxygen as you progress
  • If anonymity is a concern, try to blend in with a present contributor’s style

Optional Checks

  1. cppdep for component dependency, physical insulation, and include checks.
  2. cppcheck for static analysis (complementary to Coverity).
  3. lizard for code complexity checks.

Quality Assurance

The following is a proposed model for QA workflow. While linear in nature, any phase can be worked on individually if needed - as long as all phases are eventually addressed.

Phase 1: Basic Review

  • Review open issues on our Issue Tracker
  • Review our Vulnerability Response Process
  • All code must adhere to our contributing guidelines
  • Note areas that need improving (mentally or in code)
  • Create TODO’s and assign if possible

Phase 2: Specification Review / Implementation / Code Documentation

  • Complete specification review on a per module basis; e.g., Streaming, I2PControl, etc.
    • Code must be in-line with essential parts of the specification that will maintain the same (or better) level of anonymity that java I2P provides
    • Refactor/implement/patch when/where needed
  • Ensure C++11/14 compliant implementation
    • Review phase 2 if needed
  • Resolve all related TODO’s
  • Document code as much as possible with inline comments and Doxygen
    • Code should be understood by novice to experienced coders
    • Code should guide the reader to a better understanding of I2P
      • I2P is very complex so our code should act as sovereign replacement of spec documentation and not simply as a supplement (this can be a tedious objective but very rewarding in terms of maintenance and software lifespan)

Phase 3: Crypto Review / Security auditing

  • Ensure that crypto is up-to-date and properly implemented
  • Establish every vector for known exploitation
    • Keep these vectors in mind when writing tests
  • Break Kovri every which-way possible
    • Fix what you break
  • Always use trustworthy, well-written libraries when possible
    • Avoid homebrewed, ad-hoc, I’m sure I know better than the community type of code
  • Seek a 2nd (or more) opinion(s) from colleagues before proceeding to next phase

Phase 4: Bug squashing / Tests / Profiling

  • Resolve priority bugs/issues
  • Write unit-tests tests for every module
    • Run tests. Run them again
    • Full review of test results. Patch if needed. Refactor as necessary
  • Ensure that automation is running on a regular basis
    • valgrind, doxygen, clang-format
    • Patch if needed, refactor as necessary

Phase 5: Confer

  • Confer with colleagues and the community
    • Conferring should be done publicly via ticket, meetings, and/or IRC
  • Accept all feedback and, in response, produce tangible results
  • If satisfied, proceed with next phase, else repeat this phase (or start from a previous phase)

Phase 6: Repeat the cycle from the beginning

So, you’ve installed Kovri. Now what?

Step 1. Open your NAT/Firewall

  1. Choose a port between 9111 and 30777
  2. Save this port to your configuration file (kovri.conf)
  3. Poke a hole in your NAT/Firewall to allow incoming TCP/UDP connections to that port (See notes below if you don’t have access)

Notes:

  • If you don’t save the port, kovri will randomly generate a new one on each startup (you also have the choice to pass the port with the --port flag on each startup).
  • If you do not have access to your NAT, see instructions in the building guide for your OS.
  • Don’t share your port number with anyone as it will effect your anonymity!
  • Consider creating a designated kovri user and run kovri only using that user
  • If using Linux, consider using a hardened kernel (such as grsec with RBAC)
  • After installing the appropriate resources in your kovri data path, considering setting appropriate access control with setfacl, umask, or whatever your OS uses for ACL
  • Never share your port number with anyone as it will effect your anonymity!

Note: see kovri.conf to find your data path for Linux/OSX/Windows

Step 3. Configure Kovri, setup tunnels

For a full list of options:

$ ./kovri --help

For complete options with details:

  • kovri.conf configuration file for router and client
  • tunnels.conf configuration file for client/server tunnels

Step 4. (Optional) Setup tunnels

In short, client tunnels are tunnels which you use to connect to other services and server tunnels are used for when you host service(s) (and other people connect to your service).

By default, you will have client tunnels setup for IRC (Irc2P) and email (i2pmail). To add/remove client tunnels, see tunnels.conf.

When creating server tunnel(s), you’ll need to create persistent private keys. To do so, uncomment or create keys = your-keys.dat and replace your-keys with an appropriate name. Do not share your private .dat file with anyone, and be sure to make a backup!

Once setup, your Base32 address will be shown in your log after you start kovri. You can also find the address in a text file along with the private keys file in your kovri data path in the client/keys directory. The address inside this .txt text file is safe to distribute so other people can connect to your service.

Example:

  • Private keys file: client/keys/your-keys.dat
  • Public Base32/Base64 address: client/keys/your-keys.dat.txt

Note: see kovri.conf to find your data path for Linux/OSX/Windows

Step 5. (Optional) Register your new eepsite

Stop! Until #498 is resolved, consider only registering your service with Kovri and not stats.i2p!

  • Open a request with [Subscription Request] your-host.i2p (replace your-host.i2p with your desired hostname) on the Kovri issue tracker
  • In the request body, paste the contents of your public .txt file that was mentioned in the previous step
  • After review, we will add your host and sign the subscription
  • Done!

Step 6. Run Kovri

$ cd build/ && ./kovri
  • Wait 5 minutes or so to get bootstrapped into the network before attempting to use services

Step 7. Join us on IRC

  1. Startup your IRC client
  2. Setup your client to connect to kovri’s IRC port (default 6669). This will connect you to the Irc2P network (I2P’s IRC network)
  3. Join #kovri and #kovri-dev

Step 8. Browse an I2P website (garlic-site/eepsite)

  1. Startup a browser of your choosing (preferably a browser devoted to kovri usage)
  2. Configure your browser by reading these instructions but instead of port 4444 and 4445 change HTTP proxy port to 4446 and SSL proxy port also to 4446
  3. Visit http://check.kovri.i2p

Notes:

  • Just like with Tor, one doesn’t need SSL to safely and securely use the network
  • SSL site support and outproxy service is not currently implemented
  • If someone gives you a .i2p address that’s not in your address book, use the Jump service at http://stats.i2p/i2p/lookup.html
  • Look through hosts.txt in your data directory to view a list of default sites you can easily visit
  • Overall, HTTP Proxy and address book implementation are in development and not yet feature-complete

Step 9. Enjoy!

Container Options

Snapcraft

On Linux systems, use snapcraft for easy deployment.

Step 1. Get the Kovri source repo

$ git clone --recursive https://github.com/monero-project/kovri

Step 2. Install snapcraft

  • Refer to your distribution’s package manager for snapcraft and snapd

On Ubuntu, simple run:

$ sudo apt-get install snapcraft

Step 3. Create the snap

$ cd kovri/ && snapcraft && sudo snap install *.snap --dangerous

Note: the –dangerous flag is needed only because the snap has not been signed (you built it yourself though, so this shouldn’t be an issue)

Step 4. Run Kovri with snapcraft

$ snap run kovri

Docker

Step 1. Install Docker

Installing Docker is outside the scope of this document, please see the docker documentation

Step 2. Configuring / Open Firewall

The docker image comes with the defaults of kovri, but can be configured as explained in earlier sections.

You should choose a random port and open that port (see earlier sections).

Step 3. Running

Default Settings

KOVRI_PORT=42085 && sudo docker run -p 127.0.0.1:4446:4446 -p 127.0.0.1:6669:6669 -p $KOVRI_PORT --env KOVRI_PORT=$KOVRI_PORT geti2p/kovri

Custom Settings

Where ./kovri-settings/ contains kovri.conf and tunnels.conf.

KOVRI_PORT=42085 && sudo docker run -p 127.0.0.1:4446:4446 -p 127.0.0.1:6669:6669 -p $KOVRI_PORT --env KOVRI_PORT=$KOVRI_PORT -v kovri-settings:/home/kovri/.kovri/config:ro geti2p/kovri