Add client syslog events, fix client UDP TX error threshold

- Client mode now emits TEST_START and TEST_END syslog events - Client UDP TX threshold raised from 1000 to 50000 with adaptive backoff (matching server behavior) — prevents premature TX death on macOS - Updated all docs (README, user-guide, architecture, protocol, docker) - Added results.csv to gitignore Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-01 09:40:52 +04:00
parent 751a9d5f13
commit 949c4908ad
9 changed files with 1143 additions and 195 deletions
--- a/docs/user-guide.md
+++ b/docs/user-guide.md
@@ -14,21 +14,29 @@ btest -c 192.168.88.1 -r

 Run btest-rs as a server and let MikroTik devices connect for bandwidth testing.

-### Basic Server
+### Basic Server (No Authentication)

 ```bash
 btest -s
 ```

-Listens on TCP port 2000 (default). Any MikroTik device can connect without authentication.
+Listens on all IPv4 interfaces, TCP port 2000. Any MikroTik device can connect without credentials.

-### Server with Authentication
+### Server with MD5 Authentication

 ```bash
 btest -s -a admin -p mysecretpassword
 ```

-MikroTik devices must provide matching credentials. Uses MD5 challenge-response authentication.
+Requires connecting devices to provide matching credentials. Uses MD5 double-hash challenge-response authentication, compatible with RouterOS versions before 6.43.
+
+### Server with EC-SRP5 Authentication
+
+```bash
+btest -s -a admin -p mysecretpassword --ecsrp5
+```
+
+Advertises EC-SRP5 (Curve25519 Weierstrass) authentication to connecting clients. Required for RouterOS >= 6.43 devices that use the modern authentication protocol.

 ### Custom Port

@@ -36,25 +44,90 @@ MikroTik devices must provide matching credentials. Uses MD5 challenge-response
 btest -s -P 3000
 ```

+### Custom Listen Address
+
+```bash
+# Listen only on a specific interface
+btest -s --listen 10.0.0.1
+
+# Disable IPv4, listen only on IPv6
+btest -s --listen none --listen6
+
+# Listen on both IPv4 and IPv6
+btest -s --listen6
+```
+
+### IPv6 Listener (Experimental)
+
+```bash
+# IPv6 on default address (::)
+btest -s --listen6
+
+# IPv6 on a specific address
+btest -s --listen6 fd00::1
+```
+
+TCP over IPv6 works fully on all platforms. UDP over IPv6 has issues on macOS due to kernel ENOBUFS limitations with `send_to()`. On Linux, IPv6 UDP works correctly.
+
+### Syslog Integration
+
+```bash
+btest -s --syslog 192.168.1.1:514
+```
+
+Sends structured log events to a remote syslog server via UDP (RFC 3164 / BSD syslog format, facility local0). Events include:
+
+- `AUTH_SUCCESS` -- successful authentication with peer address, username, and auth type
+- `AUTH_FAILURE` -- failed authentication with peer address, username, auth type, and reason
+- `TEST_START` -- test initiated with peer address, protocol, direction, and connection count
+- `TEST_END` -- test completed with peer address, protocol, direction, duration, average speeds, bytes transferred, and lost packets
+
+### CSV Output
+
+```bash
+btest -s --csv /var/log/btest-results.csv
+```
+
+Appends a row for each completed test to the specified CSV file. Creates the file with headers if it does not exist. CSV columns:
+
+```
+timestamp,host,port,protocol,direction,duration_s,tx_avg_mbps,rx_avg_mbps,tx_bytes,rx_bytes,lost_packets,auth_type
+```
+
+### Quiet Mode
+
+```bash
+btest -s --csv /var/log/btest.csv -q
+```
+
+Suppresses per-second terminal output. Useful when running as a background service with CSV or syslog logging only.
+
 ### Verbose/Debug Output

 ```bash
