ping-api

Simple HTTP API wrapper around the ping crate to make an ICMP ping to a domain/IP.

Usage

In the request a endpoints array should be passed with domains and/or IP addresses to be pinged. Domains will be resolved to IP addresses to do the ping but need a port at the end (use <domain>:0 to not specify the port).

An optional ping_type property is available to specify whether the ping should use a RAW socket or a DGRAM socket. The default is DGRAM as it possibly does not require elevated privileges (depending on Linux distribution) to do the ping.

An optional timeout property is also available to specify the time a ping can take before being timed out. This is specified as a number in seconds and defaults to a 30 second timeout.

For example, using this test_v1.json file and the ping-api server running on port 8000:

{
  "ping_type": "DGRAM",
  "timeout": 30,
  "endpoints": [
    "127.0.0.1",
    "localhost:0"
  ]
}

curl -X POST http://127.0.0.1:8000/api/v1/ping -d @test_v1.json

Will result in something like the following JSON response:

[
  {
    "endpoint": "127.0.0.1",
    "ping_type": "DGRAM",
    "status": "success",
    "data": {
      "source": "127.0.0.1",
      "rtt_nanoseconds": 89450,
      "rtt_milliseconds": 0
    }
  },
  {
    "endpoint": "localhost:0",
    "ping_type": "DGRAM",
    "status": "success",
    "data": {
      "source": "::1",
      "rtt_nanoseconds": 33880,
      "rtt_milliseconds": 0
    }
  }
]

The status property will be "success" when the ping was successful and error: <error message> when an error occurred.

In the data object the round-trip time rtt_... will be returned in milliseconds and nanoseconds (useful for when the rtt is less than a millisecond). The source property will also be set to the actual source IP address that replied to the ping.

Example deployment with NixOS

Here is an example deployment I use in my NixOS configuration that builds the derivation.nix as a package and then uses it inside a Systemd service.

# imports/ping-api.nix
{ lib, pkgs, ... }:

let
  src = pkgs.fetchFromGitea {
    domain = "forgejo.drijkoningen.dev";
    owner = "bauke";
    repo = "ping-api";
    rev = "3236f6abb38ab87540fc693570b647a3ef6bb47f";
    sha256 = "sha256-m/oan9kOWQZMcrhpHGujzopSEzoLhgS88psjj7WaJi4=";
  };
in
pkgs.callPackage "${src}/derivation.nix" { }

# systemd/ping-api.nix
{ config, pkgs, ... }:

let
  ping-api = (pkgs.callPackage ../imports/ping-api.nix { });
in
{
  systemd.services."ping-api" = {
    path = [
      ping-api
    ];

    wantedBy = [ "multi-user.target" ];

    serviceConfig = {
      # NOTE: Run at port 8161, this can be any available port.
      Environment = "ROCKET_PORT=8161";
      ExecStart = "${ping-api}/bin/ping-api";
      Type = "simple";
    };
  };
}