63 lines
3.7 KiB
Markdown
63 lines
3.7 KiB
Markdown
# tnet
|
|
|
|
Purpose
|
|
=======
|
|
A minimalist and hackable file transfer (and messages) tool for local network
|
|
|
|
Description
|
|
===========
|
|
+ Built with python's standard library with no 3rd-party dependencies.
|
|
|
|
+ Utilizes the sockets and selectors modules for networking.
|
|
|
|
+ Due to the use of the selectors module the app is async and single-threaded.
|
|
|
|
+ Requires 2 ports to be opened (can be configured which ones).
|
|
|
|
+ Does not preserve file attributes when transferring a file.
|
|
|
|
+ Designed for the local network only, thus no encryption is implemented.
|
|
|
|
+ Tested with python 3.8, 3.11 and 3.12 on Ubuntu 20.04, Debian 12 and Alpine 3.19
|
|
|
|
+ Licensed under **GPLv3** license
|
|
|
|
The architecture looks as follows:
|
|
there are 4 sockets - one for listening incoming TCP connections, one for listening incoming UDP connections (discovery mechanism),
|
|
the other 2 are UNIX sockets - one for accepting the local commands (send file, send notification, discover who is online, etc.) and the second one is
|
|
for distributing events like incoming notifications, file transfer progress (both incoming and outcoming), errors, etc.
|
|
First 2 sockets are mandatory and they are used by a daemon for communication over the local network, the rest is optional and used for communication
|
|
between cli and daemon on the same machine.
|
|
|
|
There are only 4 main source files: ``protocol.py``, ``daemon.py``, ``cli.py`` and ``util.py``, their descriptions are in the corresponding files.
|
|
|
|
Typical workflow:
|
|
1) daemon is started and listens for the configured TCP and UDP ports, and one local UNIX socket for incoming commands
|
|
2) a separate cli instance sends the 'discover' command to the UNIX socket to get a list of available machines in the local network
|
|
3) the daemon in turn gets this command and broadcasts the 'discover' request via UDP
|
|
4) a daemon on another machine (if any) gets this request on the UDP socket it listens to and replies directly to the requester via TCP with its IPv4 and host name
|
|
5) the daemon on the first machine gets it and replies to the cli via the same UNIX socket
|
|
6) then this info can be used via cli to send a file or notification, again the command is sent to the daemon via the UNIX socket
|
|
7) daemon sends the file or notification via TCP, and optionally can report the progress (or errors) back to ANOTHER UNIX socket
|
|
8) counterparty daemon processes the incoming data over TCP and also can optionally report the progress on a UNIX socket, called events socket
|
|
9) once file is received it is moved from ``/tmp`` to the configured downloads directory, if transfer fails - the file gets removed from ``/tmp``
|
|
|
|
Configuration
|
|
=============
|
|
The following env variables can be set for **daemon**:
|
|
+``EVENT_SOCKET``, a path to the UNIX socket the events should be reported to, defaults to ``'./run/tnet/events'``
|
|
+``COMMAND_SOKET``, a path to the UNIX socket the commands should be read from, defaults to ``'./run/tnet/commands'``
|
|
+``BROADCAST_PORT``, 'discovery' UDP port each daemon listens to, defaults to ``0xC0DE``
|
|
+``RECEIVE_PORT``, main data transfer TCP port, defaults to ``0xC00D``
|
|
+``FILE_SAVE_DIR``, a directory the downloaded files will be stored, defaults to ``'Downloads'``
|
|
+``REPORT_PROGRESS_IN``, 0 or 1, if a CLI or other app needs to track progress via EVENT_SOCKET of **incomming** file transfer, defaults to 0
|
|
+``REPORT_PROGRESS_OUT``, 0 or 1, if a CLI or other app needs to track progress via EVENT_SOCKET of **outcoming** file transfer defaults to 0
|
|
|
|
The following env variables can be set for **cli**:
|
|
+``EVENT_SOCKET``, a path to the UNIX socket the events can be read from, defaults to ``'./run/tnet/events'``
|
|
+``COMMAND_SOKET``, a path to the UNIX socket the commands should be sent to, defaults to ``'./run/tnet/commands'``
|
|
|
|
|
|
|
|
|