From 616796b6f783888d71dcf7670c1a956d066330e9 Mon Sep 17 00:00:00 2001 From: Louis Maillard <louis.maillard@savoirfairelinux.com> Date: Thu, 10 Oct 2024 11:21:55 -0400 Subject: [PATCH] docs: add documentation about using dnc + crtmgr There was missing documentation on how to use the tools as an DevOps or SysAdmin. It now explain where to download, how to setup client and server, as well as basics about security in the tool. Change-Id: I7271d2dc37aa65459de16d0cf8a5cd41628e13e8 --- README.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 59 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 475dde2..a653c7a 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ DHTNet is a C++17 library designed to serve as a network overlay that provides an IP network abstraction. Its main objective is to establish secure peer-to-peer connections using public-key authentication. -Dhtnet allows you to connect with a device simply by knowing its public key and efficiently manages peer discovery and connectivity establishment, including NAT traversal. +DHTnet allows you to connect with a device simply by knowing its public key and efficiently manages peer discovery and connectivity establishment, including NAT traversal. ## Features @@ -24,7 +24,64 @@ For detailed information on using DHTNet, consult our documentation: - [ConnectionManager Wiki](https://docs.jami.net/en_US/developer/jami-concepts/connection-manager.html) -## Getting Started +## Getting Started using dhtnet package + +You can download latest and/or stable builds from https://dhtnet.sfl.io. +To install .deb, you can use `apt install dhtnet-xxx.deb`, and .rpm can be installed using `dnf install dhtnet_xxx.rpm`. +On fedora, you may require to install EPEL using `dnf install epel-release`. +On Redhat / Almalinux, EPEL may also be required, look at each distribution to find the installation command. + + +### Setup instructions for server: + +1. Create a server config and keys using `dhtnet-crtmgr --interactive` (run as root or with sudo is required). +2. Choose **server** and then use default configuration, or tweak values if you prefer. +3. If you want to review or edit configuration (to enable verbose mode for exemple), open `/etc/dhtnet/dnc.yaml`. +4. When ready, turn your server ON using `systemctl start dnc`. You can verify status using `systemctl status dnc`. + +Your **server ID** (needed for clients to connect at you) is printed during the `dhtnet-crtmgr` setup, and is printed at start of logs when starting server with `systemctl start dnc`. +If needed, you can get it anytime using `dhtnet-crtmgr -a -c /etc/dhtnet/id/id-server.crt -p /etc/dhtnet/id/id-server.pem`. + + +### Setup instructions for client: + +1. Create a client config and keys using `dhtnet-crtmgr --interactive` (run as your user is preffered). +2. Choose **client** for the first answer (default) +3. When asked to use server CA, answer depend on your use case: + - If server and client are setup on same host, answer **yes** is possible. + - If you are installing only the client, then answer **no**. + - If you want to enforce security but server is on different host, answer **no** and change keys later (see `anonymous` below). +4. Continue using default configuration or by changing values when wanted. +5. If you want to review or edit configuration (to enable verbose mode for example), open `$HOME/.dnc/config.yml`. + +To connect, you can use `dnc -d $HOME/.dnc/config.yml <server ID>`. +If you answered **yes** at question about setting up ssh for you, then you can use `ssh <user>@dnc/<server ID>` to reach SSH on server using DNC layer. + + +### About security and `anonymous` setting: + +By default, server allow anyone to establish connection on your server. This is why server don't start by default, and only SSH is allowed. +In server setting, you will find `anonymous` boolean. If you host a public host, keeping `true` is a good choice, but if only a set of device +are allowed to connect to your server, then setting `false` is a better security. +For client, in order to reach a server with `anonymous: false`, it require the client key to be signed by server CA certificate. +Here is how to do it: + +1. Get server CA certificate by going in `/etc/dhtnet/CA/` and copy `ca-server.crt` and `ca-server.pem`. +2. Generate a key in `MYPATH` using server certificate :`dhtnet-crtmgr -o MYPATH -c ca-server.crt -p ca-server.pem` +3. Copy the key generated in `MYPATH` in the client folder, for example `$HOME/.dnc/certificate.crt` and `$HOME/.dnc/certificate.pem` +4. If using a different path than example at step 3, edit `$HOME/.dnc/config.yml` to replace `certificate: MYPATH/certificate.crt` and `privateKey: MYPATH/certificate.pem`. + +Don't forget to turn `anonymous` to `false` and restart server to take effect using `systemctl restart dnc` + +Another security config is the `authorized_services` configuration on server, associated with `ip` and `port` on client. +When DNC establish a connection to remote host, it then try to reach `ip:port` **from this remote host**. +To enable accessing HTTP server running on server host, allow `127.0.0.1:80` on server and use `--port 80` on client for example. + + +--- + + +## Getting Started with library Get started with DHTNet by building and installing the library: -- GitLab