-btest -s -v      # Show connection info and debug messages
-btest -s -vv     # Show hex dumps of status exchange (for debugging)
+btest -s -v       # Debug messages (connection lifecycle, auth steps)
+btest -s -vv      # Trace messages (hex dumps of status exchange)
+btest -s -vvv     # Maximum verbosity
 ```

-### MikroTik Configuration (connecting to our server)
+### Combined Example

-**Important: Always set Connection Count to 1.** Multi-connection mode is not supported and will cause severely degraded speeds.
+```bash
+btest -s -a admin -p secret --ecsrp5 --syslog 10.0.0.1:514 --csv /var/log/btest.csv -v
+```
+
+This runs a server with EC-SRP5 authentication, sends events to syslog, logs results to CSV, and prints debug output to the terminal.
+
+### MikroTik Configuration (Connecting to Our Server)

 On the MikroTik device (WinBox or CLI):

 ```
-# CLI — always include connection-count=1
-/tool/bandwidth-test address=<server-ip> direction=both protocol=udp user=admin password=mysecretpassword connection-count=1
+/tool/bandwidth-test address=<server-ip> direction=both protocol=udp \
+    user=admin password=mysecretpassword
 ```

-Or via WinBox: **Tools → Bandwidth Test**, enter server address, credentials, **set Connection Count to 1**, and click Start.
+Or via WinBox: **Tools > Bandwidth Test**, enter the server address and credentials, and click Start.

 ## Client Mode

@@ -62,28 +135,27 @@ Connect to a MikroTik device's built-in bandwidth test server.

 ### Prerequisites

-Enable btest server on MikroTik:
+Enable the btest server on the MikroTik device:
+
 ```
 /tool/bandwidth-server set enabled=yes
 ```

-**Note**: If the MikroTik uses RouterOS >= 6.43 with authentication enabled, you'll need to either disable auth or use credentials. EC-SRP5 auth is not yet supported; MD5 auth works on older RouterOS versions.
-
-### Download Test (receive)
+### Download Test (Receive)

 ```bash
 btest -c 192.168.88.1 -r
 ```

-Measures download speed from MikroTik to your machine.
+Measures download speed from the MikroTik device to your machine. The server transmits, the client receives.

-### Upload Test (transmit)
+### Upload Test (Transmit)

 ```bash
 btest -c 192.168.88.1 -t
 ```

-Measures upload speed from your machine to MikroTik.
+Measures upload speed from your machine to the MikroTik device. The client transmits, the server receives.

 ### Bidirectional Test

@@ -101,6 +173,8 @@ btest -c 192.168.88.1 -t -u          # UDP upload
 btest -c 192.168.88.1 -t -r -u       # UDP bidirectional
 ```

+UDP mode uses separate data ports (2001+ on the server side, 2257+ on the client side) and exchanges status messages every second over the TCP control channel.
+
 ### Bandwidth Limiting

 ```bash
@@ -109,15 +183,7 @@ btest -c 192.168.88.1 -t -b 1G       # Limit to 1 Gbps
 btest -c 192.168.88.1 -r -b 500K     # Limit to 500 Kbps
 ```

-### NAT Traversal
-
-If you're behind NAT and need to receive UDP data:
-
-```bash
-btest -c 192.168.88.1 -r -u -n
-```
-
-The `-n` flag sends a probe packet to open the NAT firewall hole.
+Suffixes: `K` (kilobits/sec), `M` (megabits/sec), `G` (gigabits/sec). Values are in bits per second.

 ### With Authentication

@@ -125,6 +191,47 @@ The `-n` flag sends a probe packet to open the NAT firewall hole.
 btest -c 192.168.88.1 -r -a admin -p password
 ```

+The client auto-detects the authentication type (MD5 or EC-SRP5) from the server's response and handles it accordingly.
+
+### NAT Traversal
+
+```bash
+btest -c 192.168.88.1 -r -u -n
+```
+
+The `-n` flag sends an empty UDP probe packet before starting the receive thread. This opens a hole in NAT firewalls so the server's UDP data packets can reach the client.
+
+### Timed Tests
+
+```bash
+btest -c 192.168.88.1 -r -d 30       # Run for 30 seconds, then stop
+btest -c 192.168.88.1 -t -r -d 60    # 60-second bidirectional test
+```
+
+The default duration is 0 (unlimited). When the duration expires, the client exits cleanly.
+
+### CSV Output (Client Mode)
+
+```bash
+btest -c 192.168.88.1 -r -d 30 --csv results.csv
+```
+
+Appends a summary row after the test completes with the host, port, protocol, direction, duration, and auth type.
+
+### Quiet Mode (Client)
+
+```bash
+btest -c 192.168.88.1 -r -d 10 --csv results.csv -q
+```
+
+Suppresses per-second bandwidth output to the terminal. Useful for scripted or automated testing where only the CSV file matters.
+
+### Custom Port
+
+```bash
+btest -c 192.168.88.1 -r -P 3000
+```
+
 ## Reading the Output

 ```
