From a2c9509a4ab22380937a2b613fcc518da22f5166 Mon Sep 17 00:00:00 2001 From: Nathan Skrzypczak Date: Fri, 8 Oct 2021 14:05:58 +0200 Subject: docs: convert extras doc md->rst Type: improvement Change-Id: Ie3b25a86b99098d2b3a21a11fc73234c8ed589d6 Signed-off-by: Nathan Skrzypczak --- extras/vpp_stats_fs/README.md | 113 ------------------------------- extras/vpp_stats_fs/README.rst | 148 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 148 insertions(+), 113 deletions(-) delete mode 100755 extras/vpp_stats_fs/README.md create mode 100644 extras/vpp_stats_fs/README.rst (limited to 'extras/vpp_stats_fs') diff --git a/extras/vpp_stats_fs/README.md b/extras/vpp_stats_fs/README.md deleted file mode 100755 index 52610feba94..00000000000 --- a/extras/vpp_stats_fs/README.md +++ /dev/null @@ -1,113 +0,0 @@ -# VPP stats segment FUSE filesystem {#stats_fs_doc} - -The statfs binary allows to create a FUSE filesystem to expose and to browse the stats segment. -It relies on the Go-FUSE library and requires Go-VPP stats bindings to work. - -The binary mounts a filesystem on the local machine whith the data from the stats segments. -The counters can be opened and read as files (e.g. in a Unix shell). -Note that the value of a counter is determined when the corresponding file is opened (as for /proc/interrupts). - -Directories update their contents on epoch changes so that new counters get added to the filesystem. - -The script `install.sh` is responsible for buildiing and installing the filesystem. - -## Usage - -The local Makefile contains targets for all the possible intercations with the stats_f binary. - -### Help -A basic help menu -```bash -make help -``` - -### Install -Building the binary -```bash -make install -``` - -### Start -Starts the filesystem. Requires a running VPP instance using the default socket /run/vpp/stats.sock. - -May require a privileged user (sudo) -```bash -make start -``` - -### Stop -Stops and unmounts the filesystem if it is not busy. - -May require a privileged user (sudo) -```bash -make stop -``` - -### Force unmount -Forces the unmount of the filesystem even if it is busy. - -May require a privileged user (sudo) -```bash -make force-unmount -``` - -### Cleanup -Cleaning stats_fs binary. - -May require a privileged user (sudo). -```bash -make clean -``` - -## Browsing the filesystem - -The default mountpoint is /run/vpp/stats_fs_dir. -You can browse the filesystem as a regular user. -Example: - -```bash -cd /run/vpp/stats_fs_dir -cd sys/node -ls -al -cat names -``` - -## Building and mounting the filesystem manually - -For more modularity, you can build and mount the filesystem manually. - -### Building -Inside the local directory, you can build the go binary: -```bash -go build -``` - -### Mounting -Then, ou can mount the filesystem with the local binary. - -May require a privileged user (sudo). - -The basic usage is: -```bash -./stats_fs -``` - -**Options:** - - debug \ (default is false) - - socket \ (default is /run/vpp/stats.sock) : VPP socket for stats - - -### Unmounting the file system - -You can unmount the filesystem with the fusermount command. - -May require a privileged user (sudo) - -```bash -fusermount -u /path/to/mountpoint -``` - -To force the unmount even if the resource is busy, add the -z option: -```bash -fusermount -uz /path/to/mountpoint -``` diff --git a/extras/vpp_stats_fs/README.rst b/extras/vpp_stats_fs/README.rst new file mode 100644 index 00000000000..d6635d146c0 --- /dev/null +++ b/extras/vpp_stats_fs/README.rst @@ -0,0 +1,148 @@ +.. _stats_fs_doc: + +VPP stats segment FUSE filesystem +================================= + +The statfs binary allows to create a FUSE filesystem to expose and to +browse the stats segment. It relies on the Go-FUSE library and requires +Go-VPP stats bindings to work. + +The binary mounts a filesystem on the local machine with the data from +the stats segments. The counters can be opened and read as files +(e.g. in a Unix shell). Note that the value of a counter is determined +when the corresponding file is opened (as for /proc/interrupts). + +Directories update their contents on epoch changes so that new counters +get added to the filesystem. + +The script ``install.sh`` is responsible for building and installing +the filesystem. + +Usage +----- + +The local Makefile contains targets for all the possible interactions +with the stats_f binary. + +Help +~~~~ + +A basic help menu + +.. code:: bash + + make help + +Install +~~~~~~~ + +Building the binary + +.. code:: bash + + make install + +Start +~~~~~ + +Starts the filesystem. Requires a running VPP instance using the default +socket /run/vpp/stats.sock. + +May require a privileged user (sudo) + +.. code:: bash + + make start + +Stop +~~~~ + +Stops and unmounts the filesystem if it is not busy. + +May require a privileged user (sudo) + +.. code:: bash + + make stop + +Force unmount +~~~~~~~~~~~~~ + +Forces the unmount of the filesystem even if it is busy. + +May require a privileged user (sudo) + +.. code:: bash + + make force-unmount + +Cleanup +~~~~~~~ + +Cleaning stats_fs binary. + +May require a privileged user (sudo). + +.. code:: bash + + make clean + +Browsing the filesystem +----------------------- + +The default mountpoint is /run/vpp/stats_fs_dir. You can browse the +filesystem as a regular user. Example: + +.. code:: bash + + cd /run/vpp/stats_fs_dir + cd sys/node + ls -al + cat names + +Building and mounting the filesystem manually +--------------------------------------------- + +For more modularity, you can build and mount the filesystem manually. + +Building +~~~~~~~~ + +Inside the local directory, you can build the go binary: + +.. code:: bash + + go build + +Mounting +~~~~~~~~ + +Then, you can mount the filesystem with the local binary. + +May require a privileged user (sudo). + +The basic usage is: + +.. code:: bash + + ./stats_fs + +**Options:** - debug (default is false) - socket + (default is /run/vpp/stats.sock) : VPP socket for stats + +Unmounting the file system +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can unmount the filesystem with the fusermount command. + +May require a privileged user (sudo) + +.. code:: bash + + fusermount -u /path/to/mountpoint + +To force the unmount even if the resource is busy, add the -z option: + +.. code:: bash + + fusermount -uz /path/to/mountpoint -- cgit 1.2.3-korg