/ README.md
README.md
1 <!-- 2 SPDX-FileCopyrightText: Copyright (C) 2024-2025 Marek Küthe <m.k@mk16.de> 3 4 SPDX-License-Identifier: GPL-3.0-or-later 5 --> 6 7 # mping-sender 8 9 [](https://ci.codeberg.org/repos/13147) 10 [](https://www.bestpractices.dev/projects/11574) 11 12 mping-sender is a simple multicast transmitter that sends a UDP packet every second. 13 14  15 16 mping-sendet is a multicast sender designed to provide a simple multicast source that periodically sends out UDP packets to test multicast functionality. 17 18 mping-sendet sends a UDP packet every second. The source and destination can be specified using command line arguments. 19 The UDP packet attempts to follow large parts of the [mping](https://github.com/troglobit/mping/) implementation with an empty payload. 20 21 ## Building 22 23 See [BUILDING.md](BUILDING.md). 24 25 ## Contributing 26 27 See [CONTRIBUTING.md](CONTRIBUTING.md). 28 29 ## Security 30 31 On Linux, mping-sender uses three sandboxing technologies or restriction technologies: Capabilities, seccomp and landlock, systemd, and AppArmor. 32 These serve to limit the extent of compromise if mping-sender is compromised by an attack. 33 34 ### Capabilities 35 36 In Linux, capabilities are used to restrict what a program is allowed to do, especially when interacting with the system. mping-sender requires one capability: `CAP_SETPCAP`. 37 `CAP_SETPCAP` is required to restrict its own capabilities. 38 systemd and AppArmor ensure on Linux that mping-sender does not receive any other capabilities. 39 mping-sender drops all granted capabilities, as no special rights are required to send UDP packets via the operating system interface. 40 Furthermore, libcap-ng performs a "lock": If supported, NoNewPriv and securebits are set. 41 42 ### Seccomp 43 44 mping-sender uses the boost library. Boost use syscalls. However, it is not documented which ones boost use. Creating a whitelist - especially one that is distribution-independent - has therefore proven difficult. 45 For this reason, seccomp is used to blacklist syscalls that mping-sender does not need. 46 47 ### Landlock 48 49 Landlock can restrict what a program can access. At the beginning, a complete landlock sandbox is created. Only necessary permissions are granted - currently none. 50 51 Landlock offers backward compatibility with older kernels through a dynamic ABI query. However, to reduce maintenance effort, a certain Landlock version is required. This should be based on Debian. 52 53 ### AppArmor 54 55 AppArmor restricts mping-sender by determining what mping-sender is allowed to do. Unnecessary operations are therefore blocked by AppArmor. 56 57 ### systemd 58 59 mping-sender comes with a hardened systemd unit that restricts many accesses not used by mping-sender. 60 61 See [SECURITY.md](SECURITY.md). 62 63 ## How it works? 64 65 mping-sender uses several libraries to send periodic UDP packets. 66 67 Libraries used: 68 69 - [Boost.Log](https://www.boost.org/): This library is used as a logger. Various log levels can be set in the configuration file. 70 - [Boost.Program_options](https://www.boost.org/): This library is used to parse the command line options. 71 - [Boost.Asio](https://www.boost.org/): This library is used to communicate with the socket of the TAP device and to receive and send several packets asynchronously. 72 73 Optional libraries: 74 75 - [libcap-ng](https://people.redhat.com/sgrubb/libcap-ng/): Used to discard unnecessary capabilities and restrict the program. 76 - [libseccomp](https://github.com/seccomp/libseccomp): Used to block potentially dangerous system calls. 77 - [landlock](https://landlock.io/): Used to restrict access. 78 79 Here is how the program works: 80 81 1. reading the command line parameters 82 2. setting the log level 83 3. output of the versions 84 4. creation of the UDP socket 85 5. starting timer 86 87 The following happens when the timer triggers: 88 89 1. the timer is reset. 90 2. a UDP packet is sent with the current time. 91 3. the sequence number is increased by one. 92 93 ## Configuration 94 95 ``` 96 mping-sender 97 98 Usage: mping-sender [configuration] 99 100 Configuration: 101 --help Help screen 102 --log-level arg (=info) Log level. Valid options are trace, debug, info, 103 warning, error and fatal. Defaults to info. 104 --bind-address arg Address to which the UDP socket is bound. Required. 105 --bind-port arg (=4321) Port to which the UDP socket is bound. Defaults to 106 4321. 107 --address arg (=ff2e::42) Address to send packets to. Defaults to ff2e::42 108 --port arg (=4321) Address to which the packages are sent. 109 --ttl arg (=@) TTTL or hop limit with which the packets are sent. 110 Defaults to 64. 111 --interface-name arg Name of the interface from which the packets are 112 sent. Required. 113 114 ``` 115 116 The log level can have one of the following values: 117 118 - `trace` 119 - `debug` 120 - `info` 121 - `warning` 122 - `error` 123 - `fatal` 124 125 For production, "info" or lower is recommended. 126 127 ## Notes for myself 128 129 ### Create a new release 130 131 To create a new release the following is necessary: 132 133 - Create a changelog entry 134 - Create a changelog entry for the Debian package 135 - Update the SECURITY.md 136 - Update version in PKGBUILD 137 - Create a new git tag 138 139 *Note*: The WireShark plugin uses separate versioning.