From 35c6fa29d5d74fb650f2f5f965e0e09c65e54c98 Mon Sep 17 00:00:00 2001 From: Ondrej Fabry Date: Thu, 13 Jul 2023 15:35:38 +0200 Subject: [PATCH] Update README.md (#139) * Update README.md Signed-off-by: Ondrej Fabry * Update README.md Signed-off-by: Ondrej Fabry * Update TROUBLESHOOTING.md Signed-off-by: Ondrej Fabry --------- Signed-off-by: Ondrej Fabry --- README.md | 44 ++++++----- docs/TROUBLESHOOTING.md | 166 ++++++++++++++++++---------------------- 2 files changed, 99 insertions(+), 111 deletions(-) diff --git a/README.md b/README.md index f20c66a2..d2a0dc2f 100644 --- a/README.md +++ b/README.md @@ -11,22 +11,25 @@ The GoVPP repository contains Go client libraries, code bindings generator and other toolings for VPP. -Here is a brief summary of features provided by GoVPP: +--- -* Generator of Go bindings for VPP API -* Go client library for VPP binary API & Stats API -* Extendable code generator supporting custom plugins -* Pure Go implementation of VPP binary API protocol -* Efficient reader of VPP Stats data from shared memory -* Simple client API that does not rely on VPP API semantics -* Generated RPC client code that handles all boilerplate -* ..and much more! +## Features ---- +* 🆕 CLI app for interacting with VPP instance and development of VPP API (see [GoVPP CLI](https://github.com/FDio/govpp/blob/master/docs/GOVPP_CLI.md)) +* 🆕 Extendable code generator supporting custom plugins (see [Enhanced Generator](https://github.com/FDio/govpp/discussions/94)) +* 🆕 Generated RPC client code that handles all boilerplate (see [RPC Services](https://github.com/FDio/govpp/discussions/58)) +* Simple VPP client API that is not dependent on any VPP API semantics (see [Stream API](https://github.com/FDio/govpp/discussions/43)) +* Generator of Go bindings for VPP API schema (see [Binapi Generator](https://github.com/FDio/govpp/blob/master/docs/USER_GUIDE.md#binary-api-generator)) +* Go client library for VPP binary API & Stats API (see [VPP API calls](https://github.com/FDio/govpp/blob/master/docs/USER_GUIDE.md#vpp-api-calls)) +* Pure Go implementation of VPP binary API protocol (see [socketclient](https://github.com/FDio/govpp/blob/master/adapter/socketclient/socketclient.go)) +* Efficient reader of VPP Stats data from shared memory (see [stats client example](https://github.com/FDio/govpp/tree/master/examples/stats-client)) ## Quick Start -Here is a code sample of an effortless way for calling the VPP API by using a generated RPC client. +Here is a code sample of an effortless way for calling the VPP API services by using a generated RPC client. + +> **Note** +> For extensive info about using generated RPC client , see [RPC Services](https://github.com/FDio/govpp/discussions/58) ```go // Connect to VPP API socket @@ -47,23 +50,28 @@ if err != nil { log.Print("Version: ", reply.Version) ``` -See complete example in [examples/rpc-service](examples/rpc-service). +See complete code for the example above: [examples/rpc-service](examples/rpc-service). ### Examples -For all code examples demonstrating GoVPP features, please refer to the [examples](examples) directory. +For complete code examples demonstrating vrious GoVPP features, please refer to the [examples](examples) directory. ## Documentation -Refer to [User Guide](docs/USER_GUIDE.md) document for all the basics. If you run into issues or just need help debugging read our [Troubleshooting](docs/TROUBLESHOOTING.md) document. +Refer to [User Guide](docs/USER_GUIDE.md) document for info about how to use GoVPP. +If you run into any issues or need some help with debugging GoVPP, read our [Troubleshooting](docs/TROUBLESHOOTING.md) document. -Go reference is available at https://pkg.go.dev/go.fd.io/govpp. More documentation can be found under [docs](docs) directory. +Go reference docs are available at [pkg.go.dev](https://pkg.go.dev/go.fd.io/govpp). + +For other documentation refer to [docs](docs) directory. ## How to contribute? -- Contribute code by submitting a [Pull Request](https://github.com/FDio/govpp/pulls). -- Report bugs by opening an [Issue](https://github.com/FDio/govpp/issues). -- Ask questions & open discussions by starting a [Discussion](https://github.com/FDio/govpp/discussions). +Anyone insterested in GoVPP development is welcome to join our bi-weekly [📣 GoVPP Community Meeting](https://github.com/FDio/govpp/discussions/46), where we accept inputs from projects using GoVPP and have technical discussions about actual development. + +- **Contribute code**: submit a [Pull Request](https://github.com/FDio/govpp/pulls) +- **Report bugs**: open an [Issue](https://github.com/FDio/govpp/issues) +- **Ask questions**: start a [Discussion](https://github.com/FDio/govpp/discussions) ## Repository Structure diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index 2c01c998..fadf1262 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -1,16 +1,20 @@ -# Troubleshooting guide - -## Table of contents - -* [Enable debug logs](#enable-debug-logs) - + [core](#core) - + [msgid](#msgid) - + [socketclient](#socketclient) - + [msgtable](#msgtable) - + [statsclient](#statsclient) - + [proxy](#proxy) - + [Binapi generator debug logs](#binapi-generator-debug-logs) -* [Connection problems](#connection-problems) +# Troubleshooting Guide + +This document provides guidance for troubleshooting issues or any debugging for GoVPP. + +--- + +**Table of contents** + +* [Debug Logging](#debug-logging) + + [Enable Debug](#enable-debug) + + [Debug Components](#debug-components) + - [Debug Message IDs](#debug-message-ids) + - [Debug Socket Client](#debug-socket-client) + - [Debug Binapi Generator](#debug-binapi-generator) + - [Debug Stats Client](#debug-stats-client) + - [Debug Proxy](#debug-proxy) +* [Connection Problems](#connection-problems) + [Socket file does not exist](#socket-file-does-not-exist) + [Connection refused](#connection-refused) + [Permission denied](#permission-denied) @@ -18,88 +22,85 @@ * [Problems with sending/receiving messages](#problems-with-sendingreceiving-messages) + [Unknown message error](#unknown-message-error) + [VPP not replying to some messages](#vpp-not-replying-to-some-messages) -* [Message versioning, deprecated and in-progesss messages](#message-versioning-deprecated-and-in-progesss-messages) - + [Message versioning](#message-versioning) +* [Message versioning](#message-versioning) + [Deprecated messages](#deprecated-messages) + [In-progress messages](#in-progress-messages) --- -## Enable debug logs +## Debug Logging -This section describes how to increase log verbosity to enable debug logs of various GoVPP components. +This section describes ways to enable debug logs for GoVPP and its components. +Most of the debug logs is controlled via the environment variable `DEBUG_GOVPP`. -### core +### Enable Debug -Set the environment variable `DEBUG_GOVPP` to any non-empty value. +To enable debug logs for GoVPP core, set the environment variable `DEBUG_GOVPP` to a **non-empty value**. -Example: -``` -DEBUG_GOVPP=y ./bin/rpc-service +```sh +DEBUG_GOVPP=y ./app ``` -To verify that it works, check for the following line in the console output: +The following line will be printed to _stderr_ output during program initialization: + ``` DEBU[0000] govpp: debug level enabled ``` -### msgid +### Debug Components -Assign value `msgid` to the variable `DEBUG_GOVPP`. +The environment variable `DEBUG_GOVPP` can be used also to enable debug logs for other GoVPP components separately. -NOTE: To make msgid debugging work, you must also enable core debugging (in this case, it is enabled automatically, because `msgid` is a non-emtpy value). +> **Note** +> Multiple components can be enabled silmutaneously, by separating values with comma, e.g. `DEBUG_GOVPP=socketclient,msgtable` -Example: -``` -DEBUG_GOVPP=msgid ./bin/rpc-service -``` +#### Debug Message IDs -It should output lines similar to this: +To enable debugging of message IDs, set `DEBUG_GOVPP=msgid`. + +*log output sample:* ``` DEBU[0000] message "show_version" (show_version_51077d14) has ID: 1380 ``` -### socketclient +#### Debug Socket Client -Assign value `socketclient` to the variable `DEBUG_GOVPP`. +To debug `socketclient` package, set `DEBUG_GOVPP=socketclient`. -Example: +*log output sample:* ``` -DEBUG_GOVPP=socketclient ./bin/rpc-service +DEBU[0000] govpp: debug level enabled for socketclient ``` -To verify that it works, check for the following line in the console output: +Additionally, to debug the message table retrieved upon connecting to socket, set `DEBUG_GOVPP=socketclient,msgtable`. + +*log output sample:* ``` -DEBU[0000] govpp: debug level enabled for socketclient +DEBU[0000] - 1380: "show_version_51077d14" logger=govpp/socketclient ``` -### msgtable +#### Debug Binapi Generator -Assign value `msgtable` to the variable `DEBUG_GOVPP`. +To enable the basic debug logs in the binapi generator, pass the flag `-debug` to the program. -NOTE: To make msgtable debugging work, you must also enable socketclient debugging. +Additionaly, to enable debug logs for the _parser_, assign value `DEBUG_GOVPP=parser` and +to enable debug logs for the _generator_, set `DEBUG_GOVPP=binapigen`. -NOTE: To assign multiple values to a variable, you can separate the values with a colon. +Examples: +```bash +# Enable debug logs +./bin/binapi-generator -debug -Example: -``` -DEBUG_GOVPP=socketclient:msgtable ./bin/rpc-service +# Maximum verbosity +DEBUG_GOVPP=parser,binapigen ./binapi-generator ``` -It should output lines similar to this: -``` -DEBU[0000] - 1380: "show_version_51077d14" logger=govpp/socketclient -``` - -### statsclient - -Set the environment variable `DEBUG_GOVPP_STATS` to any non-empty value. +#### Debug Stats Client -NOTE: statsclient debugging only works if package `go.fd.io/govpp/adapter/statsclient` is imported. +To enable debug logs for `statsclient` package, set `DEBUG_GOVPP_STATS` to a non-empty value. -Example: -``` -DEBUG_GOVPP_STATS=y ./bin/vpp-proxy server +```sh +DEBUG_GOVPP_STATS=y ./stats-client ``` To verify that it works, check for the following line in the console output: @@ -107,49 +108,28 @@ To verify that it works, check for the following line in the console output: DEBU[0000] govpp/statsclient: enabled debug mode ``` -### proxy - -Set the environment variable `DEBUG_GOVPP_PROXY` to any non-empty value. +#### Debug Proxy -NOTE: proxy debugging only works if package `go.fd.io/govpp/proxy` is imported. +To enable debug logs for `proxy` package, set `DEBUG_GOVPP_PROXY` to a non-empty value. -Example: -``` -DEBUG_GOVPP_PROXY=y ./bin/vpp-proxy server +```sh +DEBUG_GOVPP_PROXY=y ./vpp-proxy server ``` To verify that it works, check for the following line in the console output: + ``` DEBU[0000] govpp/proxy: debug mode enabled ``` -### Binapi generator debug logs - -You can enable logs separately for vppapi parser and for binapi generator. The binapi generator has two verbosity levels. - -To enable parser logs, assign value `parser` to the variable `DEBUG_GOVPP`. - -To enable the first verbosity level for generator, pass the flag `-debug` when invoking the generator binary. - -To enable the second verbosity level for generator, assign value `binapigen` to the variable `DEBUG_GOVPP`. - -Examples: -```bash -# first verbosity level for generator -./bin/binapi-generator -debug -# maximum logs for all components -DEBUG_GOVPP=parser:binapigen ./bin/binapi-generator -``` - - - -## Connection problems +## Connection Problems This section describes various problems when GoVPP tries to connect to VPP. ### Socket file does not exist **Symptoms**: You see the following error: + ``` ERROR: connecting to VPP failed: VPP API socket file /run/vpp/api.sock does not exist ``` @@ -189,6 +169,7 @@ ERROR: connecting to VPP failed: VPP API socket file /run/vpp/api.sock does not ### Connection refused **Symptoms**: You see the following error: + ``` ERROR: connecting to VPP failed: dial unix /run/vpp/api.sock: connect: connection refused ``` @@ -200,6 +181,7 @@ ERROR: connecting to VPP failed: dial unix /run/vpp/api.sock: connect: connectio ### Permission denied **Symptoms**: You see the following error: + ``` ERROR: connecting to VPP failed: dial unix /run/vpp/api.sock: connect: permission denied ``` @@ -217,7 +199,6 @@ ERROR: connecting to VPP failed: dial unix /run/vpp/api.sock: connect: permissio (replace the `` with actual group ID; you can see the ID with `id -g`). - If you are running VPP inside Docker container, run the container as current user's group (but keep the user as root), for example `docker run -it -v /run/vpp:/run/vpp -u 0:$(id -g) ligato/vpp-base:22.10`. In this case, do NOT use the `unix { gid ... }` in `startup.conf`. - - Run GoVPP with `sudo`. - Manually change permissions or ownership of the socket file. @@ -231,9 +212,8 @@ ERROR: connecting to VPP failed: dial unix /run/vpp/api.sock: connect: permissio - Increase the interval between reconnects (the third argument, `interval`, of the `govpp.AsyncConnect` function). - Increase the timeout for waiting for the socket existence (variable `MaxWaitReady` in the file `adapter/socketclient/socketclient.go`). -**NOTE**: The solutions apply only if you use the function `govpp.AsyncConnect`. If you instead use the function `govpp.Connect`, then GoVPP tries to connect immediately and only once, and if the socket does not exist, it immediately throws error. In this case, you have to ensure that the socket is ready before starting GoVPP. - - +> **Note** +> The solutions apply only if you use the function `govpp.AsyncConnect`. If you instead use the function `govpp.Connect`, then GoVPP tries to connect immediately and only once, and if the socket does not exist, it immediately throws error. In this case, you have to ensure that the socket is ready before starting GoVPP. ## Problems with sending/receiving messages @@ -257,11 +237,7 @@ To solve it, you can try the following: - Check if the VPP is frozen or crashed. - Try sending the message with different values. - - -## Message versioning, deprecated and in-progesss messages - -### Message versioning +## Message versioning When a GoVPP's message is updated, the message itself is not changed. Instead, a new version of the message is added that has a `v2` (or `v3`, `v4`, ...) suffix to its name. The old version of the message is then marked as deprecated. @@ -270,6 +246,7 @@ When a GoVPP's message is updated, the message itself is not changed. Instead, a If a message is marked as deprecated, it should no longer be used. The message works fine for now, but it may be removed in the future. When a message is deprecated, there is likely available a new version of the message or an another message with a similar behaviour which should be used instead. Also, if some message is not deprecated, but there already exists a new version of the message, the new version should be used, as the older version may soon become deprecated. For example, here is an excerpt from the file `binapi/vhost_user/vhost_user.ba.go` (as of 31-Oct-2022): + ```go // CreateVhostUserIf defines message 'create_vhost_user_if'. // Deprecated: the message will be removed in the future versions @@ -299,6 +276,7 @@ type CreateVhostUserIfV2Reply struct { // ... } ``` + The messages `CreateVhostUserIf` and `CreateVhostUserIfReply` are deprecated and should not be used. Instead, there are new versions of the messages: `CreateVhostUserIfV2` and `CreateVhostUserIfV2Reply`, which should be used. ### In-progress messages @@ -306,6 +284,7 @@ The messages `CreateVhostUserIf` and `CreateVhostUserIfReply` are deprecated and When a new message is added, usually it is initially experimental and is marked as in-progress. In this case, an older message should be preferrably used. Later, when the message will be considered stable, the in-progress label will be removed, the message will become recommended to use and the old message may become deprecated. For example, here is an excerpt from the file `binapi/ip/ip.ba.go` (as of 31-Oct-2022): + ```go // IPRouteAddDel defines message 'ip_route_add_del'. type IPRouteAddDel struct { @@ -335,4 +314,5 @@ type IPRouteAddDelV2Reply struct { // ... } ``` + In this case, the messages `IPRouteAddDel` and `IPRouteAddDelReply` should be used; the messages `IPRouteAddDelV2` and `IPRouteAddDelV2Reply` are in-progress.