Skip to content

Commit

Permalink
doc: add top-level README.md (#16)
Browse files Browse the repository at this point in the history
Add initial README.md describing the `rbmk` tool.
  • Loading branch information
bassosimone authored Nov 30, 2024
1 parent 2e19f40 commit 940679a
Showing 1 changed file with 81 additions and 0 deletions.
81 changes: 81 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
# Really Basic Measurement Kit

[![GoDoc](https://pkg.go.dev/badge/github.com/rbmk-project/rbmk)](https://pkg.go.dev/github.com/rbmk-project/rbmk)

RBMK (Really Basic Measurement Kit) is a command-line utility
to facilitate network exploration and measurements. It provides
two atomic operations (`dig` and `curl`) that you can
compose together to perform modular network measurements where
you can observe each operation in isolation.

## Features

- Modular design with separate DNS and HTTP(S) measurements
- CLI-first approach with composable commands
- Extensive structured logging for detailed analysis
- Support for multiple DNS protocols (UDP, TCP, DoT, DoH)
- HTTP(S) measurements with granular control

The tool is designed to support both general use and measurement-specific
features, with careful consideration of concurrent operations and
extensive testing capabilities.

## Installation

```sh
go install github.com/rbmk-project/rbmk/cmd/rbmk@latest
```

## Quick Start

```sh
# Resolve a domain name
$ rbmk dig +short=ip example.com
93.184.215.14

# Make an HTTP request
$ rbmk curl https://example.com/

# Combine dig and curl for step-by-step measurement
$ IP=$(rbmk dig +short=ip example.com|head -n1)
$ rbmk curl --resolve example.com:443:$IP https://example.com/

# Collect measurement data in flat JSONL format
$ rbmk dig --logs dns.jsonl example.com
$ rbmk curl --logs http.jsonl https://example.com/
```

For a quick introduction with more examples:

```sh
$ rbmk intro
```

## Commands

- `dig`: Performs DNS measurements with a `dig(1)`-like interface
- `curl`: Measures HTTP/HTTPS endpoints using a `curl(1)`-like interface
- `intro`: Shows a brief introduction with usage examples
- `tutorial`: Provides comprehensive usage documentation

Each command supports the `--help` flag for detailed usage information.

## Design

The project focuses on modular, composable measurements where each
operation that may fail is executed independently. This allows for precise
analysis of network behavior and easier debugging of issues.

See [DESIGN.md](docs/DESIGN.md) for detailed design documentation.

## Contributing

Contributions are welcome! Please submit pull requests using
GitHub. Use [rbmk-project/issues](https://github.com/rbmk-project/issues)
to create issues and discuss features.

## License

```
SPDX-License-Identifier: GPL-3.0-or-later
```

0 comments on commit 940679a

Please sign in to comment.