Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/neilstephens/miniplex

A minimal UDP/TCP/Serial multiplexer/hub/broker. A simple way to bolt-on rudimentary multi-cast/multi-path or combine connections.
https://github.com/neilstephens/miniplex

broker dnp3 framing hub multi-path multiplexer serial tcp udp

Last synced: about 1 month ago
JSON representation

A minimal UDP/TCP/Serial multiplexer/hub/broker. A simple way to bolt-on rudimentary multi-cast/multi-path or combine connections.

Awesome Lists containing this project

README 

          
# MiniPlex

[![MiniPlex Workflow](https://github.com/neilstephens/MiniPlex/actions/workflows/MiniPlex.yml/badge.svg)](https://github.com/neilstephens/MiniPlex/actions/workflows/MiniPlex.yml)



## Synopsis

```



MiniPlex: A minimal UDP multiplexer/hub/broker.

ProtoConv: Protocol adapter to convert between a stream and datagrams.



		In combination, a simple way to bolt-on rudimentary multi-cast/multi-path or combine connections for existing applications



USAGE: 



   ./MiniPlex  {-H|-T|-P|-X} -p  [-l ] [-Z ]

               [-Y ] [-o ] [-O ] [-n

               ] [-r ] [-t ] [-B

               ] ... [-b ] ... [-C ] [-c ] [-f ] [-F ] [-S ] [-N ] [-x ] [-M] [-m ] [--]

               [--version] [-h]



Where: 



   -H,  --hub

     (OR required)  Hub mode: Forward datagrams from/to all endpoints.

         -- OR --

   -T,  --trunk

     (OR required)  Trunk mode: Forward frames from a 'trunk' to other

     endpoints. Forward datagrams from other endpoints to the trunk.

         -- OR --

   -P,  --prune

     (OR required)  Like Trunk mode, but limits flow to one (first in best

     dressed) branch

         -- OR --

   -X,  --switch

     (OR required)  Switch mode: forward datagrams based on application

     addresses.



   -p ,  --port 

     (required)  Local port to listen/receive on.



   -l ,  --local 

     Local ip address. Defaults to 0.0.0.0 for all ipv4 interfaces.



   -Z ,  --so_rcvbuf 

     Datagram socket receive buffer size.



   -Y ,  --max_process_q 

     Maximun number of datagram buffers to allocate. If this limit is

     reached, reading the socket is delayed until processing catches up



   -o ,  --timeout 

     Milliseconds to keep an idle endpoint cached



   -O ,  --branch_cache_max 

     Max number of entries in the active branch cache



   -n ,  --switch_cache_max 

     Max number of branches to cache for each switch mode address



   -r ,  --trunk_ip 

     Remote trunk ip address.



   -t ,  --trunk_port 

     Remote trunk port.



   -B ,  --branch_ip   (accepted multiple times)

     Remote endpoint addresses to permanently cache. Use -b to provide

     respective ports in the same order.



   -b ,  --branch_port   (accepted multiple

      times)

     Remote endpoint port to permanently cache. Use -B to provide

     respective addresses in the same order.



   -C ,  --byte_code 

     RV64IM RISC-V byte code file. Switch mode code for extracting src and

     dst addrs from packet data.



     Pre-conditions: a0=&buf, a1=buf_size, a2=&src, a3=&dst.

     Post-execution: result = a0 (success result==0, src/dst have been

     written).



   -c ,  --console_logging 

     Console log level: off, critical, error, warn, info, debug, or trace.

     Default critical.



   -f ,  --file_logging 

     File log level: off, critical, error, warn, info, debug, or trace.

     Default error.



   -F ,  --log_file 

     Log filename. Defaults to ./MiniPlex.log



   -S ,  --log_size 

     Roll the log file at this many kB. Defaults to 5000



   -N ,  --log_num 

     Keep this many log files when rolling the log. Defaults to 3



   -x ,  --concurrency 

     A hint for the number of threads in thread pool. Defaults to detected

     hardware concurrency.



   -M,  --benchmark

     Run a loopback test for fixed duration (see -m) and exit.



   -m ,  --benchmark_duration 

     Number of milliseconds to run the loopback benchmark test. Defaults to

     10000.



   --,  --ignore_rest

     Ignores the rest of the labeled arguments following this flag.



   --version

     Displays version information and exits.



   -h,  --help

     Displays usage information and exits.



=================================================================================



   ./ProtoConv  -l  [-a ] -A  -r

                 [-B ] [-Q ] [-D ] [-q ] [-m ] [-T ] [-C ] [-k ] [-t ] [-s ] ...

                [-b ] ... [-L ] ... [-Z ] ... [-i ] ... [-p ] [-c ] [-f ] [-F ] [-S ] [-N ] [-x

                ] [--] [--version] [-h]



Where: 



   -l ,  --localport 

     (required)  Local port to listen/receive datagrams on.



   -a ,  --localaddr 

     Local ip address for datagrams. Defaults to 0.0.0.0 for all ipv4

     interfaces.



   -A ,  --remoteaddr 

     (required)  Remote ip address for datagrams.



   -r ,  --remoteport 

     (required)  Remote port for datagrams.



   -B ,  --so_rcvbuf 

     Datagram socket receive buffer size.



   -Q ,  --write_queue_size 

     Max number of messages to buffer in the stream writer queue before

     dropping (older) data.



   -D ,  --packet_delimiter 

     Use a packet delimiter (inserted in the stream with sequence and CRC)

     instead of protocol framing.



   -q ,  --max_sequence_reorder 

     Tolerance for frame re-ordering: max frames to buffer waiting for the

     next sequence number.



   -m ,  --max_sequence_age_ms 

     Tolerance for frame re-ordering: max time (ms) to wait for the next

     sequence number.



   -T ,  --tcphost 

     If converting TCP, this is the remote IP address for the connection.



   -C ,  --tcpisclient 

     If converting TCP, this is defines if it's a client or server

     connection.



   -k ,  --tcpretrytimes 

     Timing parameters for the tcp connection retry exponential backoff:

     '  ' in

     milliseconds



   -t ,  --tcpport 

     TCP port if converting TCP.



   -s ,  --serialdevices   (accepted

      multiple times)

     List of serial devices, if converting serial



   -b ,  --serialbauds   (accepted

      multiple times)

     List of serial board rates, if converting serial



   -L ,  --serialflowctl   (accepted multiple times)

     List of serial flow control settings, if converting serial



   -Z ,  --serialcharsize   (accepted

      multiple times)

     List of serial char sizes, if converting serial



   -i ,  --serialstopbits   (accepted

      multiple times)

     List of serial stop bits settings, if converting serial



   -p ,  --frameprotocol 

     Parse stream frames based on this protocol



   -c ,  --console_logging 

     Console log level: off, critical, error, warn, info, debug, or trace.

     Default critical.



   -f ,  --file_logging 

     File log level: off, critical, error, warn, info, debug, or trace.

     Default error.



   -F ,  --log_file 

     Log filename. Defaults to ./ProtoConv.log



   -S ,  --log_size 

     Roll the log file at this many kB. Defaults to 5000



   -N ,  --log_num 

     Keep this many log files when rolling the log. Defaults to 3



   -x ,  --concurrency 

     A hint for the number of threads in thread pool. Defaults to detected

     hardware concurrency.



   --,  --ignore_rest

     Ignores the rest of the labeled arguments following this flag.



   --version

     Displays version information and exits.



   -h,  --help

     Displays usage information and exits.

   

```



## Get MiniPlex



You can download a pre-built binaries for various platforms from the github [Releases](https://github.com/neilstephens/MiniPlex/releases) section. Alternatively, simply build your own copy from source using the instructions below.



## Example Use Case



Suppose you have a network that doesn't support UDP multicast. Maybe it's disabled for security or performance, or maybe you like firewall policies to have strict point-to-point rules.

But you would still like to stream UDP packets to multiple endpoints. This is where MiniPlex can help. MiniPlex can convert a single unicast stream into multiple streams, or route packets in any number of ways. For example:



### Stream some audio to multiple endpoints:



Run MiniPlex to listen on port 1234 in hub mode any incoming datagrams will be forwarded to all branches.

We specify two fixed branches on the command line, because they will just passively recieve data:



```

./MiniPlex -H -p 1234 -B 192.168.1.5 -b 1234 -B 192.168.1.6 -b 1234

```



Use vlc to stream out some unicast UDP audio:



```

vlc sftp://192.168.1.2/Music/ --sout="#std{access=udp, mux=ts, dst=127.0.0.1:1234}"

```



On the branch hosts (192.168.1.5 and 192.168.1.6 in this example) run vlc to recieve the the audio that is being forwarded by MiniPlex:



```

vlc udp://@:1234

```



### UDP Switch



See [these examples](Examples/SwitchBytecode/README.md) for how to use MiniPlex as a layer 4 UDP switch! The examples include VXLAN, WireGuard and DNP3, but any address based protocol is possible.



## Build



Assuming

  * You've git cloned this repo into a directory called 'MiniPlex' (source directory),

  * Created an adjacent build directory called MiniPlex-bin,

  * Have the appropriate c++20 toolchain installed (earlier version might work, but aren't tested):

    * g++ >= 9.4.0, or

    * clang >= 10.0.0, or

    * MSVC >= VS 2019 v16.11



### Configure the build



```

cmake -S MiniPlex -B MiniPlex-bin

```

This will automatically clone and init the submodules repo dependencies for spdlog, tclap and asio and configure the default build system.



### Run the build

```

cmake --build MiniPlex-bin

```

You should have a MiniPlex executable in MiniPlex-bin. See the synopsis above for how to use it.