From 0a23dee9661f1cb52cae00944bdc1211096c75ad Mon Sep 17 00:00:00 2001 From: lvlcn-t <75443136+lvlcn-t@users.noreply.github.com> Date: Mon, 5 Aug 2024 21:36:34 +0200 Subject: [PATCH] chore: lint markdown files --- README.md | 41 +++++++----- pkg/checks/traceroute/test-lab/how-to-test.md | 65 +++++++++++++------ 2 files changed, 70 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index bb63a609..1c86be28 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,9 @@ - [DNS Metrics](#dns-metrics) - [Check: Traceroute](#check-traceroute) - [Example configuration](#example-configuration-3) - - [Required Capabilities](#required-capabilities) + - [Optional Capabilities](#optional-capabilities) + - [Traceroute Prometheus Metrics](#traceroute-prometheus-metrics) + - [Traceroute API Metrics](#traceroute-api-metrics) - [API](#api) - [Metrics](#metrics) - [Code of Conduct](#code-of-conduct) @@ -409,7 +411,7 @@ latency: - `sparrow_latency_duration_seconds` - Type: Gauge - - Description: Latency with status information of targets. This metric is DEPRECATED. Use `sparrow_latency_seconds`. + - Description: Latency with status information of targets. This metric is DEPRECATED. Use `sparrow_latency_seconds`. - Labelled with `target` and `status` - `sparrow_latency_seconds` @@ -511,40 +513,45 @@ dns: #### Optional Capabilities -Sparrow does not need any extra permissions to run this check. However, some data, like the ip address +Sparrow does not need any extra permissions to run this check. However, some data, like the ip address of the hop that dropped a packet, will not be available. To enable this functionality, there are two options: -- run sparrow as root: -```bash -sudo sparrow run --config config.yaml -``` +- Run sparrow as root: -- allow sparrow to create raw sockets, by assigning the `CAP_NET_RAW` capability to the sparrow binary: -```bash -sudo setcap 'cap_net_raw=ep' sparrow -``` + ```bash + sudo sparrow run --config config.yaml + ``` -#### Traceroute Prometheus Metrics +- Allow sparrow to create raw sockets, by assigning the `CAP_NET_RAW` capability to the sparrow binary: + + ```bash + sudo setcap 'cap_net_raw=ep' sparrow + ``` +#### Traceroute Prometheus Metrics - `sparrow_traceroute_check_duration_ms{target="google.com"} 43150` - - Type: Gauge - - Description: How long the last traceroute took for this target in total + - Type: Gauge + - Description: How long the last traceroute took for this target in total - `sparrow_traceroute_minimum_hops{target="google.com"} 14` - - Type: Gauge - - Description: The minimum number of hops required to reach a target + - Type: Gauge + - Description: The minimum number of hops required to reach a target #### Traceroute API Metrics + The traceroute check exposes additional data through its rest API that isn't available in prometheus. -This data give a more detailed breakdown of the trace and can be found at `/v1/metrics/traceroute` and is +This data give a more detailed breakdown of the trace and can be found at `/v1/metrics/traceroute` and is meant to be a json representation of traditional traceroute output: + ```bash $ traceroute -T -q 1 100.1.2.2 1 200.2.0.1 (200.2.0.1) 2 ms 2 11.0.0.34 (11.0.0.34) 5 ms ... ``` + Is roughly equal to this: + ```json { "data": { diff --git a/pkg/checks/traceroute/test-lab/how-to-test.md b/pkg/checks/traceroute/test-lab/how-to-test.md index 3693bb6a..1bd1947a 100644 --- a/pkg/checks/traceroute/test-lab/how-to-test.md +++ b/pkg/checks/traceroute/test-lab/how-to-test.md @@ -1,61 +1,84 @@ -# How to test the traceroute check +# How to test the traceroute check + +- [About this tool](#about-this-tool) +- [Requirements](#requirements) +- [How to](#how-to) + - [1. Start kathara network](#1-start-kathara-network) + - [2. Connect to the client system](#2-connect-to-the-client-system) + - [3. (optional) Explore the network](#3-optional-explore-the-network) + - [4. Run sparrow](#4-run-sparrow) + - [5. Other tools](#5-other-tools) + - [6. Cleaning up](#6-cleaning-up) + +## About this tool -## What is this Kathara is a container-based network emulation tool. The files in this folder configure a small test network using kathara. In this case we use kathara to locally simulate a network with a webserver, a client and multiple network hops between them. + ## Requirements -- install [ kathara ](https://github.com/KatharaFramework/Kathara) -- install wireshark (optional) + +- Install [kathara](https://github.com/KatharaFramework/Kathara) +- Install wireshark (optional) ## How to -1. Start kathara network +### 1. Start kathara network + In this folder run: + ```bash kathara lstart ``` + To prevent kathara from creating a terminal window for every container: + ```bash kathara lstart --noterminals ``` -This starts the test-lab ([ topology ](https://github.com/KatharaFramework/Kathara-Labs/blob/main/main-labs/basic-topics/static-routing/004-kathara-lab_static-routing.pdf)) +This starts the test-lab ([topology](https://github.com/KatharaFramework/Kathara-Labs/blob/main/main-labs/basic-topics/static-routing/004-kathara-lab_static-routing.pdf)) + +### 2. Connect to the client system -2. Connect to the client system In a separate terminal run: + ```bash kathara connect pc1 ``` +### 3. (optional) Explore the network -3. (optional) Explore the network Aside from you, there are two routers and a webserver in this lab. Tracerouting to the webserver shows us, that we need to go through the two routers to reach the webserver: + ```bash export WEBSERVER=200.1.1.7 root@pc1:/# traceroute $WEBSERVER traceroute to 200.1.1.7 (200.1.1.7), 30 hops max, 60 byte packets - 1 195.11.14.1 (195.11.14.1) 0.972 ms 1.093 ms 1.095 ms - 2 100.0.0.10 (100.0.0.10) 1.543 ms 1.712 ms 1.838 ms - 3 200.1.1.7 (200.1.1.7) 2.232 ms 2.310 ms 2.394 ms +1 195.11.14.1 (195.11.14.1) 0.972 ms 1.093 ms 1.095 ms +2 100.0.0.10 (100.0.0.10) 1.543 ms 1.712 ms 1.838 ms +3 200.1.1.7 (200.1.1.7) 2.232 ms 2.310 ms 2.394 ms ``` We can also look at the server website: + ```bash root@pc1:/# curl $WEBSERVER ``` + This should return the default apache website. -4. Run sparrow +### 4. Run sparrow -To run sparrow we first need to build and move the sparrow binary into the container. Luckily, kathara mounts a shared folder to all systems in the lab. -We can use this folder to run sparrow in the containers without having to build our own image! +To run sparrow we first need to build and move the sparrow binary into the container. Luckily, kathara mounts a shared folder to all systems in the lab. +We can use this folder to run sparrow in the containers without having to build our own image! ```bash go build -o sparrow . && mv sparrow pkg/checks/traceroute/test-lab/shared/ ``` Back in the client container: + ```bash root@pc1:/# cd /shared root@pc1:/shared# ./sparrow -h @@ -76,7 +99,9 @@ Flags: Use "sparrow [command] --help" for more information about a command. ``` + Now we just have to create a config for sparrow to use and we're ready to develop. For testing traceroute I used this config: + ```yaml root@pc1:/shared# cat config.yaml name: sparrow.dev @@ -95,16 +120,17 @@ traceroute: port: 80 ``` - Now just run sparrow in the shared folder: ```bash root@pc1:/shared# ./sparrow run --config config.yaml ``` -5. Other tools -The container image has a bunch of utilities for debugging network issues. If you're debugging low level issues, where you need to inspect +### 5. Other tools + +The container image has a bunch of utilities for debugging network issues. If you're debugging low level issues, where you need to inspect specific network packets you can use tcpdump directly, which is preinstalled: + ```bash root@pc1:/# tcpdump tcpdump: verbose output suppressed, use -v[v]... for full protocol decode @@ -126,11 +152,12 @@ root@pc1:/# tcpdump -w /shared/dump.pcap wireshark -r dump.pcap ``` - Happy Debugging! -6. Cleaning up +### 6. Cleaning up + Cleanup is simple: + ```bash kathara lclean ```