From b10c6e7c32528d632b4052da5114ce3efd4d9f13 Mon Sep 17 00:00:00 2001
From: Amna <amna.snene@savoirfairelinux.com>
Date: Mon, 25 Sep 2023 11:12:35 -0400
Subject: [PATCH] tools: add readme dsh and dnc

Change-Id: I8ba6bc51c6c6de4a11d9529bb8a52d002f7569e0
---
 CMakeLists.txt      |  5 +++++
 tools/dnc/README.md | 34 ++++++++++++++++++++++++++++++
 tools/dnc/dnc.1     | 51 +++++++++++++++++++++++++++++++++++++++++++++
 tools/dsh/README.md | 29 ++++++++++++++++++++++++++
 tools/dsh/dsh.1     | 44 ++++++++++++++++++++++++++++++++++++++
 5 files changed, 163 insertions(+)
 create mode 100644 tools/dnc/README.md
 create mode 100644 tools/dnc/dnc.1
 create mode 100644 tools/dsh/README.md
 create mode 100644 tools/dsh/dsh.1

diff --git a/CMakeLists.txt b/CMakeLists.txt
index d2a713f..6086fb4 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -253,6 +253,11 @@ if (BUILD_TOOLS AND NOT MSVC)
     target_link_libraries(upnpctrl PRIVATE dhtnet fmt::fmt readline)
     target_include_directories(upnpctrl PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/tools)
     install(TARGETS upnpctrl RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
+
+    install(FILES
+        tools/dnc/dnc.1
+        tools/dsh/dsh.1
+    DESTINATION ${CMAKE_INSTALL_MANDIR})
 endif()
 
 if (BUILD_BENCHMARKS)
diff --git a/tools/dnc/README.md b/tools/dnc/README.md
new file mode 100644
index 0000000..6b1eb56
--- /dev/null
+++ b/tools/dnc/README.md
@@ -0,0 +1,34 @@
+# dnc - Distributed nc
+
+## Overview
+
+**dnc** is a versatile command-line utility that enables network connectivity between peers in a Distributed Hash Table (DHT) network. It allows you to establish connections with other peers or devices and create TCP sockets on remote devices, similar to the traditional `nc` (netcat) utility.
+
+**Key Features**:
+- Create TCP sockets on remote devices.
+- Establish network connections between peers in a DHT network.
+- Supports TURN (Traversal Using Relays around NAT) server for network traversal.
+- Provides identity management for secure DHT interactions.
+
+### Options
+
+**dnc** accepts the following command-line options:
+
+- `-h, --help`: Display help information for using **dnc**.
+- `-V, --version`: Display the version information of **dnc**.
+- `-p, --port <PORT>`: Specify the port number to use for network connections. This option requires an argument. The default value is 22 if not specified.
+- `-i, --ip <REMOTE_IP>`: Specify the IP address or hostname of the remote host or device to connect to. This option requires an argument. The default value is "127.0.0.1" if not specified.
+- `-l, --listen`: Run **dnc** in listen mode, allowing the program to accept incoming network connections and perform network-related tasks on request.
+- `-b, --bootstrap <BOOTSTRAP_ADDRESS>`: Specify the address of a bootstrap node to connect to an existing DHT network. This option requires an argument. The default value is "bootstrap.jami.net" if not specified.
+- `-I, --id_path <IDENTITY_PATH>`: Specify the path to the identity file, which contains information about the peer's identity and is used for DHT network interactions. This option requires an argument. The default value is "~/.dhtnet" if not specified.
+- `-t, --turn_host <TURN_SERVER>`: Specify the hostname or IP address of the TURN (Traversal Using Relays around NAT) server to use for network traversal. This option requires an argument. The default value is "turn.jami.net" if not specified.
+- `-u, --turn_user <TURN_USERNAME>`: Specify the username for authentication with the TURN server. This option requires an argument. The default value is "ring" if not specified.
+- `-w, --turn_pass <TURN_PASSWORD>`: Specify the password for authentication with the TURN server. This option requires an argument. The default value is "ring" if not specified.
+- `-r, --turn_realm <TURN_REALM>`: Specify the realm for authentication with the TURN server. This option requires an argument. The default value is "ring" if not specified.
+- `<PEER_ID>`: The peer ID argument is required when not running in listen mode. It specifies the ID of the target peer or device in the DHT network with which the connection should be established.
+
+For example, to connect to a remote device with a specific TURN server and identity file, you can use the following command:
+
+```shell
+dnc -i <REMOTE_IP> -p <PORT> -t <TURN_SERVER> -u <TURN_USERNAME> -w <TURN_PASSWORD> -r <TURN_REALM> -I <IDENTITY_PATH> <PEER_ID>
+```
\ No newline at end of file
diff --git a/tools/dnc/dnc.1 b/tools/dnc/dnc.1
new file mode 100644
index 0000000..ef79c2e
--- /dev/null
+++ b/tools/dnc/dnc.1
@@ -0,0 +1,51 @@
+.TH DNC 1 "September 2023" "Version 1.0" "Distributed nc"
+.SH NAME
+dnc \- Distributed nc
+.SH SYNOPSIS
+.B dnc
+.RI "[-h|--help] [-V|--version] [-p|--port <PORT>] [-i|--ip <REMOTE_IP>] [-l|--listen] [-b|--bootstrap <BOOTSTRAP_ADDRESS>] [-I|--id_path <IDENTITY_PATH>] [-t|--turn_host <TURN_SERVER>] [-u|--turn_user <TURN_USERNAME>] [-w|--turn_pass <TURN_PASSWORD>] [-r|--turn_realm <TURN_REALM>]"
+.RI "<peer-id>"
+.SH DESCRIPTION
+\fBdnc\fR is a versatile command-line utility that enables network connectivity between peers in a Distributed Hash Table (DHT) network. It allows you to establish connections with other peers or devices and create TCP sockets on remote devices, similar to the traditional \fBnc\fR (netcat) utility.
+.SH OPTIONS
+.TP
+.B \-h, \-\-help
+Display help information for using \fBdnc\fR.
+.TP
+.B \-V, \-\-version
+Display the version information of \fBdnc\fR.
+.TP
+.B \-p, \-\-port <PORT>
+Specify the port number to use for network connections. This option requires an argument. The default value is 22 if not specified.
+.TP
+.B \-i, \-\-ip <REMOTE_IP>
+Specify the IP address or hostname of the remote host or device to connect to. This option requires an argument. The default value is "127.0.0.1" if not specified.
+.TP
+.B \-l, \-\-listen
+Run \fBdnc\fR in listen mode, allowing the program to accept incoming network connections and perform network-related tasks on request.
+.TP
+.B \-b, \-\-bootstrap <BOOTSTRAP_ADDRESS>
+Specify the address of a bootstrap node to connect to an existing DHT network. This option requires an argument and is only valid when not running in listen mode. The default value is "bootstrap.jami.net" if not specified.
+.TP
+.B \-I, \-\-id_path <IDENTITY_PATH>
+Specify the path to the identity file, which contains information about the peer's identity and is used for DHT network interactions. This option requires an argument. The default value is "~/.dhtnet" if not specified.
+.TP
+.B \-t, \-\-turn_host <TURN_SERVER>
+Specify the hostname or IP address of the TURN (Traversal Using Relays around NAT) server to use for network traversal. This option requires an argument. The default value is "turn.jami.net" if not specified.
+.TP
+.B \-u, \-\-turn_user <TURN_USERNAME>
+Specify the username for authentication with the TURN server. This option requires an argument. The default value is "ring" if not specified.
+.TP
+.B \-w, \-\-turn_pass <TURN_PASSWORD>
+Specify the password for authentication with the TURN server. This option requires an argument. The default value is "ring" if not specified.
+.TP
+.B \-r, \-\-turn_realm <TURN_REALM>
+Specify the realm for authentication with the TURN server. This option requires an argument. The default value is "ring" if not specified.
+.SH EXAMPLE
+To connect to a remote device with a specific TURN server and identity file, you can use the following command:
+.PP
+.B
+dnc -i <REMOTE_IP> -p <PORT> -t <TURN_SERVER> -u <TURN_USERNAME> -w <TURN_PASSWORD> -r <TURN_REALM> -I <IDENTITY_PATH> <peer-id>
+.SH SEE ALSO
+.PP
+.BR nc (1)
diff --git a/tools/dsh/README.md b/tools/dsh/README.md
new file mode 100644
index 0000000..af92142
--- /dev/null
+++ b/tools/dsh/README.md
@@ -0,0 +1,29 @@
+# dsh - Distributed Shell
+
+**dsh** is a Distributed Shell program that enables peers to establish connections with other peers in a Distributed Hash Table (DHT) network and execute a binary on the remote target.
+
+## Overview
+
+**dsh** allows you to:
+
+- Execute commands on remote peers in a DHT network.
+- Establish connections with peers and execute binaries on their side.
+
+
+### Options
+
+**dsh** accepts the following command-line options:
+
+- `-h, --help`: Display help information for using **dsh**.
+- `-V, --version`: Display the version information of **dsh**.
+- `-l, --listen`: Run **dsh** in listen mode, allowing the program to accept incoming network connections and perform network-related tasks on request.
+- `-b, --bootstrap <BOOTSTRAP_ADDRESS>`: Specify the address of a bootstrap node to connect to an existing DHT network. This option requires an argument. The default value is "bootstrap.jami.net" if not specified.
+- `-s, --binary <BINARY_PATH>`: Specify the path to the binary that should be executed on the remote target when a connection is established. This option requires an argument. The default value is "bash" if not specified.
+- `-I, --id_path <IDENTITY_PATH>`: Specify the path to the identity file, which contains information about the peer's identity and is used for DHT network interactions. This option requires an argument. The default value is "~/.dhtnet" if not specified.
+- `<PEER_ID>`: The peer ID argument is required when not running in listen mode. It specifies the ID of the target peer or device in the DHT network with which the connection should be established.
+
+For example, to connect to a remote peer and specify a custom bootstrap node, binary, and identity file, you can use the following command:
+
+```shell
+dsh -b <BOOTSTRAP_ADDRESS> -s <BINARY_PATH> -I <IDENTITY_PATH> <PEER_ID>
+```
\ No newline at end of file
diff --git a/tools/dsh/dsh.1 b/tools/dsh/dsh.1
new file mode 100644
index 0000000..80fda57
--- /dev/null
+++ b/tools/dsh/dsh.1
@@ -0,0 +1,44 @@
+.TH DSH 1 "September 2023" "Version 1.0" "Distributed Shell"
+.SH NAME
+dsh \- Distributed Shell
+.SH SYNOPSIS
+.B dsh
+.RI "[-h|--help] [-V|--version] [-l|--listen] [-b|--bootstrap <BOOTSTRAP_ADDRESS>] [-s|--binary <BINARY_PATH>] [-I|--id_path <IDENTITY_PATH>]"
+.RI "<PEER_ID>"
+.SH DESCRIPTION
+\fBdsh\fR is a Distributed Shell program that enables peers to establish connections with other peers in a Distributed Hash Table (DHT) network and execute a binary on the remote target.
+.PP
+\fBdsh\fR allows you to:
+.IP
+- Execute commands on remote peers in a DHT network.
+- Establish connections with peers and execute binaries on their side.
+.SH OPTIONS
+.TP
+.B \-h, \-\-help
+Display help information for using \fBdsh\fR.
+.TP
+.B \-V, \-\-version
+Display the version information of \fBdsh\fR.
+.TP
+.B \-l, \-\-listen
+Run \fBdsh\fR in listen mode, allowing the program to accept incoming network connections and perform network-related tasks on request.
+.TP
+.B \-b, \-\-bootstrap <BOOTSTRAP_ADDRESS>
+Specify the address of a bootstrap node to connect to an existing DHT network. This option requires an argument. The default value is "bootstrap.jami.net" if not specified.
+.TP
+.B \-s, \-\-binary <BINARY_PATH>
+Specify the path to the binary that should be executed on the remote target when a connection is established. This option requires an argument. The default value is "bash" if not specified.
+.TP
+.B \-I, \-\-id_path <IDENTITY_PATH>
+Specify the path to the identity file, which contains information about the peer's identity and is used for DHT network interactions. This option requires an argument. The default value is "~/.dhtnet" if not specified.
+.TP
+.B <PEER_ID>
+The peer ID argument is required when not running in listen mode. It specifies the ID of the target peer or device in the DHT network with which the connection should be established.
+.SH EXAMPLE
+To connect to a remote peer and specify a custom bootstrap node, binary, and identity file, you can use the following command:
+.PP
+.B
+dsh -b <BOOTSTRAP_ADDRESS> -s <BINARY_PATH> -I <IDENTITY_PATH> <PEER_ID>
+.SH SEE ALSO
+.PP
+.BR dshd (1)
-- 
GitLab