From 0d729649c09fd00f8b2cb2a9b78366245dff2dba Mon Sep 17 00:00:00 2001 From: polistern <55511995+polistern@users.noreply.github.com> Date: Tue, 16 Nov 2021 04:06:55 +0000 Subject: [PATCH] Start to fill out. (#1) Co-authored-by: polistern --- .gitignore | 1 + README.md | 4 +- docs/devs/bote/desc.md | 0 docs/devs/bote/version5.md | 7 ++ docs/devs/building/requirements.md | 9 ++ docs/devs/building/unix.md | 43 ++++++++++ docs/index.md | 29 +++++++ docs/user-guide/configuration.md | 127 +++++++++++++++++++++++++++++ docs/user-guide/install.md | 11 +++ docs/user-guide/run.md | 0 mkdocs.yml | 29 +++++++ 11 files changed, 259 insertions(+), 1 deletion(-) create mode 100644 .gitignore create mode 100644 docs/devs/bote/desc.md create mode 100644 docs/devs/bote/version5.md create mode 100644 docs/devs/building/requirements.md create mode 100644 docs/devs/building/unix.md create mode 100644 docs/index.md create mode 100644 docs/user-guide/configuration.md create mode 100644 docs/user-guide/install.md create mode 100644 docs/user-guide/run.md create mode 100644 mkdocs.yml diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..45ddf0a --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +site/ diff --git a/README.md b/README.md index 44dfe7d..d8ceb35 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,4 @@ -# pboted_docs +# pboted docs pboted documentation + +Feel free to open an issue or create a pull-request. diff --git a/docs/devs/bote/desc.md b/docs/devs/bote/desc.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/devs/bote/version5.md b/docs/devs/bote/version5.md new file mode 100644 index 0000000..ddadde9 --- /dev/null +++ b/docs/devs/bote/version5.md @@ -0,0 +1,7 @@ +# Protocol version 5 + +At the moment, PeerList packets of 5th version have been implemented to support current types of I2P destination. +PeerList packets of 4th version are supported, older Java nodes respond but do not send requests due to protocol restrictions at DSA I2P destinations. +You can see the implementation details in `docs/techdoc_v5 (draft).txt` file. + +Proposals for improving the 5th version of the protocol are accepted for consideration. \ No newline at end of file diff --git a/docs/devs/building/requirements.md b/docs/devs/building/requirements.md new file mode 100644 index 0000000..2a7c193 --- /dev/null +++ b/docs/devs/building/requirements.md @@ -0,0 +1,9 @@ +# Build requirements + +In general, for building **pboted** you need several things: + +* compiler with c++17 support (for example: gcc >= 4.8, clang) +* cmake >= 3.7 +* boost >= 1.62 +* openssl library +* zlib library (openssl already depends on it) diff --git a/docs/devs/building/unix.md b/docs/devs/building/unix.md new file mode 100644 index 0000000..352340c --- /dev/null +++ b/docs/devs/building/unix.md @@ -0,0 +1,43 @@ +# Building on Unix systems + +**Supported systems:** + +* GNU/Linux + - Debian / Ubuntu (with packaging) + +## CMake Options + + +## Debian/Ubuntu: + +_Tested with Debian 10 and Ubuntu 20.04._ + +- Install development libraries and tools: + +``` +sudo apt install git cmake build-essential zlib1g-dev libssl-dev \ +libboost-filesystem-dev libboost-system-dev libboost-program-options-dev \ +libboost-date-time-dev libboost-thread-dev libmimetic-dev +``` + +- Clone repository: + +``` +git clone https://github.com/polistern/pboted.git +cd pboted +git submodule update --init +``` + +- Build: + +``` +cd build +cmake -DCMAKE_BUILD_TYPE=Release +make +``` + +- Put binary to `/usr/sbin/` + +``` +sudo mv pboted /usr/sbin/pboted +``` \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..726c461 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,29 @@ +# Plus Bote Daemon + + + +# pboted + +pboted (Plus Bote Daemon) - is a standalone C++ implementation of I2P-Bote (server-less Kademlia DHT-based email) protocol. +Interaction with the I2P network occurs through the SAMv3 interface (tested with i2pd and Java I2P). + +## Features + +- Sending and receiving emails +- Basic support for short recipient names +- Elliptic Curve encryption (ECDH-256/ECDSA-256/AES-256/SHA-256) +- Runnable as daemon or as user service +- SMTP / POP3 (basic support, work in progress) + +## Planned Features + +- Custom per identity/user email folders +- Sending email anonymously +- Delivery confirmation +- Sending and receiving via relays, similar to Mixmaster +- CLI interface and tools +- Interfaces for interaction with third-party applications (IMAP, etc.) + +## Resources +- [Documentation](https://pboted.readthedocs.io/en/latest/) +- [Tickets/Issues](https://github.com/polistern/pboted/issues) diff --git a/docs/user-guide/configuration.md b/docs/user-guide/configuration.md new file mode 100644 index 0000000..101d34c --- /dev/null +++ b/docs/user-guide/configuration.md @@ -0,0 +1,127 @@ +## Configuration + +### The pboted needs I2P router + +- Install and run i2pd +- Enable SAM API in i2pd. Edit in i2pd.conf: + +``` +[sam] +enabled = true +``` + +- Restart i2pd +- Local TCP port 7656 and UDP port 7655 should be available + +### User service configuration + +- Copy example config from `contrib/pboted.conf` to `~/.pboted/pboted.conf`: + +``` +cp contrib/pboted.conf ~/.pboted/pboted.conf` +``` + +- Edit the config to suit your needs. The file is well documented, comments will help you. +- Now you can run application: + +``` +./pboted --conf ~/.pboted/pboted.conf +``` + +### Unix daemon configuration [recommended] + +- Create `/etc/pboted` directory: + +``` +sudo mkdir /etc/pboted +``` + +- Copy example config from `contrib/pboted.conf` to `~/.pboted/pboted.conf`: + +``` +sudo cp contrib/pboted.conf /etc/pboted/pboted.conf` +``` + +- Edit the config to suit your needs. The file is well documented, comments will help you. +- Create user, data and logs directories: + +``` +sudo useradd pboted -r -s /usr/sbin/nologin +sudo mkdir /var/lib/pboted +sudo chown -R pboted: /var/lib/pboted +sudo mkdir /var/log/pboted +sudo chown -R pboted: /var/log/pboted +``` + +- Copy example systemd service from `contrib/pboted.service` to `/lib/systemd/system/pboted.service`: + +``` +sudo cp contrib/pboted.service /lib/systemd/system/pboted.service` +``` + +- Reload daemons configuration and start unit: + +``` +sudo systemctl daemon-reload +sudo systemctl start pboted.service +``` + +- Now you can see in log files that all works. Also, you can see the status of the SAM session in the I2P Router console. + +## Usage + +You may need the utilities from the `utils` directory to work with **pboted**. +In the future, their list will grow. +There are plans to transfer all means for interaction into a separate CLI utility. + +You can only continue to use your Java I2P-Bote identities if: + +- your address is created using the ECDH-256/ECDSA-256/AES-256/SHA-256 algorithm (others are not supported yet) +- identities file is not encrypted (encrypted files are not supported yet) + +### Sending email + +#### SMTP + +To be able to send email through SMTP you need to: + +- Fill [smtp] section in configuration file: + +``` +[smtp] +enabled = true +address = 127.0.0.1 +port = 25 +``` + +- Restart the **pboted** to apply the settings +- After loading, you be able to connect to the specified SMTP port manually or with your mail client + +#### Via `outbox` directory + +- Prepare plain test message +- Format it with `message_formatter` +- Put result file to `outbox` directory in pboted working directory +- pboted will automatically check `outbox` and send email +- After sending email file will be moved to `sent` directory + +### Receiving email + +After starting with a generated identity the application will begin its normal job of searching for mail. +If mail for identity are found, they will be placed in the `inbox` directory. + +#### POP3 + +To be able to receive email through POP3 you need to: + +- Fill [pop3] section in configuration file: + +``` +[pop3] +enabled = true +address = 127.0.0.1 +port = 110 +``` + +- Restart the **pboted** to apply the settings +- After loading, you be able to connect to the specified POP3 port manually or with your mail client. \ No newline at end of file diff --git a/docs/user-guide/install.md b/docs/user-guide/install.md new file mode 100644 index 0000000..c2dba00 --- /dev/null +++ b/docs/user-guide/install.md @@ -0,0 +1,11 @@ +# Installing + +## Building from source + +## Ubuntu + +You can install binary packages from the [latest release page](https://github.com/polistern/pboted/releases/latest). + +## Debian + +You can install binary packages from the [latest release page](https://github.com/polistern/pboted/releases/latest). diff --git a/docs/user-guide/run.md b/docs/user-guide/run.md new file mode 100644 index 0000000..e69de29 diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..5e92c4c --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,29 @@ +site_name: pboted documentation +site_url: https://pboted.readthedocs.io +site_description: pboted documentation +site_author: polistern + +repo_url: https://github.com/polistern/pboted_docs + +nav: +- Home: index.md +- User Guide: + - Installing: user-guide/install.md + - Running: user-guide/run.md + - Configuring: user-guide/configuration.md + #- FAQ: user-guide/FAQ.md +- Developer Section: + - Building from source: + - Requirements: devs/building/requirements.md + - Unix: devs/building/unix.md + - Bote Protocol: + - Desc: devs/bote/desc.md + - Version 5: devs/bote/version5.md +#- About: +# - Community: about/community.md +# - History: about/history.md +# - License: about/license.md +# - Contributing: about/contributing.md + +copyright: CC-BY-SA 4.0, Maintained by polistern +theme: readthedocs