From 51043e440de1705eddc01ec36d9e512b41e75a44 Mon Sep 17 00:00:00 2001 From: Simone Basso Date: Fri, 20 Dec 2024 14:05:26 +0100 Subject: [PATCH] doc: document when each command appeared (#53) While there, tweak the documentation here and there, add clarifications and examples. --- internal/rootcmd/README.md | 12 +++++++++++ pkg/cli/cat/README.md | 8 ++++++- pkg/cli/curl/README.md | 42 ++++++++++++++++++++++++------------- pkg/cli/dig/README.md | 10 ++++++--- pkg/cli/intro/README.md | 4 ++++ pkg/cli/ipuniq/README.md | 6 ++++-- pkg/cli/mkdir/README.md | 6 +++++- pkg/cli/mv/README.md | 8 +++++-- pkg/cli/nc/README.md | 18 +++++++++++----- pkg/cli/pipe/README.md | 6 +++++- pkg/cli/pipe/read.md | 12 +++++++---- pkg/cli/pipe/write.md | 4 ++++ pkg/cli/rm/README.md | 4 ++++ pkg/cli/sh/README.md | 2 +- pkg/cli/stun/README.md | 12 +++++++---- pkg/cli/tar/README.md | 8 +++++-- pkg/cli/timestamp/README.md | 10 +++++++-- pkg/cli/tutorial/README.md | 4 ++++ pkg/cli/tutorial/basics.md | 18 +++++++++++++++- pkg/cli/version/README.md | 6 +++++- 20 files changed, 156 insertions(+), 44 deletions(-) diff --git a/internal/rootcmd/README.md b/internal/rootcmd/README.md index 53f6624..53534ea 100644 --- a/internal/rootcmd/README.md +++ b/internal/rootcmd/README.md @@ -35,9 +35,21 @@ to facilitate network exploration and measurements. * `intro` - Shows a brief introduction with usage examples. * `tutorial` - Provides comprehensive usage documentation. +* `version` - Prints the version of the `rbmk` utility to the stdout. ## Getting Started New to RBMK? Try `rbmk intro` to get started! Run `rbmk COMMAND --help` for more information about `COMMAND`. + +## License + +``` +SPDX-License-Identifier: GPL-3.0-or-later +``` + +## Reporting Bugs + +Please, use the [rbmk-project/issues](https://github.com/rbmk-project/issues) +repository to report bugs or suggest improvements. diff --git a/pkg/cli/cat/README.md b/pkg/cli/cat/README.md index 1823fbf..fa93c78 100644 --- a/pkg/cli/cat/README.md +++ b/pkg/cli/cat/README.md @@ -16,8 +16,14 @@ Concatenate files and print on the standard output. The following invocation concatenates the content of the `file1.txt` and `file2.txt` files to the stdout: - $ rbmk cat file.txt +``` +$ rbmk cat file1.txt file2.txt +``` ## Exit Status This command exits with `0` on success and `1` on failure. + +## History + +The `rbmk cat` command was introduced in RBMK v0.2.0. diff --git a/pkg/cli/curl/README.md b/pkg/cli/curl/README.md index e35d3f1..c63475d 100644 --- a/pkg/cli/curl/README.md +++ b/pkg/cli/curl/README.md @@ -20,10 +20,10 @@ Print this help message. ### `--logs FILE` -Writes structured logs to the given FILE. If FILE already exists, we -append to it. If FILE does not exist, we create it. If FILE is a single +Writes structured logs to the given `FILE`. If `FILE` already exists, we +append to it. If `FILE` does not exist, we create it. If `FILE` is a single dash (`-`), we write to the stdout. If you specify `--logs` multiple -times, we write to the last FILE specified. +times, we write to the last `FILE` specified. ### `--max-time DURATION` @@ -41,15 +41,15 @@ continuing due to this flag. ### `-o, --output FILE` -Write the response body to FILE instead of using the stdout. +Write the response body to `FILE` instead of using the stdout. ### `--resolve HOST:PORT:ADDR` -Use ADDR instead of DNS resolution for HOST:PORT. +Use `ADDR` instead of DNS resolution for `HOST:PORT`. -Implementation note: we ignore the port and replace the HOST with -ADDR for every port number. Additionally, when using this flag, the -DNS lookup fails with "no such host" if the URL host is not HOST. +Implementation note: we ignore the `PORT` and replace the `HOST` with +`ADDR` for every port number. Additionally, when using this flag, the +DNS lookup fails with "no such host" if the URL host is not `HOST`. ### `-v, --verbose` @@ -57,30 +57,40 @@ Make the operation more talkative. ### `-X, --request METHOD` -Use the given request METHOD instead of GET. +Use the given request `METHOD` instead of GET. ## Examples The following invocation prints the response body of the `https://example.com/` website URL: - $ rbmk curl https://example.com/ +``` +$ rbmk curl https://example.com/ +``` To also print request and response headers, use `-v`: - $ rbmk curl -v https://example.com/ +``` +$ rbmk curl -v https://example.com/ +``` To save structured logs to `logfile.jsonl` use `--logs`: - $ rbmk curl --logs logfile.jsonl https://example.com/ +``` +$ rbmk curl --logs logfile.jsonl https://example.com/ +``` To save the response body to `output.txt` use `-o`: - $ rbmk curl -o output.txt https://example.com/ +``` +$ rbmk curl -o output.txt https://example.com/ +``` To use a previously resolved IP address, use `--resolve`: - $ rbmk curl --resolve example.com:443:93.184.215.14 https://example.com/ +``` +$ rbmk curl --resolve example.com:443:93.184.215.14 https://example.com/ +``` ## Exit Status @@ -91,3 +101,7 @@ Returns `0` on success. Returns `1` on: - File operation errors (cannot open/close files). - Measurement failures (unless `--measure` is specified). + +## History + +The `rbmk curl` command was introduced in RBMK v0.1.0. diff --git a/pkg/cli/dig/README.md b/pkg/cli/dig/README.md index 4758022..e2459e2 100644 --- a/pkg/cli/dig/README.md +++ b/pkg/cli/dig/README.md @@ -61,10 +61,10 @@ Print this help message. ### `--logs FILE` -Writes structured logs to the given FILE. If FILE already exists, we -append to it. If FILE does not exist, we create it. If FILE is a single +Writes structured logs to the given `FILE`. If `FILE` already exists, we +append to it. If `FILE` does not exist, we create it. If `FILE` is a single dash (`-`), we write to the stdout. If you specify `--logs` multiple -times, we write to the last FILE specified. +times, we write to the last `FILE` specified. ### `--measure` @@ -179,3 +179,7 @@ Returns `0` on success. Returns `1` on: - File operation errors (cannot open/close files). - Measurement failures (unless `--measure` is specified). + +## History + +The `rbmk dig` command was introduced in RBMK v0.1.0. diff --git a/pkg/cli/intro/README.md b/pkg/cli/intro/README.md index 1506689..118c8c2 100644 --- a/pkg/cli/intro/README.md +++ b/pkg/cli/intro/README.md @@ -64,3 +64,7 @@ and makes it easier to understand where issues occur. * Run `rbmk curl --help` for detailed HTTP measurement options * Try `rbmk tutorial` for a comprehensive guide + +## History + +The `rbmk intro` command was introduced in RBMK v0.1.0. diff --git a/pkg/cli/ipuniq/README.md b/pkg/cli/ipuniq/README.md index ae00517..40b09e5 100644 --- a/pkg/cli/ipuniq/README.md +++ b/pkg/cli/ipuniq/README.md @@ -53,11 +53,11 @@ Print this help message. ### `-p, --port PORT` -Format output as HOST:PORT endpoints, adding [] brackets for IPv6 +Format output as `ADDRESS:PORT` endpoints, adding [] brackets for IPv6 addresses as needed. This flag can be specified multiple times to generate endpoints for multiple ports (e.g., `-p 80 -p 443 -p 22` generates HTTP, HTTPS, and SSH endpoints). When no ports are -specified, we output IP addresses without ports. Each PORT must +specified, we output IP addresses without ports. Each `PORT` must be a valid port number (0-65535). ### `-r, --random` @@ -138,3 +138,5 @@ This command exits with `0` on success and `1` on failure. Before RBMK v0.4.0, this command always randomly shuffled the addresses. Afterwards, one must use `--random` explicitly. + +This command was introduced in RBMK v0.2.0. diff --git a/pkg/cli/mkdir/README.md b/pkg/cli/mkdir/README.md index aad5af3..e918f09 100644 --- a/pkg/cli/mkdir/README.md +++ b/pkg/cli/mkdir/README.md @@ -7,7 +7,7 @@ rbmk mkdir [-p] DIRECTORY... ``` -Create the DIRECTORY(ies), if they do not already exist. We use the +Create the `DIRECTORY`(ies), if they do not already exist. We use the `0755` file mode to create new directories. ## Flags @@ -37,3 +37,7 @@ $ rbmk mkdir -p a/long/path/of/dirs ## Exit Status This command exits with `0` on success and `1` on failure. + +## History + +The `rbmk mkdir` command was introduced in RBMK v0.2.0. diff --git a/pkg/cli/mv/README.md b/pkg/cli/mv/README.md index e2f09b6..3c3a901 100644 --- a/pkg/cli/mv/README.md +++ b/pkg/cli/mv/README.md @@ -8,8 +8,8 @@ rbmk mv [-f] SOURCE... DESTINATION ## Description -Move (rename) SOURCE to DESTINATION. When moving multiple SOURCE files, -the DESTINATION must be an existing directory. +Move (rename) `SOURCE` to `DESTINATION`. When moving multiple `SOURCE` files, +the `DESTINATION` must be an existing directory. ## Flags @@ -34,3 +34,7 @@ $ rbmk mv file1.txt file2.txt target_directory/ ## Exit Status This command exits with `0` on success and `1` on failure. + +## History + +The `rbmk mv` command was introduced in RBMK v0.3.0. diff --git a/pkg/cli/nc/README.md b/pkg/cli/nc/README.md index 9d0e1bb..b4c3810 100644 --- a/pkg/cli/nc/README.md +++ b/pkg/cli/nc/README.md @@ -24,7 +24,9 @@ it is recommended to specify an IP address directly. Specify ALPN protocol(s) for TLS connections. Can be specified multiple times to support protocol negotiation. For example: - --alpn h2 --alpn http/1.1 +``` +--alpn h2 --alpn http/1.1 +``` Must be used alongside the `--tls` flag. @@ -38,10 +40,10 @@ Print this help message. ### `--logs FILE` -Writes structured logs to the given FILE. If FILE already exists, we -append to it. If FILE does not exist, we create it. If FILE is a single +Writes structured logs to the given `FILE`. If `FILE` already exists, we +append to it. If `FILE` does not exist, we create it. If `FILE` is a single dash (`-`), we write to the stdout. If you specify `--logs` multiple -times, we write to the last FILE specified. +times, we write to the last `FILE` specified. ### `--measure` @@ -56,7 +58,9 @@ continuing due to this flag. Specify the server name for the SNI extension in the TLS handshake. For example: - --sni www.example.com +``` +--sni www.example.com +``` Must be used alongside the `--tls` flag. @@ -110,3 +114,7 @@ $ rbmk nc --logs conn.jsonl example.com 80 ## Exit Status The nc utility exits with `0` on success and `1` on error. + +## History + +The `rbmk nc` command was introduced in RBMK v0.6.0. diff --git a/pkg/cli/pipe/README.md b/pkg/cli/pipe/README.md index 51653bd..f2698ca 100644 --- a/pkg/cli/pipe/README.md +++ b/pkg/cli/pipe/README.md @@ -11,7 +11,7 @@ rbmk pipe COMMAND [args...] Create and use named pipes for inter-process communication within measurement scripts. Uses Unix domain sockets on both Unix systems -and modern Windows (10.0.17063+). +and modern Windows systems (10.0.17063+). ## Commands @@ -69,3 +69,7 @@ Returns `0` on success. Returns `1` on: - Connection timeouts - I/O errors + +## History + +The `rbmk pipe` command was introduced in RBMK v0.4.0. diff --git a/pkg/cli/pipe/read.md b/pkg/cli/pipe/read.md index 7e2a0f7..85074e9 100644 --- a/pkg/cli/pipe/read.md +++ b/pkg/cli/pipe/read.md @@ -9,9 +9,9 @@ rbmk pipe read --writers N PIPE ## Description -Read from a named pipe in the current directory. Accepts exactly N writers +Read from a named pipe in the current directory. Accepts exactly `N` writers and multiplexes their output to stdout line by line. The command terminates -after all N writers have disconnected. If `N` is not specified +after all `N` writers have disconnected. If `N` is not specified or is zero, this command will `exit 1` and print an error. Each line from each writer is written atomically to stdout to prevent garbled @@ -43,7 +43,7 @@ done ## Notes -- Blocks until exactly N writers have connected and completed +- Blocks until exactly `N` writers have connected and completed - Each writer's output is handled line by line @@ -51,7 +51,7 @@ done - Writers may disconnect early -- No new connections are accepted after N writers +- No new connections are accepted after `N` writers ## Exit Status @@ -62,3 +62,7 @@ Returns `0` on success. Returns `1` on: - Connection errors - I/O errors + +## History + +The `rbmk pipe read` command was introduced in RBMK v0.4.0. diff --git a/pkg/cli/pipe/write.md b/pkg/cli/pipe/write.md index d5a9fc3..a9dc1bb 100644 --- a/pkg/cli/pipe/write.md +++ b/pkg/cli/pipe/write.md @@ -37,3 +37,7 @@ Returns `0` on success. Returns `1` on: - Connection timeout - I/O errors + +## History + +The `rbmk pipe write` command was introduced in RBMK v0.4.0. diff --git a/pkg/cli/rm/README.md b/pkg/cli/rm/README.md index 2d8560e..002a2ae 100644 --- a/pkg/cli/rm/README.md +++ b/pkg/cli/rm/README.md @@ -42,3 +42,7 @@ $ rbmk rm -rf directory ## Exit Status This command exits with `0` on success and `1` on failure. + +## History + +The `rbmk rm` command was introduced in RBMK v0.2.0. diff --git a/pkg/cli/sh/README.md b/pkg/cli/sh/README.md index cbf612e..7e6f0a1 100644 --- a/pkg/cli/sh/README.md +++ b/pkg/cli/sh/README.md @@ -96,4 +96,4 @@ Since v0.7.0. `rbmk` is an internal shell command, `rbmk sh` is not capable of executing external commands, and `$RBMK_EXE` is set to `rbmk`, thus supporting previously existing scripts without modification. -The `rbmk sh` command appeared in RBMK v0.2.0. +The `rbmk sh` command was introduced in RBMK v0.2.0. diff --git a/pkg/cli/stun/README.md b/pkg/cli/stun/README.md index 498f6e4..c5a6221 100644 --- a/pkg/cli/stun/README.md +++ b/pkg/cli/stun/README.md @@ -9,14 +9,14 @@ rbmk stun [flags] ENDPOINT ## Description -Send a STUN Binding Request to the given ENDPOINT and print the reflexive +Send a STUN Binding Request to the given `ENDPOINT` and print the reflexive transport address (public IP address and port) to standard output. ## Arguments ### `ENDPOINT` -The ENDPOINT argument should be in the form HOST:PORT. For example: +The ENDPOINT argument should be in the form `HOST:PORT`. For example: - `stun.l.google.com:19302` @@ -35,8 +35,8 @@ Print this help message. ### `--logs FILE` -Writes structured logs to the given FILE. If FILE already exists, we -append to it. If FILE does not exist, we create it. If FILE is a single +Writes structured logs to the given `FILE`. If `FILE` already exists, we +append to it. If `FILE` does not exist, we create it. If `FILE` is a single dash (`-`), we write to the stdout. ### `--max-time DURATION` @@ -77,3 +77,7 @@ Returns `0` on success. Returns `1` on: - File operation errors (cannot open/close files). - Measurement failures (unless `--measure` is specified). + +## History + +The `rbmk stun` command was introduced in RBMK v0.3.0. diff --git a/pkg/cli/tar/README.md b/pkg/cli/tar/README.md index 95292d1..1399b95 100644 --- a/pkg/cli/tar/README.md +++ b/pkg/cli/tar/README.md @@ -9,7 +9,7 @@ rbmk tar -czf ARCHIVE FILE|DIR... ## Description -Create a tar ARCHIVE containing the specified FILEs and DIRs. We +Create a tar `ARCHIVE` containing the specified `FILE`s and `DIR`s. We only support archiving regular files and directories. ## Flags @@ -20,7 +20,7 @@ Create a new archive. ### `-f, --file NAME` -Set the archive file name. +Set the archive file name and path. ### `-h, --help` @@ -42,3 +42,7 @@ $ rbmk tar -czf results.tar.gz ./measurements ## Exit Status This command exits with `0` on success and `1` on failure. + +## History + +The `rbmk tar` command was introduced in RBMK v0.2.0. diff --git a/pkg/cli/timestamp/README.md b/pkg/cli/timestamp/README.md index 809bff1..a69007d 100644 --- a/pkg/cli/timestamp/README.md +++ b/pkg/cli/timestamp/README.md @@ -11,9 +11,11 @@ rbmk timestamp Print a filesystem-friendly ISO8601 UTC timestamp. -The timestamp format is YYYYMMDDTHHmmssZ, for example: +The timestamp format is `YYYYMMDDTHHmmssZ`, for example: - 20241201T114117Z +``` +20241201T114117Z +``` ## Features @@ -41,3 +43,7 @@ $ rbmk mkdir -p "$outdir" ## Exit Status This command exits with `0` on success and `1` on failure. + +## History + +The `rbmk timestamp` command was introduced in RBMK v0.2.0. diff --git a/pkg/cli/tutorial/README.md b/pkg/cli/tutorial/README.md index cbdf05e..8b57f53 100644 --- a/pkg/cli/tutorial/README.md +++ b/pkg/cli/tutorial/README.md @@ -31,3 +31,7 @@ Read the basics tutorial: ``` $ rbmk tutorial basics ``` + +## History + +The `rbmk tutorial` command was introduced in RBMK v0.1.0. diff --git a/pkg/cli/tutorial/basics.md b/pkg/cli/tutorial/basics.md index 1376c98..b1089b3 100644 --- a/pkg/cli/tutorial/basics.md +++ b/pkg/cli/tutorial/basics.md @@ -17,7 +17,9 @@ text associated with the `rbmk dig` subcommand. All commands exit with `0` on success and with `1` on failure. Note that failure includes both usage errors (e.g., passing an invalid flag -to a command) and measurement errors (e.g., a network timeout). +to a command) and measurement errors (e.g., a network timeout). The +`--measure` flag disables the exit-on-failure behavior for measurement +errors, thus allowing shell scripts to use `set -e`. ## Basic Commands @@ -52,6 +54,20 @@ $ rbmk stun stun.l.google.com:19302 Run `rbmk stun --help` for additional help. +4. Netcat (`rbmk nc`) + +Check whether a port is open: + +``` +$ rbmk nc -zv example.com 80 +``` + +Same as above, but also checking for TLS reachability: + +``` +$ rbmk nc --alpn h2 --alpn http/1.1 -zvc example.com 443 +``` + ## Combining Commands diff --git a/pkg/cli/version/README.md b/pkg/cli/version/README.md index ae2e362..0502fff 100644 --- a/pkg/cli/version/README.md +++ b/pkg/cli/version/README.md @@ -10,7 +10,7 @@ rbmk version ## Description Prints on the stdout version information. We add version information -when compiling `rbmk` using the `GNUMakefile`. +when compiling `rbmk` using the `GNUmakefile` makefile. Possible values for the version information are: @@ -20,3 +20,7 @@ Possible values for the version information are: - `vX.Y.Z--g` if using `GNUMakefile` to build a commit not associated with a tag. + +## History + +The `rbmk version` command was introduced in RBMK v0.5.0.