Browse Source

Move docs to new repo

pull/806/head
Darknet Villain 8 years ago
parent
commit
78c3babc37
  1. 3
      docs/README.md
  2. 65
      docs/building/android.md
  3. 74
      docs/building/cross.md
  4. 85
      docs/building/ios.md
  5. 15
      docs/building/requirements.md
  6. 136
      docs/building/unix.md
  7. 159
      docs/building/windows.md
  8. 300
      docs/conf.py
  9. 43
      docs/config_opts_after_2.3.0.md
  10. 165
      docs/configuration.md
  11. 36
      docs/family.md
  12. 114
      docs/hacking.md
  13. 41
      docs/index.rst
  14. 171
      docs/usage.md

3
docs/README.md

@ -0,0 +1,3 @@ @@ -0,0 +1,3 @@
Documentation is moved to [separate repository](https://github.com/PurpleI2P/i2pd_docs_en.git)
[View docs online](https://i2pd.readthedocs.io/en/latest/)

65
docs/building/android.md

@ -1,65 +0,0 @@ @@ -1,65 +0,0 @@
Building on Android
===================
There are two versions: with QT and without QT.
Pre-requesties
--------------
You need to install Android SDK, NDK and QT with android support.
- [SDK](https://developer.android.com/studio/index.html) (choose command line tools only)
- [NDK](https://developer.android.com/ndk/downloads/index.html)
- [QT](https://www.qt.io/download-open-source/)(for QT only).
Choose one for your platform for android. For example QT 5.6 under Linux would be [this file](http://download.qt.io/official_releases/qt/5.6/5.6.1-1/qt-opensource-linux-x64-android-5.6.1-1.run)
You also need Java JDK and Ant.
QT-Creator (for QT only)
------------------------
Open QT-creator that should be installed with QT.
Go to Settings/Anndroid and specify correct paths to SDK and NDK.
If everything is correct you will see two set avaiable:
Android for armeabi-v7a (gcc, qt) and Android for x86 (gcc, qt).
Dependencies
--------------
Take following pre-compiled binaries from PurpleI2P's repositories.
git clone https://github.com/PurpleI2P/Boost-for-Android-Prebuilt.git
git clone https://github.com/PurpleI2P/OpenSSL-for-Android-Prebuilt.git
git clone https://github.com/PurpleI2P/MiniUPnP-for-Android-Prebuilt.git
git clone https://github.com/PurpleI2P/android-ifaddrs.git
Building the app with QT
------------------------
- Open `qt/i2pd_qt/i2pd_qt.pro` in the QT-creator
- Change line `MAIN_PATH = /path/to/libraries` to an actual path where you put the dependancies to
- Select appropriate project (usually armeabi-v7a) and build
- You will find an .apk file in `android-build/bin` folder
Building the app without QT
---------------------------
- Change line `I2PD_LIBS_PATH` in `android/jni/Application.mk` to an actual path where you put the dependancies to
- Run `ndk-build -j4` from andorid folder
- Create or edit file 'local.properties'. Place 'sdk.dir=<path to SDK>' and 'ndk.dir=<path to NDK>'
- Run `ant clean debug`
Creating release .apk
----------------------
In order to create release .apk you must obtain a Java keystore file(.jks). Either you have in already, or you can generate it yourself using keytool, or from one of you existing well-know ceritificates.
For example, i2pd release are signed with this [certificate](https://github.com/PurpleI2P/i2pd/blob/openssl/contrib/certificates/router/orignal_at_mail.i2p.crt).
Create file 'ant.propeties':
key.store='path to keystore file'
key.alias='alias name'
key.store.password='keystore password'
key.alias.password='alias password'
Run `ant clean release`

74
docs/building/cross.md

@ -1,74 +0,0 @@ @@ -1,74 +0,0 @@
Cross compilation notes
=======================
Static 64 bit windows binary on Ubuntu 15.10 (Wily Werewolf)
------------------------------------------------------------
Install cross compiler and friends
sudo apt-get install g++-mingw-w64-x86-64
Default is to use Win32 threading model which lacks std::mutex and such. So we change defaults
sudo update-alternatives --set x86_64-w64-mingw32-g++ /usr/bin/x86_64-w64-mingw32-g++-posix
From now on we assume we have everything in `~/dev/`. Get Boost sources unpacked into `~/dev/boost_1_60_0/` and change directory to it.
Now add out cross compiler configuration. Warning: the following will wipe out whatever you had in there.
echo "using gcc : mingw : x86_64-w64-mingw32-g++ ;" > ~/user-config.jam
Proceed with building Boost normal way, but let's define dedicated staging directory
./bootstrap.sh
./b2 toolset=gcc-mingw target-os=windows variant=release link=static runtime-link=static address-model=64 \
--build-type=minimal --with-filesystem --with-program_options --with-date_time \
--stagedir=stage-mingw-64
cd ..
Now we get & build OpenSSL
git clone https://github.com/openssl/openssl
cd openssl
git checkout OpenSSL_1_0_2g
./Configure mingw64 no-rc2 no-rc4 no-rc5 no-idea no-bf no-cast no-whirlpool no-md2 no-md4 no-ripemd no-mdc2 \
no-camellia no-seed no-comp no-krb5 no-gmp no-rfc3779 no-ec2m no-ssl2 no-jpake no-srp no-sctp no-srtp \
--prefix=~/dev/stage --cross-compile-prefix=x86_64-w64-mingw32-
make depend
make
make install
cd ..
...and zlib
git clone https://github.com/madler/zlib
cd zlib
git checkout v1.2.8
CC=x86_64-w64-mingw32-gcc CFLAGS=-O3 ./configure --static --64 --prefix=~/dev/stage
make
make install
cd ..
Now we prepare cross toolchain hint file for CMake, let's name it `~/dev/toolchain-mingw.cmake`
set(CMAKE_SYSTEM_NAME Windows)
set(CMAKE_C_COMPILER x86_64-w64-mingw32-gcc)
set(CMAKE_CXX_COMPILER x86_64-w64-mingw32-g++)
set(CMAKE_RC_COMPILER x86_64-w64-mingw32-windres)
set(CMAKE_FIND_ROOT_PATH /usr/x86_64-w64-mingw32)
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
Download miniupnpc, unpack and symlink it into `~/dev/miniupnpc/`.
Finally, we can build i2pd with all that goodness
git clone https://github.com/PurpleI2P/i2pd
mkdir i2pd-mingw-64-build
cd i2pd-mingw-64-build
BOOST_ROOT=~/dev/boost_1_60_0 cmake -G 'Unix Makefiles' ~/dev/i2pd/build -DBUILD_TYPE=Release \
-DCMAKE_TOOLCHAIN_FILE=~/dev/toolchain-mingw.cmake -DWITH_AESNI=ON -DWITH_UPNP=ON -DWITH_STATIC=ON \
-DWITH_HARDENING=ON -DCMAKE_INSTALL_PREFIX:PATH=~/dev/i2pd-mingw-64-static \
-DZLIB_ROOT=~/dev/stage -DBOOST_LIBRARYDIR:PATH=~/dev/boost_1_60_0/stage-mingw-64/lib \
-DOPENSSL_ROOT_DIR:PATH=~/dev/stage
make
x86_64-w64-mingw32-strip i2pd.exe
By now, you should have a release build with stripped symbols.

85
docs/building/ios.md

@ -1,85 +0,0 @@ @@ -1,85 +0,0 @@
Building on iOS
===================
How to build i2pd for iOS 9 and iOS Simulator 386/x64
Prerequisites
--------------
XCode7+, cmake 3.2+
Dependencies
------------
- precompiled openssl
- precompiled boost with modules `filesystem`, `program_options`, `date_time` and `system`
- ios-cmake toolchain from `https://github.com/vovasty/ios-cmake.git`
Building
--------
Assume you have folder structure
lib/
libboost_date_time.a
libboost_filesystem.a
libboost_program_options.a
libboost_system.a
libboost.a
libcrypto.a
libssl.a
include/
boost/
openssl/
ios-cmake/
i2pd/
```bash
mkdir -p build/simulator/lib build/ios/lib include/i2pd
pushd build/simulator && \
cmake -DIOS_PLATFORM=SIMULATOR \
-DPATCH=/usr/bin/patch \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_TOOLCHAIN_FILE=../../ios-cmake/toolchain/iOS.cmake \
-DWITH_STATIC=yes \
-DWITH_BINARY=no \
-DBoost_INCLUDE_DIR=../../include \
-DOPENSSL_INCLUDE_DIR=../../include \
-DBoost_LIBRARY_DIR=../../lib \
-DOPENSSL_SSL_LIBRARY=../../lib/libssl.a \
-DOPENSSL_CRYPTO_LIBRARY=../../lib/libcrypto.a \
../../i2pd/build && \
make -j16 VERBOSE=1 && \
popd
pushd build/ios
cmake -DIOS_PLATFORM=OS \
-DPATCH=/usr/bin/patch \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_TOOLCHAIN_FILE=../../ios-cmake/toolchain/iOS.cmake \
-DWITH_STATIC=yes \
-DWITH_BINARY=no \
-DBoost_INCLUDE_DIR=../../include \
-DOPENSSL_INCLUDE_DIR=../../include \
-DBoost_LIBRARY_DIR=../../lib \
-DOPENSSL_SSL_LIBRARY=../../lib/libssl.a \
-DOPENSSL_CRYPTO_LIBRARY=../../lib/libcrypto.a \
../../i2pd/build && \
make -j16 VERBOSE=1 && \
popd
libtool -static -o lib/libi2pdclient.a build/*/libi2pdclient.a
libtool -static -o lib/libi2pd.a build/*/libi2pd.a
cp i2pd/*.h include/i2pd
```
Include into project
--------------------
- add all libraries in `lib` folder to `Project linked frameworks`.
- add `libc++` and `libz` libraries from system libraries to `Project linked frameworks`.
- add path to i2p headers to your `Headers search paths`
Alternatively you may use swift wrapper `https://github.com/vovasty/SwiftyI2P.git`

15
docs/building/requirements.md

@ -1,15 +0,0 @@ @@ -1,15 +0,0 @@
Build requirements
==================
In general, for building i2pd you need several things:
* compiler with c++11 support (for example: gcc >= 4.7, clang)
* boost >= 1.49
* openssl library
* zlib library (openssl already depends on it)
Optional tools:
* cmake >= 2.8 (or 3.3+ if you want to use precompiled headers on windows)
* miniupnp library (for upnp support)
* [websocketpp](https://github.com/zaphoyd/websocketpp/) (for websocket ui)

136
docs/building/unix.md

@ -1,136 +0,0 @@ @@ -1,136 +0,0 @@
Building on Unix systems
=============================
First of all we need to make sure that all dependencies are satisfied.
This doc is trying to cover:
* [Debian/Ubuntu](#debian-ubuntu) (contains packaging instructions)
* [Fedora/Centos](#fedora-centos)
* [Fedora/Centos](#mac-os-x)
* [FreeBSD](#freebsd)
Make sure you have all required dependencies for your system successfully installed.
See [this](requirements.md) page for common requirements.
If so then we are ready to go!
Let's clone the repository and start building the i2pd:
git clone https://github.com/PurpleI2P/i2pd.git
Generic build process looks like this (with cmake):
cd i2pd/build
cmake <cmake options> . # see "CMake Options" section below
make # you may add VERBOSE=1 to cmdline for debugging
..or with quick-and-dirty way with just make:
cd i2pd/
make
After successfull build i2pd could be installed with:
make install
CMake Options
-------------
Available CMake options(each option has a form of `<key>=<value>`, for more information see `man 1 cmake`):
* `CMAKE_BUILD_TYPE` build profile (Debug/Release)
* `WITH_BINARY` build i2pd itself
* `WITH_LIBRARY` build libi2pd
* `WITH_STATIC` build static versions of library and i2pd binary
* `WITH_UPNP` build with UPnP support (requires libminiupnp)
* `WITH_AESNI` build with AES-NI support (ON/OFF)
* `WITH_HARDENING` enable hardening features (ON/OFF) (gcc only)
* `WITH_PCH` use pre-compiled header (experimental, speeds up build)
* `WITH_I2LUA` used when building i2lua
* `WITH_WEBSOCKETS` enable websocket server
Also there is `-L` flag for CMake that could be used to list current cached options:
cmake -L
Debian/Ubuntu
-------------
You will need a compiler and other tools that could be installed with `build-essential` package:
sudo apt-get install build-essential
Also you will need a bunch of development libraries:
sudo apt-get install \
libboost-date-time-dev \
libboost-filesystem-dev \
libboost-program-options-dev \
libboost-system-dev \
libssl-dev
If you need UPnP support miniupnpc development library should be installed (don't forget to rerun CMake with needed option):
sudo apt-get install libminiupnpc-dev
You may also build deb-package with the following:
sudo apt-get install fakeroot devscripts
cd i2pd
debuild --no-tgz-check
Fedora/Centos
-------------
You will need a compiler and other tools to perform a build:
sudo yum install make cmake gcc gcc-c++
Also you will need a bunch of development libraries
sudo yum install boost-devel openssl-devel
If you need UPnP support miniupnpc development library should be installed (don't forget to rerun CMake with needed option):
sudo yum install miniupnpc-devel
Latest Fedora systems using [DNF](https://en.wikipedia.org/wiki/DNF_(software)) instead of YUM by default, you may prefer to use DNF, but YUM should be ok
Centos 7 has CMake 2.8.11 in the official repositories that too old to build i2pd, CMake >=2.8.12 is required.
But you can use cmake3 from the epel repository:
yum install epel-release -y
yum install make cmake3 gcc gcc-c++ miniupnpc-devel boost-devel openssl-devel -y
...and then use 'cmake3' instead 'cmake'.
MAC OS X
--------
Requires [homebrew](http://brew.sh)
brew install boost libressl
Then build:
make HOMEBREW=1
FreeBSD
-------
For 10.X use clang. You would also need devel/boost-libs, security/openssl and devel/gmake ports.
Type gmake, it invokes Makefile.bsd, make necessary changes there is required.
Branch 9.X has gcc v4.2, that is too old (not supports -std=c++11)
Required ports:
* `devel/cmake`
* `devel/boost-libs`
* `lang/gcc47`(or later version)
To use newer compiler you should set these variables(replace "47" with your actual gcc version):
export CC=/usr/local/bin/gcc47
export CXX=/usr/local/bin/g++47

159
docs/building/windows.md

@ -1,159 +0,0 @@ @@ -1,159 +0,0 @@
Building on Windows
=========================
There are two approaches available to build i2pd on Windows. The best
one depends on your needs and personal preferences. One is to use
msys2 and [unix alike infrastructure](unix.md). Another
one is to use Visual Studio. While there might be no difference for
end users of i2pd daemon, developers, however, shall be wary of
differences in C++ name mangling between the two compilers when making
a choice to be able to link their software against libi2pd.
If you are a stranger to C++ with no development tools installed on
your system and your only goal is to have i2pd up and running from the
most recent source, consider using msys2. Although it relies on
command line operations, it should be straight forward.
In this guide, we will use CMake for both approaches and we will
assume that you typically have your projects in C:\dev\ as your
development location for the sake of convenience. Adjust paths
accordingly if it is not the case. Note that msys uses unix-alike
paths like /c/dev/ for C:\dev\.
msys2
-----
Get install file `msys2-$ARCH-*.exe` from `https://msys2.github.io`
Where $ARCH is `i686` or `x86_64` (matching your system).
- Open MSYS2 Shell (from Start menu).
- Install all prerequisites and download i2pd source:
export ARCH='i686' # or 'x86_64'
export MINGW='mingw32' # or 'mingw64'
pacman -S mingw-w64-$ARCH-boost mingw-w64-$ARCH-openssl mingw-w64-$ARCH-gcc git make
mkdir -p /c/dev/i2pd
cd /c/dev/i2pd
git clone https://github.com/PurpleI2P/i2pd.git
cd i2pd
# we need compiler on PATH which is usually heavily cluttered on Windows
export PATH=/$MINGW/bin:/usr/bin
make
### Caveats
It is important to restrict PATH as described above.
If you have Strawberry Perl and/or Mercurial installed,
it will pick up gcc & openssl from the wrong places.
If you do use precompiled headers to speed up compilation (recommended),
things can go wrong if compiler options have changed for whatever reason.
Just delete `stdafx.h.gch` found in your build folder, note the file extension.
If you are an Arch Linux user, refrain from updating system with `pacman -Syu`.
Always update runtime separately as described on the home page,
otherwise you might end up with DLLs incompatibility problems.
### AES-NI
If your processor has [AES instruction set](https://en.wikipedia.org/wiki/AES_instruction_set),
use `make USE_AESNI=1` instead just `make`. No check is done however, it will compile,
but it might crash with `Illegal instruction` if this feature is not supported by your processor.
You should be able to run ./i2pd . If you need to start from the new shell,
consider starting *MinGW-w64 Win32 Shell* instead of *MSYS2 Shell*
as it adds `/minw32/bin` to the PATH.
### UPnP
You can install it through the MSYS2 and build with `USE_UPNP` key.
export ARCH='i686' # or 'x86_64'
pacman -S mingw-w64-$ARCH-miniupnpc
make USE_UPNP=yes
Using Visual Studio
-------------------
Requirements for building:
* [CMake](https://cmake.org/) (tested with 3.1.3)
* [Visual Studio Community Edition](https://www.visualstudio.com/en-us/products/visual-studio-community-vs.aspx) (tested with VS2013 Update 4)
* [Boost](http://www.boost.org/) (tested with 1.59)
* Optionally [MiniUPnP](http://miniupnp.free.fr) (tested with 1.9), we need only few client headers
* OpenSSL (tested with 1.0.1p and 1.0.2e), if building from sources (recommended), you'll need as well
* [Netwide assembler](http://www.nasm.us/)
* Strawberry Perl or ActiveState Perl, do NOT try msys2 perl, it won't work
### Building Boost
Open a Command Prompt (there is no need to start Visual Studio command
prompt to build Boost) and run the following:
cd C:\dev\boost
bootstrap
b2 toolset=msvc-12.0 --build-type=complete --with-filesystem --with-program_options --with-date_time
If you are on 64-bit Windows and you want to build 64-bit version as well
b2 toolset=msvc-12.0 --build-type=complete --stagedir=stage64 address-model=64 --with-filesystem --with-program_options --with-date_time
After Boost is compiled, set the environment variable `BOOST_ROOT` to
the directory Boost was unpacked to, e.g., C:\dev\boost.
If you are planning on building only particular variant, e.g. Debug only and static linking,
and/or you are out of space/time, you might consider `--build-type=minimal`.
Take a look at [appveyor.yml](../appveyor.yml) for details on how test builds are done.
### Building OpenSSL
Download OpenSSL, e.g. with git
git clone https://github.com/openssl/openssl.git
cd openssl
git checkout OpenSSL_1_0_1p
Now open Visual Studio command prompt and change directory to that with OpenSSL
set "PATH=%PATH%;C:\Program Files (x86)\nasm"
perl Configure VC-WIN32 --prefix=c:\OpenSSL-Win32
ms\do_nasm
nmake -f ms\ntdll.mak
nmake -f ms\ntdll.mak install
You should have it installed into C:\OpenSSL-Win32 by now.
Note that you might consider providing `-DOPENSSL_ROOT_DIR` to CMake and/or
create a symlink (with mklink /J) to C:\OpenSSL if you plan on maintain
multiple versions, e.g. 64 bit and/or static/shared.
See `C:\Program Files (x86)\CMake\share\cmake-3.3\Modules\FindOpenSSL.cmake` for details.
### Get miniupnpc
If you are behind a UPnP enabled router and don't feel like manually configuring port forwarding,
you should consider using [MiniUPnP](http://miniupnp.free.fr) client.
I2pd can be built capable of using miniupnpc shared library (DLL) to open up necessary port.
You'd want to have include headers around to build i2pd with support for this.
Unpack client source code to subdir, e.g. `C:\dev\miniupnpc`.
You may want to remove version number from folder name included in downloaded archive.
### Creating Visual Studio project
Start CMake GUI, navigate to i2pd directory, choose building directory, e.g. ./out, and configure options.
Alternatively, if you feel adventurous, try that from the command line
mkdir i2pd\out
cd i2pd\out
cmake ..\build -G "Visual Studio 12 2013" -DWITH_UPNP=ON -DWITH_PCH=ON -DCMAKE_INSTALL_PREFIX:PATH=C:\dev\Debug_Win32_stage
If necessary files are not found `WITH_UPNP` will stay off.
### Building i2pd
You can open generated solution/project with Visual Studio and build from there,
alternatively you can use `cmake --build . --config Release --target install` or
[MSBuild tool](https://msdn.microsoft.com/en-us/library/dd293626.aspx)
msbuild i2pd.sln /p:Configuration=Release

300
docs/conf.py

@ -1,300 +0,0 @@ @@ -1,300 +0,0 @@
# -*- coding: utf-8 -*-
#
# i2pd documentation build configuration file, created by
# sphinx-quickstart on Tue Jan 12 06:26:12 2016.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import sys
import os
import shlex
from recommonmark.parser import CommonMarkParser
source_parsers = {
'.md': CommonMarkParser,
}
# Check if on RTD
on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = []
# Add any paths that contain templates here, relative to this directory.
#templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
# source_suffix = ['.rst', '.md']
source_suffix = ['.rst', '.md']
# The encoding of source files.
#source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'i2pd'
copyright = u'2016, PurpleI2P team'
author = u'PurpleI2P team'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = u'2.2.0'
# The full version, including alpha/beta/rc tags.
release = u'2.2.0'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = ['_build']
# The reST default role (used for this markup: `text`) to use for all
# documents.
#default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
# If true, keep warnings as "system message" paragraphs in the built documents.
#keep_warnings = False
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = False
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'default'
if not on_rtd:
try:
import sphinx_rtd_theme
html_theme = 'sphinx_rtd_theme'
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
except ImportError:
pass
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
#html_static_path = ['_static']
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
#html_extra_path = []
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {}
# If false, no module index is generated.
#html_domain_indices = True
# If false, no index is generated.
#html_use_index = True
# If true, the index is split into individual pages for each letter.
#html_split_index = False
# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = None
# Language to be used for generating the HTML full-text search index.
# Sphinx supports the following languages:
# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr'
#html_search_language = 'en'
# A dictionary with options for the search language support, empty by default.
# Now only 'ja' uses this config value
#html_search_options = {'type': 'default'}
# The name of a javascript file (relative to the configuration directory) that
# implements a search results scorer. If empty, the default will be used.
#html_search_scorer = 'scorer.js'
# Output file base name for HTML help builder.
htmlhelp_basename = 'i2pddoc'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#'preamble': '',
# Latex figure (float) alignment
#'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'i2pd.tex', u'i2pd Documentation',
u'PurpleI2P team', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
#latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#latex_use_parts = False
# If true, show page references after internal links.
#latex_show_pagerefs = False
# If true, show URL addresses after external links.
#latex_show_urls = False
# Documents to append as an appendix to all manuals.
#latex_appendices = []
# If false, no module index is generated.
#latex_domain_indices = True
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'i2pd', u'i2pd Documentation',
[author], 1)
]
# If true, show URL addresses after external links.
#man_show_urls = False
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'i2pd', u'i2pd Documentation',
author, 'i2pd', 'One line description of project.',
'Miscellaneous'),
]
# Documents to append as an appendix to all manuals.
#texinfo_appendices = []
# If false, no module index is generated.
#texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#texinfo_show_urls = 'footnote'
# If true, do not generate a @detailmenu in the "Top" node's menu.
#texinfo_no_detailmenu = False

43
docs/config_opts_after_2.3.0.md

@ -1,43 +0,0 @@ @@ -1,43 +0,0 @@
Изменения обработки параметров в релизах > 2.3.0
------------------------------------------------
Система параметров отличается от того, что было ранее и достаточно сильно:
* изменения имён и стиля параметров
Все параметры теперь в виде --help (gnu-style), у некоторых есть шорткаты в виде -h (unix-style).
Это касается всех систем, в том числе винды.
--daemon=1 и подобное -> просто --daemon, без параметра. Нет опции - false, есть - true
--notransit=1 -> --notransit, то же что и выше: есть опция - false, нет - true
--v6 -> --ipv6 (первое было похоже на версию какого-то своего протокола, типа socksproxy --v5)
--tunnelscfg -> --tunconf (имя параметра было слишком длинным, cfg переделан на conf - единообразно с --conf)
--sockskeys -> разделён на два, для socks и httpproxy по-отдельности
* поддержка секций в основном конфиге
Выглядит это так:
# основные опции
pidfile = /var/run/i2pd.pid
#
# настройки конкретного модуля
[httproxy]
address = 1.2.3.4
port = 4446
keys = httproxy-keys.dat
# и так далее
[sam]
enabled = no
addresss = 127.0.0.2
# ^^ переопределяется только адрес, остальное берётся из дефолта
Точно так же сейчас работает конфиг туннелей: секция до точки - имя, после - параметр
* поддержка выключения отдельных сервисов "на корню" см sam.enabled и подобное
Это позволило задать дефолт для номера порта и не писать его руками для включения.
* добавлен --help (см #110)
* присутствует некая валидация параметров, --port=abcd - не прокатит, --port=100500 - тоже

165
docs/configuration.md

@ -1,165 +0,0 @@ @@ -1,165 +0,0 @@
i2pd configuration
==================
Command line options
--------------------
Options specified on the command line take precedence over those in the config file.
If you are upgrading your very old router (< 2.3.0) see also [this](config_opts_after_2.3.0.md) page.
* --help - Show builtin help message (default value of option will be shown in braces)
* --conf= - Config file (default: ~/.i2pd/i2pd.conf or /var/lib/i2pd/i2pd.conf)
This parameter will be silently ignored if the specified config file does not exist.
* --tunconf= - Tunnels config file (default: ~/.i2pd/tunnels.conf or /var/lib/i2pd/tunnels.conf)
* --pidfile= - Where to write pidfile (dont write by default)
* --log= - Logs destination: stdout, file (stdout if not set, file - otherwise, for compatibility)
* --logfile= - Path to logfile (default - autodetect)
* --loglevel= - Log messages above this level (debug, info, warn, error)
* --datadir= - Path to storage of i2pd data (RI, keys, peer profiles, ...)
* --host= - Router external IP for incoming connections
* --port= - Port to listen for incoming connections (default: auto)
* --daemon - Router will go to background after start
* --service - Router will use system folders like '/var/lib/i2pd'
* --ipv6 - Enable communication through ipv6. false by default
* --notransit - Router will not accept transit tunnels at startup. false by default
* --floodfill - Router will be floodfill. false by default
* --bandwidth= - Bandwidth limit: integer in KBps or letters: L (32), O (256), P (2048), X (>9000)
* --family= - Name of a family, router belongs to
* --netid= - Network ID, router belongs to. Main I2P is 2.
Windows-specific options:
* --svcctl= - Windows service management (--svcctl="install" or --svcctl="remove")
* --insomnia - Prevent system from sleeping
* --close= - Action on close: minimize, exit, ask
All options below still possible in cmdline, but better write it in config file:
* --http.enabled= - If webconsole is enabled. true by default
* --http.address= - The address to listen on (HTTP server)
* --http.port= - The port to listen on (HTTP server) 7070 by default
* --http.auth - Enable basic HTTP auth for webconsole
* --http.user= - Username for basic auth (default: i2pd)
* --http.pass= - Password for basic auth (default: random, see logs)
* --httpproxy.enabled= - If HTTP proxy is enabled. true by default
* --httpproxy.address= - The address to listen on (HTTP Proxy)
* --httpproxy.port= - The port to listen on (HTTP Proxy) 4444 by default
* --httpproxy.keys= - optional keys file for HTTP proxy local destination
* --httpproxy.signaturetype= - signature type for new keys if keys file is set. 7 by default
* --httpproxy.inbound.length= - Inbound tunnels length if keys is set. 3 by default
* --httpproxy.inbound.quantity= - Inbound tunnels quantity if keys is set. 5 by default
* --httpproxy.outbound.length= - Outbound tunnels length if keys is set. 3 by default
* --httpproxy.outbound.quantity= - Outbound tunnels quantity if keys is set. 5 by default
* --socksproxy.enabled= - If SOCKS proxy is enabled. true by default
* --socksproxy.address= - The address to listen on (SOCKS Proxy)
* --socksproxy.port= - The port to listen on (SOCKS Proxy). 4447 by default
* --socksproxy.keys= - optional keys file for SOCKS proxy local destination
* --socksproxy.signaturetype= - signature type for new keys if keys file is set. 7 by default
* --socksproxy.inbound.length= - Inbound tunnels length if keys is set. 3 by default
* --socksproxy.inbound.quantity= - Inbound tunnels quantity if keys is set. 5 by default
* --socksproxy.outbound.length= - Outbound tunnels length if keys is set. 3 by default
* --socksproxy.outbound.quantity= - Outbound tunnels quantity if keys is set. 5 by default
* --socksproxy.outproxy= - Address of outproxy. requests outside i2p will go there
* --socksproxy.outproxyport= - Outproxy remote port
* --sam.address= - The address to listen on (SAM bridge)
* --sam.port= - Port of SAM bridge. Usually 7656. SAM is off if not specified
* --sam.enabled= - If SAM is enabled. false by default
* --bob.address= - The address to listen on (BOB command channel)
* --bob.port= - Port of BOB command channel. Usually 2827. BOB is off if not specified
* --bob.enabled= - If BOB is enabled. false by default
* --i2cp.address= - The address to listen on or an abstract address for Android LocalSocket
* --i2cp.port= - Port of I2CP server. Usually 7654. Ignored for Andorid
* --i2cp.enabled= - If I2CP is enabled. false by default. Other services don't require I2CP
* --i2pcontrol.address= - The address to listen on (I2P control service)
* --i2pcontrol.port= - Port of I2P control service. Usually 7650. I2PControl is off if not specified
* --i2pcontrol.enabled= - If I2P control is enabled. false by default
* --i2pcontrol.password= - I2P control authentication password. itoopie by default
* --i2pcontrol.cert= - I2P control HTTPS certificate file name. i2pcontrol.crt.pem by default
* --i2pcontrol.key= - I2P control HTTPS certificate key file name. i2pcontrol.key.pem by default
* --upnp.enabled= - Enable or disable UPnP, false by default for CLI and true for GUI (Windows, Android)
* --upnp.name= - Name i2pd appears in UPnP forwardings list. I2Pd by default
* --precomputation.elgamal= - Use ElGamal precomputated tables. false for x64 and true for other platforms by default
* --reseed.verify= - Request SU3 signature verification
* --reseed.file= - Full path to SU3 file to reseed from
* --reseed.urls= - Reseed URLs, separated by comma
* --addressbook.defaulturl= - AddressBook subscription URL for initial setup
* --addressbook.subscriptions= - AddressBook subscriptions URLs, separated by comma
* --limits.transittunnels= - Override maximum number of transit tunnels. 2500 by default
* --limits.openfiles= - Maximum size of corefile in Kb (0 - use system limit)
* --limits.coresize= - Maximum size of corefile in Kb (0 - use system limit)
Config files
------------
INI-like, syntax is the following : <key> = <value>.
Comments are "#", not ";" as you may expect. See [boost ticket](https://svn.boost.org/trac/boost/ticket/808)
All command-line parameters are allowed as keys, but note for those which contains dot (.).
For example:
i2pd.conf:
# comment
log = true
ipv6 = true
# settings for specific module
[httpproxy]
port = 4444
# ^^ this will be --httproxy.port= in cmdline
# another comment
[sam]
enabled = true
See also commented config with examples of all options in ``docs/i2pd.conf``.
tunnels.conf:
# outgoing tunnel sample, to remote service
# mandatory parameters:
# * type -- always "client"
# * port -- local port to listen to
# * destination -- i2p hostname
# optional parameters (may be omitted)
# * keys -- our identity, if unset, will be generated on every startup,
# if set and file missing, keys will be generated and placed to this file
# * address -- local interface to bind
# * signaturetype -- signature type for new destination. 0 (DSA/SHA1), 1 (EcDSA/SHA256) or 7 (EdDSA/SHA512)
[IRC]
type = client
address = 127.0.0.1
port = 6668
destination = irc.postman.i2p
keys = irc-keys.dat
#
# incoming tunnel sample, for local service
# mandatory parameters:
# * type -- "server" or "http"
# * host -- ip address of our service
# * port -- port of our service
# * keys -- file with LeaseSet of address in i2p
# optional parameters (may be omitted)
# * inport -- optional, i2p service port, if unset - the same as 'port'
# * accesslist -- comma-separated list of i2p addresses, allowed to connect
# every address is b32 without '.b32.i2p' part
[LOCALSITE]
type = http
host = 127.0.0.1
port = 80
keys = site-keys.dat
#
[IRC-SERVER]
type = server
host = 127.0.0.1
port = 6667
keys = irc.dat
Also see [this page](https://github.com/PurpleI2P/i2pd/wiki/tunnels.cfg) for more tunnel examples.

36
docs/family.md

@ -1,36 +0,0 @@ @@ -1,36 +0,0 @@
Family configuration
====================
Your might want to specify a family, your router belongs to.
There are two possibilities: create new family or joing to existing.
New family
-----------
You must create family self-signed certificate and key.
The only key type supposted is prime256v1.
Use the following list of commands:
openssl ecparam -name prime256v1 -genkey -out <your family name>.key
openssl req -new -key <your family name>.key -out <your family name>.csr
touch v3.ext
openssl x509 -req -days 3650 -in <your family name>.csr -signkey <your family name>.key -out <your family name>.crt -extfile v3.ext
Specify <your family name>.family.i2p.net for CN (Common Name) when requested.
Once you are done with it place <your-family-name>.key and <your-family-name>.crt to <ip2d data>/family folder (for exmple ~/.i2pd/family).
You should provide these two files to other members joining your family.
If you want to register you family and let I2P network recorgnize it, create pull request for you .crt file into contrib/certificate/family.
It will appear in i2pd and I2P next releases packages. Dont place .key file, it must be shared between you family members only.
How to join existing family
---------------------------
Once you and that family agree to do it, they must give you .key and .crt file and you must place in <i2pd datadir>/certificates/family/ folder.
Publish your family
-------------------
Run i2pd with parameter 'family=<your-family-name>', make sure you have <your-family-name>.key and <your-family-name>.crt in your 'family' folder.
If everything is set properly, you router.info will contain two new fields: 'family' and 'family.sig'.
Otherwise your router will complain on startup with log messages starting with "Family:" prefix and severity 'warn' or 'error'.

114
docs/hacking.md

@ -1,114 +0,0 @@ @@ -1,114 +0,0 @@
# Hacking on I2PD
This document contains notes compiled from hacking on i2pd
## prerequisites
This guide assumes:
* a decent understanding of c++
* basic understanding of how i2p works at i2np level and up
## general structure
Notes on multithreading
* every compontent runs in its own thread
* each component (usually) has a public function `GetService()` which can be used to obtain the `boost::asio::io_service` that it uses.
* when talking between components/threads, **always** use `GetService().post()` and be mindfull of stack allocated memory.
### NetDb
#### NetDb.h
The `i2p::data::netdb` is a `i2p::data::NetDb` instance processes and dispatches *inbound* i2np messages passed in from transports.
global singleton at `i2p::data::netdb` as of 2.10.1
#### NetDbRequests.h
For Pending RouterInfo/LeaseSet lookup and store requests
### ClientContext
#### ClientContext.h
`i2p::client::ClientContext` spawns all destinations used by the i2p router including the shared local destination.
global singleton at `i2p::client::context` as of 2.10.1
### Daemon
File: Daemon.cpp
`i2p::util::Daemon_Singleton_Private` subclasses implement the daemon start-up and tear-down, creates Http Webui and i2p control server.
### Destinations
#### Destination.h
each destination runs in its own thread
##### i2p::client::LeaseSetDestination
Base for `i2p::client::ClientDestination`
##### i2p::client::ClientDestination
Destination capable of creating (tcp/i2p) streams and datagram sessions.
#### Streaming.h
##### i2p::stream::StreamingDestination
Does not implement any destination related members, the name is a bit misleading.
Owns a `i2p::client::ClientDestination` and runs in the destination thread.
Anyone creating or using streams outside of the destination thread **MUST** be aware of the consequences of multithreaded c++ :^)
If you use streaming please consider running all code within the destination thread using `ClientDestination::GetService().post()`
#### Garlic.h
Provides Inter-Destination routing primatives.
##### i2p::garlic::GarlicDestination
sublcass of `i2p::client::LeaseSetDestination` for sending messages down shared routing paths.
##### i2p::garlic::GarlicRoutingSession
a point to point conversation between us and 1 other destination.
##### i2p::garlic::GarlicRoutingPath
A routing path currently used by a routing session. specifies which outbound tunnel to use and which remote lease set to use for `OBEP` to `IBGW` inter tunnel communication.
members:
* outboundTunnel (OBEP)
* remoteLease (IBGW)
* rtt (round trip time)
* updatedTime (last time this path's IBGW/OBEP was updated)
* numTimesUsesd (number of times this path was used)
### Transports
each transport runs in its own thread
#### Transports.h
`i2p::transport::Transports` contains NTCP and SSU transport instances

41
docs/index.rst

@ -1,41 +0,0 @@ @@ -1,41 +0,0 @@
i2pd
====
i2pd is a full-featured C++ implementation of
`I2P <https://geti2p.net/en/about/intro>`_ client.
* `Website <http://i2pd.website>`_
* `GitHub <https://github.com/PurpleI2P/i2pd>`_
* `Wiki <https://github.com/PurpleI2P/i2pd/wiki>`_
* `Tickets/Issues <https://github.com/PurpleI2P/i2pd/issues>`_
* `Twitter <https://twitter.com/i2porignal>`_
Installing
----------
The easiest way to install i2pd is by using
`precompiled binaries <https://github.com/PurpleI2P/i2pd/releases/latest>`_.
See documentation for how to build i2pd from source on your OS.
Using i2pd
----------
See documentation and
`example config file <https://github.com/PurpleI2P/i2pd/blob/openssl/docs/i2pd.conf>`_.
Contents:
---------
.. toctree::
:maxdepth: 2
building/requirements
building/unix
building/windows
building/cross
building/android
building/ios
configuration
family
usage

171
docs/usage.md

@ -1,171 +0,0 @@ @@ -1,171 +0,0 @@
Usage and tutorials
===================
i2pd can be used for:
* [anonymous websites](#browsing-and-hosting-websites)
* [anonymous chats](#using-and-hosting-chat-servers)
* [anonymous file sharing](#file-sharing)
and many more.
## Starting, stopping and reloading configuration
After you have built i2pd from source, just run a binary:
./i2pd
To display all available options:
./i2pd --help
i2pd can be controlled with signals. Process ID by default is written to file `~/.i2pd/i2pd.pid` or `/var/run/i2pd/i2pd.pid`.
You can use `kill` utility to send signals like this:
kill -INT $( cat /var/run/i2pd/i2pd.pid )
i2pd supports the following signals:
* INT - Graceful shutdown. i2pd will wait for 10 minutes and stop. Send second INT signal to shutdown i2pd immediately.
* HUP - Reload configuration files.
### systemd unit
Some binary Linux packages have a systemd control unit, so it is possible to managage i2pd with it.
Start/stop i2pd:
sudo systemctl start i2pd.service
sudo systemctl stop i2pd.service
Enable/disable i2pd to be started on bootup:
sudo systemctl enable i2pd.service
sudo systemctl disable i2pd.service
## Configuring i2pd
See [configuration documentation](/page/configuration.html).
## Browsing and hosting websites
### Browse anonymous websites
To browse anonymous websites inside Invisible Internet, configure your web browser to use HTTP proxy 127.0.0.1:4444 (available by default in i2pd).
In Firefox: Preferences -> Advanced -> Network tab -> Connection Settings -> choose Manual proxy configuration, Enter HTTP proxy 127.0.0.1, Port 4444
In Chromium: run chromium executable with key
chromium --proxy-server="http://127.0.0.1:4444"
Note that if you wish to stay anonymous too you'll need to tune your browser for better privacy. Do your own research, [can start here](http://www.howtogeek.com/102032/how-to-optimize-mozilla-firefox-for-maximum-privacy/).
Big list of Invisible Internet websites can be found at [identiguy.i2p](http://identiguy.i2p).
### Host anonymous website
If you wish to run your own website in Invisible Internet, follow those steps:
1) Run your webserver and find out which host:port it uses (for example, 127.0.0.1:8080).
2) Configure i2pd to create HTTP server tunnel. Put in your ~/.i2pd/tunnels.conf file:
[anon-website]
type = http
host = 127.0.0.1
port = 8080
keys = anon-website.dat
3) Restart i2pd.
4) Find b32 destination of your website.
Go to webconsole -> [I2P tunnels page](http://127.0.0.1:7070/?page=i2p_tunnels). Look for Sever tunnels and you will see address like \<long random string\>.b32.i2p next to anon-website.
Website is now available in Invisible Internet by visiting this address.
5) (Optional) Register short and rememberable .i2p domain on [inr.i2p](http://inr.i2p).
## Using and hosting chat servers
### Running anonymous IRC server
1) Run your IRC server software and find out which host:port it uses (for example, 127.0.0.1:5555).
For small private IRC servers you can use [miniircd](https://github.com/jrosdahl/miniircd), for large public networks [UnreadIRCd](https://www.unrealircd.org/).
2) Configure i2pd to create IRC server tunnel.
Simplest case, if your server does not support WebIRC, add this to ~/.i2pd/tunnels.conf:
[anon-chatserver]
type = irc
host = 127.0.0.1
port = 5555
keys = chatserver-key.dat
And that is it.
Alternatively, if your IRC server supports WebIRC, for example, UnreadIRCd, put this into UnrealIRCd config:
webirc {
mask 127.0.0.1;
password your_password;
};
Also change line:
modes-on-connect "+ixw";
to
modes-on-connect "+iw";
And this in ~/.i2pd/tunnels.conf:
[anon-chatserver]
type = irc
host = 127.0.0.1
port = 5555
keys = chatserver-key.dat
webircpassword = your_password
3) Restart i2pd.
4) Find b32 destination of your anonymous IRC server.
Go to webconsole -> [I2P tunnels page](http://127.0.0.1:7070/?page=i2p_tunnels). Look for Sever tunnels and you will see address like \<long random string\>.b32.i2p next to anon-chatserver.
Clients will use this address to connect to your server anonymously.
### Connect to anonymous IRC server
To connect to IRC server at *walker.i2p*, add this to ~/.i2pd/tunnels.conf:
[IRC2]
type = client
address = 127.0.0.1
port = 6669
destination = walker.i2p
#keys = walker-keys.dat
Restart i2pd, then connect to irc://127.0.0.1:6669 with your IRC client.
## File sharing
You can share and download torrents with [Transmission-I2P](https://github.com/l-n-s/transmission-i2p).
Alternative torrent-clients are [Robert](http://en.wikipedia.org/wiki/Robert_%28P2P_Software%29) and [Vuze](https://en.wikipedia.org/wiki/Vuze).
Robert uses BOB protocol, i2pd must be run with parameter --bob.enabled=true.
Vuze uses I2CP protocol, i2pd must be run with parameter --i2cp.enabled=true.
Also, visit [postman tracker](http://tracker2.postman.i2p).
Loading…
Cancel
Save