readme: Better usage guide

Signed-off-by: Casper Andersson <[email protected]>

README.md

@@ -3,30 +3,85 @@ SPDX-License-Identifier: GPL-2.0-only
 SPDX-FileCopyrightText: 2023 Casper Andersson <[email protected]>
 -->
 
-# capmon - Linux Capabilities checker/monitor
+# Capmon - Linux Capabilities checker/monitor
 
 Monitor when processes check
 [capabilities(7)](https://man7.org/linux/man-pages/man7/capabilities.7.html) to
-find out what they require. Run `capmon <YOUR COMMAND>` to track the
-capabilities it requires. It's important to **not** run your command with sudo
-since that bypasses certain checks. Let the command fail at the first missing
-capability check and add that capability, then try again and see if if fails on
-more. Rinse and repeat until command runs successfully.
+find out what they require. Run `capmon '<COMMAND>'` to track the capabilities
+it accesses. It's important to **not** run your command with sudo since that
+bypasses certain checks. Let the command fail at the first missing capability
+check and add that capability, then try again and see if if fails on more.
+Rinse and repeat until command runs successfully.
 
-# Table of Contents
+For an introduction to capabilities see [A simpler life without
+sudo](https://casan.se/blog/linux/a-simpler-life-without-sudo/).
+
+## Table of Contents
+- [Usage](#usage)
+  - [Using without sudo](#using-without-sudo)
+  - [Legacy mode](#legacy-mode)
 - [Installation](#installation)
   - [Build dependencies](#build-dependencies)
   - [Run dependencies](#run-dependencies)
-- [Usage](#usage)
-  - [Using without sudo](#using-without-sudo)
 - [Contributing](#contributing)
-- [Issues](#issues)
 
 
+## Usage
 
-<a name="installation"/>
+To use Capmon do
+```sh
+capmon '<cmd>'
+```
 
-# Installation
+For example:
+```sh
+capmon 'ip link netns add test'
+```
+
+It is recommended to enclose the command in quotes to avoid the shell from doing
+any funny business with globbing or other special features, and to avoid Capmon
+from interpreting the command's argument as its own. Capmon will run the command
+with `/bin/sh`.
+
+The output of the above command will be
+```sh
+[ip]
+- [PASS] CAP_DAC_OVERRIDE
+- [PASS] CAP_NET_ADMIN
+```
+because the `ip` command required the capabilities `CAP_NET_ADMIN` and
+`CAP_DAC_OVERRIDE` for this particular task. Another example, `ip link set dev
+tap0 up` only requires `CAP_NET_ADMIN`.
+
+If the user didn't have the capabilities it would instead report `[FAIL]` on one
+of the capabilities. If it failed on the first of the two then it may not even
+show the second since commands often bail out as soon as they fail to do
+something.
+
+If a command is still failing even though Capmon doesn't report anything there
+is the flag `-a` or `--all`. This changes the place where it listens to another
+location which covers many more checks, some of which are not always necessary
+and are allowed to fail. This is not the default mode as to not confuse the
+user with a bunch of capabilities that usually will not matter.
+
+### Using without sudo
+It is recommended to give Capmon the capabilities it needs. Running it with
+sudo will pass sudo rights to any child processes, preventing the return value
+of the cap check to be correct.
+
+To use Capmon without sudo you must assign `CAP_DAC_OVERRIDE` and
+`CAP_SYS_ADMIN` to yourself and to `capmon`. For a guide on how to set
+capabilities see [A simpler life without
+sudo](https://casan.se/blog/linux/a-simpler-life-without-sudo/).
+
+### Legacy mode
+
+See [Monitor mode documentation](doc/monitor.md) for usage of the legacy
+monitor mode.
+
+
+
+## Installation
 
 ```
 make
@@ -35,77 +90,25 @@ sudo make install
 The Makefile is a wrapper around CMake that will fetch the submodules and
 output any build artifacts into the `build/` directory.
 
-
-
-<a name="build-dependencies"/>
-
-## Build dependencies
+### Build dependencies
 
 These should be available on most modern Linux distributions.
 ```
 sudo apt install cmake clang llvm libelf1 libelf-dev zlib1g-dev
 ```
 - `CONFIG_PERF_EVENTS=y`?
-- Kernel >= 5.10? ([BPF CO-RE](
+- Linux kernel >= 5.10? ([BPF CO-RE](
   https://patchwork.ozlabs.org/project/buildroot/patch/[email protected]/))
 
-
-
-<a name="run-dependencies"/>
-
-## Run dependencies
+### Run dependencies
 
 - `CONFIG_DEBUG_INFO_BTF=y`
 - Linux kernel >= 5.8 (BPF ring buffer)
 
 
 
-<a name="usage"/>
-
-# Usage
-Check what capabilities it requires to run the command `ip link set dev eth0
-down`. Capmon will output what the different processes (main and subprocesses)
-requests.
-```
-capmon ip link set dev eth0 down
-```
-
-See [Monitor mode documentation](doc/monitor.md) for usage of the legacy monitor mode.
-
-
-
-<a name="using-without-sudo"/>
-
-## Using without sudo
-It is recommended to give Capmon the capabilities it needs. Running it with
-sudo will pass sudo rights to any child processes, preventing the return value
-of the cap check to be correct.
-
-To use Capmon without sudo you must assign `CAP_DAC_OVERRIDE` and
-`CAP_SYS_ADMIN` to yourself and to `capmon`. Check out [this post by
-Troglobit](https://troglobit.com/2016/12/11/a-life-without-sudo/) on how to use
-capabilities.
-
-
-
-<a name="contributing"/>
-
-# Contributing
+## Contributing
 
 For more detailed explanation on building it and how it works see
 [CONTRIBUTING.md](doc/CONTRIBUTING.md)
 
-
-
-<a name="issues"/>
-
-# Issues
-
-- To get correct comm names (process names) you can do `sudo sh` and run the commands.
-  Otherwise, the desktop manager may take over the name. (Not sure if it's
-  still an issue with process tracking)
-- Note that some kernel functions will call `cap_capable` directly, instead of
-  going through the other functions. Or they use some other less-common path.
-  Use the flag `-a` to track everything.
-
-