@@ -137,50 +244,131 @@ btest -c 192.168.88.1 -r -a admin -p password
 | Field | Meaning |
 |-------|---------|
 | `[  N]` | Interval number (1 per second) |
-| `TX` | Data we sent (upload) |
-| `RX` | Data we received (download) |
+| `TX` | Data sent (upload from your perspective) |
+| `RX` | Data received (download from your perspective) |
 | `Mbps` | Megabits per second |
 | `bytes` | Raw bytes transferred in this interval |
-| `lost: N` | UDP packets lost (UDP mode only) |
+| `lost: N` | UDP packets lost in this interval (UDP mode only) |

-## CLI Reference
+## Complete CLI Reference

 ```
-btest-rs — MikroTik Bandwidth Test server & client in Rust
+btest-rs -- MikroTik Bandwidth Test server & client in Rust

 Usage: btest [OPTIONS]

 Options:
-  -s, --server              Run in server mode
-  -c, --client <HOST>       Run in client mode, connect to HOST
-  -t, --transmit            Client: upload test
-  -r, --receive             Client: download test
-  -u, --udp                 Use UDP instead of TCP
-  -b, --bandwidth <BW>      Bandwidth limit (e.g., 100M, 1G, 500K)
-  -P, --port <PORT>         Port number [default: 2000]
-  -a, --authuser <USER>     Authentication username
-  -p, --authpass <PASS>     Authentication password
-  -n, --nat                 NAT traversal mode
-  -v, --verbose             Increase log verbosity (-v, -vv)
-  -h, --help                Show help
-  -V, --version             Show version
+  -s, --server
+          Run in server mode. Listens for incoming connections from MikroTik
+          devices or other btest clients. Conflicts with -c.
+
+  -c, --client <HOST>
+          Run in client mode, connecting to the specified host. The host can be
+          an IPv4 address, IPv6 address, or hostname. Conflicts with -s.
+
+  -t, --transmit
+          Client transmits data (upload test). Tells the server to receive.
+          Can be combined with -r for bidirectional testing.
+
+  -r, --receive
+          Client receives data (download test). Tells the server to transmit.
+          Can be combined with -t for bidirectional testing.
+
+  -u, --udp
+          Use UDP instead of TCP for the data transfer. UDP uses separate data
+          ports (2001+ server side, 2257+ client side) and exchanges status
+          messages over the TCP control channel every second.
+
+  -b, --bandwidth <BW>
+          Target bandwidth limit for the test. Accepts suffixes: K (kilobits),
+          M (megabits), G (gigabits). Examples: 100M, 1G, 500K. Default is 0
+          (unlimited).
+
+  -P, --port <PORT>
+          TCP port to listen on (server mode) or connect to (client mode).
+          [default: 2000]
+
+      --listen <ADDR>
+          IPv4 address to bind the server listener to. Use "none" to disable
+          IPv4 listening entirely (useful with --listen6 for IPv6-only mode).
+          [default: 0.0.0.0]
+
+      --listen6 [<ADDR>]
+          Enable the IPv6 listener. If no address is given, binds to [::].
+          Experimental: TCP over IPv6 works fully on all platforms. UDP over
+          IPv6 has issues on macOS due to kernel ENOBUFS limitations.
+
+  -a, --authuser <USER>
+          Authentication username. In server mode, clients must provide this
+          username. In client mode, this is sent to the server.
+
+  -p, --authpass <PASS>
+          Authentication password. In server mode, clients must provide a
+          matching password. In client mode, this is used to authenticate.
+
+      --ecsrp5
+          Use EC-SRP5 authentication (Curve25519 Weierstrass). In server mode,
+          this advertises EC-SRP5 instead of MD5 to connecting clients.
+          Required for RouterOS >= 6.43. In client mode, auth type is
+          auto-detected and this flag is not needed.
+
+  -n, --nat
+          NAT traversal mode. Sends an empty UDP probe packet to the server
+          before starting the receive thread, opening a hole in NAT firewalls.
+          Only relevant for UDP receive tests behind NAT.
+
+  -d, --duration <SECS>
+          Test duration in seconds (client mode only). The client exits cleanly
+          after the specified time. A value of 0 means unlimited (run until
+          interrupted with Ctrl-C). [default: 0]
+
+      --csv <FILE>
+          Output test results to a CSV file. Appends a row per completed test.
+          Creates the file with a header row if it does not exist. Columns:
+          timestamp, host, port, protocol, direction, duration_s, tx_avg_mbps,
+          rx_avg_mbps, tx_bytes, rx_bytes, lost_packets, auth_type.
+
+  -q, --quiet
+          Suppress per-second bandwidth output to the terminal. Useful in
+          combination with --csv for machine-readable-only output, or when
+          running as a background service.
+
+      --syslog <HOST:PORT>
+          Send structured log events to a remote syslog server via UDP. Uses
+          RFC 3164 (BSD syslog) format with facility local0. Events include
+          AUTH_SUCCESS, AUTH_FAILURE, TEST_START, and TEST_END with detailed
+          metadata. Example: --syslog 192.168.1.1:514
+
+  -v, --verbose...
+          Increase log verbosity. Can be repeated:
+            -v    debug messages (connection lifecycle, auth steps)
+            -vv   trace messages (hex dumps of protocol exchange)
+            -vvv  maximum verbosity
+
+  -h, --help
+          Print help information
+
+  -V, --version
+          Print version information
 ```

 ## Tips

