diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bc57f962ed..254ba066c9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -218,7 +218,7 @@ Code Structure `./po`- contains text-based portable object file. These .PO files are referenced by GNU gettext as a property file and these files are human readable used for translating purpose. -`./src`- source code for libnm, nmcli, nm-cloud-setup, nmtui… +[`./src`](src/)- source code for libnm, nmcli, nm-cloud-setup, nmtui… `./tools`- tools for generating the intermediate files or merging the file. diff --git a/src/README.md b/src/README.md new file mode 100644 index 0000000000..e923ef7f25 --- /dev/null +++ b/src/README.md @@ -0,0 +1,65 @@ +src/ +==== + +Most of the subdirectories are static helper libraries, which +get linked into one of the final build artifacts (like libnm, +nmcli or NetworkManager). Static libraries are internal API. + +The only public API is libnm, which is a shared library provided +client implementations. + +Our own clients (like nmcli and nmtui) also use libnm, the shared library. +But they also use additional static helper libraries. + +The daemon statically links against a part of libnm, the part that provides +connection profiles. That is libnm-core. libnm-core is thus statically linked +with libnm and the daemon. It does not get linked by clients that already link +with libnm (like nmtui). + +Read the individual README.md files in the subdirectories for details: + +| Directory | Description | +|------------------------------------------------------|---------------------------------------------------------| +| [core/](core/) | the NetworkManager daemon | +| [nmcli/](nmcli/) | nmcli application, a command line client for NetworkManager | +| [nmtui/](nmtui/) | nmtui application, a text UI client for NetworkManager | +| [nm-cloud-setup/](nm-cloud-setup/) | service to automatically configure NetworkManager in cloud environment | +| [nm-initrd-generator/](nm-initrd-generator/) | generates NetworkManager configuration by parsing kernel command line options for dracut/initrd | +| [nm-dispatcher/](nm-dispatcher/) | NetworkManager-dispatcher service to run user scripts | +| [nm-online/](nm-online/) | application which checks whether NetworkManager is done, for implementing NetworkManager-wait-online.service | +| [nm-sudo/](nm-sudo/) | internal service for privileged operations | +| [nm-daemon-helper/](nm-daemon-helper/) | internal helper binary spawned by NetworkManager | +| | | +| [libnm-std-aux/](libnm-std-aux/) | internal helper library for standard C | +| [libnm-glib-aux/](libnm-glib-aux/) | internal helper library for glib | +| [libnm-log-null/](libnm-log-null/) | internal helper library with dummy (null) logging backend | +| [libnm-log-core/](libnm-log-core/) | internal helper library with logging backend (syslog) used by daemon | +| [libnm-base/](libnm-base/) | internal helper library with base definitions | +| [libnm-platform/](libnm-platform/) | internal helper library for netlink and other platform/kernel API | +| [libnm-udev-aux/](libnm-udev-aux/) | internal helper library for libudev | +| | | +| [libnm-core-public/](libnm-core-public/) | public API of libnm (libnm-core part) | +| [libnm-core-intern/](libnm-core-intern/) | internal API of libnm-core, used by libnm and daemon | +| [libnm-core-impl/](libnm-core-impl/) | implementation of libnm-core | +| [libnm-core-aux-intern/](libnm-core-aux-intern/) | internal helper library on top of libnm-core (used by libnm-core itself) | +| [libnm-core-aux-extern/](libnm-core-aux-extern/) | internal helper library on top of libnm-core (not used by libnm-core) | +| [libnm-client-public/](libnm-client-public/) | public API of libnm (NMClient part) | +| [libnm-client-impl/](libnm-client-impl/) | implementation of libnm (NMClient) | +| [libnm-client-aux-extern/](libnm-client-aux-extern/) | internal helper library on top of libnm (not used by libnm itself) | +| [libnmc-base/](libnmc-base/) | internal helper library for libnm clients | +| [libnmc-setting/](libnmc-setting/) | internal helper library for setting connection profiles (used by nmcli) | +| [libnmt-newt/](libnmt-newt/) | internal helper library for libnewt for nmtui | +| | | +| [linux-headers/](linux-headers/) | extra Linux kernel UAPI headers | +| [contrib/](contrib/) | sources that are not used by NetworkManager itself | +| [tests/](tests/) | unit tests that are not specific to one of the other directories | +| [libnm-client-test/](libnm-client-test/) | internal helper library with test utils for libnm | +| | | +| [c-list/](c-list/) | fork of c-util helper library for intrusive, doubly linked list | +| [c-rbtree/](c-rbtree/) | fork of c-util helper library for intrusive Red-Black Tree | +| [c-siphash/](c-siphash/) | fork of c-util helper library for SIPHash24 | +| [c-stdaux/](c-stdaux/) | fork of c-util general purpose helpers for standard C | +| [n-acd/](n-acd/) | fork of nettools IPv4 ACD library | +| [n-dhcp4/](n-dhcp4/) | fork of nettools DHCPv4 library | +| [libnm-systemd-core/](libnm-systemd-core/) | fork of systemd code as network library | +| [libnm-systemd-shared/](libnm-systemd-shared/) | fork of systemd code as general purpose library | diff --git a/src/contrib/README.md b/src/contrib/README.md new file mode 100644 index 0000000000..81ebaf0331 --- /dev/null +++ b/src/contrib/README.md @@ -0,0 +1,11 @@ +contrib +======= + +This directories contains miscellaneous helpers. +This code is not actually used anywhere in our source +tree (beside unit tests). + +The purpose is that a external libnm/NetworkManager user +can copy+paste these helpers into their source three. This +code should act as an example but also be directly usable +by copying. diff --git a/src/core/README.md b/src/core/README.md new file mode 100644 index 0000000000..13779197fd --- /dev/null +++ b/src/core/README.md @@ -0,0 +1,9 @@ +core +==== + +The source code of the NetworkManager daemon. + +NetworkManager is a daemon that provides a D-Bus API and a file-based +API for configuring the network on a Linux host. + +This is the daemon source code. diff --git a/src/libnm-base/README.md b/src/libnm-base/README.md new file mode 100644 index 0000000000..8eb2119a18 --- /dev/null +++ b/src/libnm-base/README.md @@ -0,0 +1,20 @@ +libnm-base +========== + +A static helper library with network/NetworkManager specific +code. + +Contrary to libnm-glib-aux, this does not contain general purpose +helpers, but code that is more specific about NetworkManager. + +This is the most low-level dependency of this kind. Most NetworkManager +specific code will directly or indirectly link with this. + +As this is a static library, there is no problem with dragging this into your +binary/library, if your application already depends on libnm-glib-aux (and glib). + +Dependencies: + + - glib + - [../libnm-std-aux/](../libnm-std-aux/) + - [../libnm-glib-aux/](../libnm-glib-aux/) diff --git a/src/libnm-client-aux-extern/README.md b/src/libnm-client-aux-extern/README.md index 460b269e6d..7d3b27e890 100644 --- a/src/libnm-client-aux-extern/README.md +++ b/src/libnm-client-aux-extern/README.md @@ -1,4 +1,7 @@ -nm-libnm-aux is a static library that: +libnm-client-aux-extern +======================= + +libnm-client-aux-extern is a static library that: - uses the public parts of "libnm" - that can also be statically linked into other users of libnm. @@ -10,6 +13,10 @@ That means: - you can use it everywhere where you dynamically link with libnm. -Also, since nm-libnm-aux itself only uses public (stable) +Also, since libnm-client-aux-extern itself only uses public (stable) API of libnm, you theoretically can copy the sources into your own source tree. + +This makes it very similar in purpose to [../libnmc-base/](../libnmc-base/). +The difference might be that this one is smaller and that you could easier +copy+paste this to a libnm application outside this source tree. diff --git a/src/libnm-client-impl/README.md b/src/libnm-client-impl/README.md new file mode 100644 index 0000000000..1ec481c1ac --- /dev/null +++ b/src/libnm-client-impl/README.md @@ -0,0 +1,14 @@ +libnm-client-impl +================= + +libnm is NetworkManager's client API. +This API consists of two parts: + +- the handling of connections (`NMConnection`), implemented + by libnm-core-impl. +- the caching of D-Bus API (`NMClient`), implemented by + libnm-client-impl. + +This directory contains the implementation of the second part. +As such, it will be statically linked with libnm-core-impl +to make libnm. Also, it cannot be used by the daemon. diff --git a/src/libnm-client-public/README.md b/src/libnm-client-public/README.md new file mode 100644 index 0000000000..a4ecb06627 --- /dev/null +++ b/src/libnm-client-public/README.md @@ -0,0 +1,16 @@ +libnm-client-public +=================== + +libnm is NetworkManager's client API. It has a public API. +This API consists of two parts: + +- the handling of connections (`NMConnection`), implemented + by libnm-core-impl. +- the caching of D-Bus API (`NMClient`), implemented by + libnm-client-impl. + +This directory contains public headers that are used by libnm +users. As such, it's the `NMClient` part of libnm-core-public. + +These headers are usable to any libnm client application and +to libnm itself. But not to libnm-core-impl or the daemon. diff --git a/src/libnm-client-test/README.md b/src/libnm-client-test/README.md new file mode 100644 index 0000000000..f06220b47a --- /dev/null +++ b/src/libnm-client-test/README.md @@ -0,0 +1,11 @@ +libnm-client-test +================= + +A static helper library that is used by unit tests +on top of libnm. Mostly it's D-Bus helpers. + +It has no purpose in non-test code. + +Unit tests may not dynamically link with libnm. They +may also statically link with the relevant parts of libnm, +and still be able to use this helper. diff --git a/src/libnm-glib-aux/README.md b/src/libnm-glib-aux/README.md new file mode 100644 index 0000000000..cb43e87c69 --- /dev/null +++ b/src/libnm-glib-aux/README.md @@ -0,0 +1,16 @@ +libnm-glib-aux +============== + +A static helper library with general purpose helpers on top +of glib. + +This is similar to libnm-std-aux (on which this library depends). +The difference is that libnm-std-aux only requires standard C (C11), +while this has a dependency on glib. + +As this has no additional dependencies, we should have all our glib code +use this internal helper library. It contains helpers that should be +available (and used) in all our C/glib applications/libraries. + +Parts of this library are usually already included via the `nm-default*.h` +headers. diff --git a/src/libnm-log-core/README.md b/src/libnm-log-core/README.md new file mode 100644 index 0000000000..4223232bfa --- /dev/null +++ b/src/libnm-log-core/README.md @@ -0,0 +1,10 @@ +libnm-log-core +============== + +libnm-glib-aux has a forward-declaration of logging API. +If a libnm-glib-aux user uses that API for logging, it must +link the final binary with an implementation. + +There are two implementations: libnm-log-core and +[../libnm-log-null/(..libnm-log-null/). This one is the implementation +used by the daemon and logs to syslog/journald. diff --git a/src/libnm-log-null/README.md b/src/libnm-log-null/README.md new file mode 100644 index 0000000000..eb5d0821a9 --- /dev/null +++ b/src/libnm-log-null/README.md @@ -0,0 +1,10 @@ +libnm-log-null +============== + +libnm-glib-aux has a forward-declaration of logging API. +If a libnm-glib-aux user uses that API for logging, it must +link the final binary with an implementation. + +There are two implementations: libnm-log-null and +[../libnm-log-core/(..libnm-log-core/). This one is a dummy implementation +that drops all logging. diff --git a/src/libnm-platform/README.md b/src/libnm-platform/README.md new file mode 100644 index 0000000000..c8e7cf7679 --- /dev/null +++ b/src/libnm-platform/README.md @@ -0,0 +1,22 @@ +libnm-platform +============== + +A static helper library that provides `NMPlatform` and other utils. +This is NetworkManager's internal netlink library, but also contains +helpers for sysfs, ethtool and other kernel APIs. + +`NMPlaform` is also a cache of objects of the netlink API: `NMPCache` +and `NMPObject`. These objects are used throughout NetworkManager +also for generally tracking information about these types. For example, +`NMPlatformIP4Address` (the public part of a certain type of `NMPObject`) +is not only used to track platform addresses from netlink in the cache, +but to track information about IPv4 addresses in general. + +This depends on the following helper libraries + + - [../libnm-std-aux/](../libnm-std-aux/) + - [../libnm-base/](../libnm-base/) + - [../libnm-glib-aux/](../libnm-glib-aux/) + - [../libnm-udev-aux/](../libnm-udev-aux/) + - [../libnm-log-core/](../libnm-log-core/) + - [../linux-headers/](../linux-headers/) diff --git a/src/libnm-std-aux/README.md b/src/libnm-std-aux/README.md new file mode 100644 index 0000000000..ccc48e9dc8 --- /dev/null +++ b/src/libnm-std-aux/README.md @@ -0,0 +1,16 @@ +libnm-std-aux +============= + +A static helper library with general purpose helpers on top of +standard C (C11). + +As this has no additional dependencies, we should have all our C code +use this internal helper library. It contains helpers that should be +available (and used) everywhere where we write C. + +Our C is gnu11, that is C11 or newer with some GCC-ism. The requirement +is that it is supported by all complilers we care about (in pratice GCC +and Clang). + +Parts of this library are usually already included via the `nm-default*.h` +headers. diff --git a/src/libnm-systemd-core/README.md b/src/libnm-systemd-core/README.md new file mode 100644 index 0000000000..b9792ca705 --- /dev/null +++ b/src/libnm-systemd-core/README.md @@ -0,0 +1,16 @@ +libnm-systemd-core +================== + +This is a fork of systemd source files that are compiled +as a static library with network helpers. + +We use systemd's DHCPv6 and LLDP library, by forking their code. + +We also still use their DHCPv4 library, but that is about to be replaced +by nettools' n-dhcp4. + +This approach of code-reuse is very cumbersome, and we should replace +systemd code by a proper library (like nettools). + +We should not use systemd directly from our sources, beyond what +we really need. diff --git a/src/libnm-systemd-shared/README.md b/src/libnm-systemd-shared/README.md new file mode 100644 index 0000000000..67ad4875c2 --- /dev/null +++ b/src/libnm-systemd-shared/README.md @@ -0,0 +1,11 @@ +libnm-systemd-shared +==================== + +This is a fork of systemd source files that are compiled +as a static library with general purpose helpers. + +We mainly need this for [../libnm-systemd-core/](../libnm-systemd-core/), +which contains systemd library with network tools (like DHCPv6). + +We should not use systemd directly from our sources, beyond what +we really need to make get libnm-systemd-core working. diff --git a/src/libnm-udev-aux/README.md b/src/libnm-udev-aux/README.md new file mode 100644 index 0000000000..648f792ca8 --- /dev/null +++ b/src/libnm-udev-aux/README.md @@ -0,0 +1,9 @@ +libnm-udev-aux +============== + +Static helper library with tools around libudev. + +This library depends on glib and libudev: + + - [../libnm-std-aux/](../libnm-std-aux/) + - [../libnm-glib-aux/](../libnm-glib-aux/) diff --git a/src/libnmc-base/README.md b/src/libnmc-base/README.md new file mode 100644 index 0000000000..8038c785a9 --- /dev/null +++ b/src/libnmc-base/README.md @@ -0,0 +1,12 @@ +libnmc-base +=========== + +A helper library on top of libnm for our clients. +The "c" in "libnmc-base" stands for clients. + +This has no additional dependencies on top of libnm, +so any client application that uses libnm can statically +link with this helper at will. + +As such, this is very similar in purpose to [../libnm-client-aux-extern](../libnm-client-aux-extern), +the difference is only in scope. diff --git a/src/libnmc-setting/README.md b/src/libnmc-setting/README.md new file mode 100644 index 0000000000..6ed424353a --- /dev/null +++ b/src/libnmc-setting/README.md @@ -0,0 +1,17 @@ +libnmc-setting +============== + +A client library on top of libnm (and libnm-base). +Like libnmc-base, this is a helper library that a libnm +client could use. + +But its purpose is more specific. It's mainly about providing +a generic API for handling connection properties. As such, it's +only used by nmcli and in practice also specific to nmcli. + +Theoretically, the API is supposed to be generic, so we could +imagine another client that uses this beside nmcli. + +Like libnm-base, this has a similar purpose and application +as [../libnm-client-aux-extern/](../libnm-client-aux-extern/), +the difference is that it's even more specific. diff --git a/src/libnmt-newt/README.md b/src/libnmt-newt/README.md new file mode 100644 index 0000000000..386a86cb2d --- /dev/null +++ b/src/libnmt-newt/README.md @@ -0,0 +1,4 @@ +libnmt-newt +=========== + +A helper library of UI elements on top of libnewt and libnm, for nmtui. diff --git a/src/linux-headers/README.md b/src/linux-headers/README.md new file mode 100644 index 0000000000..382632b995 --- /dev/null +++ b/src/linux-headers/README.md @@ -0,0 +1,10 @@ +linux-headers +============= + +Contains a copy of Linux UAPI kernel headers. +When we build against an older kernel, we may +still want to unconditionally build against a +certain version of kernel API. + +These headers should be taken without modification +from Linux. diff --git a/src/nm-cloud-setup/README.md b/src/nm-cloud-setup/README.md new file mode 100644 index 0000000000..e484aa20df --- /dev/null +++ b/src/nm-cloud-setup/README.md @@ -0,0 +1,8 @@ +nm-cloud-setup +============== + +A NetworkManager client application that aims to automatically +configure the network in a cloud environment. + +See: +- `man 8 nm-cloud-setup` ([[www]](https://networkmanager.dev/docs/api/latest/nm-cloud-setup.html)) diff --git a/src/nm-daemon-helper/README.md b/src/nm-daemon-helper/README.md new file mode 100644 index 0000000000..695f533553 --- /dev/null +++ b/src/nm-daemon-helper/README.md @@ -0,0 +1,11 @@ +nm-daemon-helper +================ + +A internal helper application that is spawned by NetworkManager +to perform certain actions. + +Currently all it does is doing a reverse DNS lookup, which +cannot be done by NetworkManager because the operation requires +to reconfigure the libc resolver (which is a process-wide operation). + +This is not directly useful to the user. diff --git a/src/nm-dispatcher/README.md b/src/nm-dispatcher/README.md new file mode 100644 index 0000000000..53c8c70945 --- /dev/null +++ b/src/nm-dispatcher/README.md @@ -0,0 +1,15 @@ +nm-dispatcher +============= + +Runs as a D-Bus activated, exit-on-idle service to execute +user scripts (dispatcher scripts) on certain events. + +The user does not directly configure this service, it gets +controlled by NetworkManager. However, the user (or other +applications) would place scripts in certain directories for +the dispatcher service to execute them. + +The systemd service is called `NetworkManager-dispatcher.service`. + +See: +- `man 8 NetworkManager-dispatcher` ([[www]](https://networkmanager.dev/docs/api/latest/NetworkManager-dispatcher.html)) diff --git a/src/nm-initrd-generator/README.md b/src/nm-initrd-generator/README.md new file mode 100644 index 0000000000..cc995f5fd1 --- /dev/null +++ b/src/nm-initrd-generator/README.md @@ -0,0 +1,12 @@ +nm-initrd-generator +=================== + +A command line tool that generates NetworkManager configuration. + +This is supposed to be run by dracut in initrd, before NetworkManager +starts. It parses the kernel command line, generates configuration +and quits. + +See: +- `man 8 nm-initrd-generator` ([[www]](https://networkmanager.dev/docs/api/latest/nm-initrd-generator.html)) +- `man 7 dracut.cmdline` diff --git a/src/nm-online/README.md b/src/nm-online/README.md new file mode 100644 index 0000000000..eaa909f717 --- /dev/null +++ b/src/nm-online/README.md @@ -0,0 +1,14 @@ +nm-online +========= + +A small NetworkManager client that blocks until +NetworkManager is done configuring the interfaces. + +This is not very useful to the end user. It is used +by `NetworkManager-wait-online.service` to determine +when NetworkManager is done with startup. + +See: + +- `man 1 nm-online` ([[www]](https://networkmanager.dev/docs/api/latest/nm-online.html)) +- `systemctl cat NetworkManager-wait-online.service` diff --git a/src/nm-sudo/README.md b/src/nm-sudo/README.md new file mode 100644 index 0000000000..13fd488185 --- /dev/null +++ b/src/nm-sudo/README.md @@ -0,0 +1,21 @@ +nm-sudo +======= + +This is a D-Bus activatable, exit-on-idle service, which +provides an internal API to NetworkManager daemon. + +This has no purpose for the user, it is an implementation detail +of the daemon. + +The purpose is that `nm-sudo` can execute certain operations, +which NetworkManager process is not allowed to. We want to +sandbox NetworkManager as much as possible, and nm-sudo provides +a controlled way to perform some very specific operations. + +As such, nm-sudo should still be sandboxed too to only being +able to execute the operations that are necessary for NetworkManager. + +nm-sudo will reject all D-Bus requests that are not originating +from the current name owner of "org.freedesktop.NetworkManager". +That is, it is supposed to only reply to NetworkManager daemon +and as such is not useful to the user directly. diff --git a/src/nmcli/README.md b/src/nmcli/README.md new file mode 100644 index 0000000000..a828a762cd --- /dev/null +++ b/src/nmcli/README.md @@ -0,0 +1,13 @@ +nmcli +===== + +The command line user interface of NetworkManager. +It uses the D-Bus API of NetworkManager (via libnm). + +See: + +- `man 1 nmcli` ([[www]](https://networkmanager.dev/docs/api/latest/nmcli.html)) +- `man 7 nmcli-examples` ([[www]](https://networkmanager.dev/docs/api/latest/nmcli-examples.html)) +- `man 5 nm-settings-nmcli` ([[www]](https://networkmanager.dev/docs/api/latest/nm-settings-nmcli.html)) + +Try also with bash-completion! diff --git a/src/nmtui/README.md b/src/nmtui/README.md new file mode 100644 index 0000000000..5205f48095 --- /dev/null +++ b/src/nmtui/README.md @@ -0,0 +1,15 @@ +nmtui +===== + +The curses-based text user interface of NetworkManager. +It uses the D-Bus API of NetworkManager (via libnm). + +This is a NetworkManager client applications that can +edit connection profiles and activate them, by providing +a text UI. + +It uses libnewt. + +See: + +- `man 1 nmtui` ([[www]](https://networkmanager.dev/docs/api/latest/nmtui.html)) diff --git a/src/tests/README.md b/src/tests/README.md new file mode 100644 index 0000000000..7ffae40ddd --- /dev/null +++ b/src/tests/README.md @@ -0,0 +1,8 @@ +tests +===== + +Contains some unit tests that don't clearly fit a category +to be placed in a different location. + +Maybe a better place should be found and this directory should +go away.