Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update README.md #139

Merged
merged 4 commits into from
Jul 13, 2023
Merged

Update README.md #139

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ed213c5
Update README.md
ondrej-fabry Jun 26, 2023
cea4bfc
Update README.md
ondrej-fabry Jun 26, 2023
1184139
Update TROUBLESHOOTING.md
ondrej-fabry Jul 3, 2023
5feaa87
Merge branch 'master' into readme
ondrej-fabry Jul 11, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 26 additions & 18 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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

Expand Down
166 changes: 73 additions & 93 deletions docs/TROUBLESHOOTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,155 +1,135 @@
# 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)
+ [The socket is not ready](#the-socket-is-not-ready)
* [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:
```
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
```
Expand Down Expand Up @@ -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
```
Expand All @@ -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
```
Expand All @@ -217,7 +199,6 @@ ERROR: connecting to VPP failed: dial unix /run/vpp/api.sock: connect: permissio
(replace the `<ID>` 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.
Expand All @@ -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

Expand All @@ -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.

Expand All @@ -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
Expand Down Expand Up @@ -299,13 +276,15 @@ 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

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 {
Expand Down Expand Up @@ -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.