- **Connection Count MUST be 1** when MikroTik connects to your server. Multi-connection mode is not supported and will cause speeds to drop to near zero. Single-connection performance is excellent (1+ Gbps).
 - **TCP mode** generally gives more stable results than UDP due to TCP flow control.
 - **UDP mode** is better for measuring raw link capacity without TCP overhead.
 - **First interval** may show higher or lower numbers as the connection stabilizes. Look at intervals 3+ for steady-state throughput.
 - **WiFi testing**: bidirectional tests on WiFi will show lower per-direction speeds because WiFi is half-duplex at the MAC layer.
+- **Bandwidth limiting** applies to the direction you specify. In bidirectional mode with `-b 100M`, both directions are limited to 100 Mbps each.

 ## Troubleshooting

 | Problem | Solution |
 |---------|----------|
-| `EC-SRP5 authentication not supported` | Disable auth on MikroTik btest server, or use older RouterOS |
-| `Connection refused` | Check port 2000 is open, firewall allows it |
-| Server shows 0 RX | Check MikroTik is actually sending (direction setting) |
-| Speed drops over time (server mode) | Set Connection Count to 1 on MikroTik. Multi-connection is not supported |
-| Very low speed with multiple connections | Multi-connection mode is broken — set Connection Count to 1 |
-| UDP `lost` packets high | Network congestion or MTU issues, try reducing bandwidth with `-b` |
+| Connection refused | Check that port 2000 is open and the server is running |
+| Auth failure with EC-SRP5 | Ensure `--ecsrp5` is set on the server if the MikroTik client uses RouterOS >= 6.43 |
+| Auth failure with MD5 | Verify username and password match exactly (case-sensitive) |
+| Server shows 0 RX | Check that the MikroTik direction setting includes sending to the server |
+| Very low UDP speed | Network congestion or MTU issues; try reducing bandwidth with `-b` |
+| IPv6 UDP fails on macOS | Known macOS kernel limitation; use Linux for IPv6 UDP tests |
+| Syslog messages not arriving | Verify the syslog server address and port, and check firewall rules for UDP 514 |
+| CSV file not created | Check write permissions on the directory; the file is created on first use |