You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* Pure Go implementation of VPP binary API protocol
20
-
* Efficient reader of VPP Stats data from shared memory
21
-
* Simple client API that does not rely on VPP API semantics
22
-
* Generated RPC client code that handles all boilerplate
23
-
* ..and much more!
16
+
## Features
24
17
25
-
---
18
+
* 🆕 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))
* 🆕 Generated RPC client code that handles all boilerplate (see [RPC Services](https://github.com/FDio/govpp/discussions/58))
21
+
* Simple VPP client API that is not dependent on any VPP API semantics (see [Stream API](https://github.com/FDio/govpp/discussions/43))
22
+
* 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))
23
+
* 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))
24
+
* Pure Go implementation of VPP binary API protocol (see [socketclient](https://github.com/FDio/govpp/blob/master/adapter/socketclient/socketclient.go))
25
+
* Efficient reader of VPP Stats data from shared memory (see [stats client example](https://github.com/FDio/govpp/tree/master/examples/stats-client))
26
26
27
27
## Quick Start
28
28
29
-
Here is a code sample of an effortless way for calling the VPP API by using a generated RPC client.
29
+
Here is a code sample of an effortless way for calling the VPP API services by using a generated RPC client.
30
+
31
+
> **Note**
32
+
> For extensive info about using generated RPC client , see [RPC Services](https://github.com/FDio/govpp/discussions/58)
30
33
31
34
```go
32
35
// Connect to VPP API socket
@@ -47,23 +50,28 @@ if err != nil {
47
50
log.Print("Version: ", reply.Version)
48
51
```
49
52
50
-
See complete example in[examples/rpc-service](examples/rpc-service).
53
+
See complete code for the example above:[examples/rpc-service](examples/rpc-service).
51
54
52
55
### Examples
53
56
54
-
For all code examples demonstrating GoVPP features, please refer to the [examples](examples) directory.
57
+
For complete code examples demonstrating vrious GoVPP features, please refer to the [examples](examples) directory.
55
58
56
59
## Documentation
57
60
58
-
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.
61
+
Refer to [User Guide](docs/USER_GUIDE.md) document for info about how to use GoVPP.
62
+
If you run into any issues or need some help with debugging GoVPP, read our [Troubleshooting](docs/TROUBLESHOOTING.md) document.
59
63
60
-
Go reference is available at https://pkg.go.dev/go.fd.io/govpp. More documentation can be found under [docs](docs) directory.
64
+
Go reference docs are available at [pkg.go.dev](https://pkg.go.dev/go.fd.io/govpp).
65
+
66
+
For other documentation refer to [docs](docs) directory.
61
67
62
68
## How to contribute?
63
69
64
-
- Contribute code by submitting a [Pull Request](https://github.com/FDio/govpp/pulls).
65
-
- Report bugs by opening an [Issue](https://github.com/FDio/govpp/issues).
66
-
- Ask questions & open discussions by starting a [Discussion](https://github.com/FDio/govpp/discussions).
70
+
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.
71
+
72
+
-**Contribute code**: submit a [Pull Request](https://github.com/FDio/govpp/pulls)
73
+
-**Report bugs**: open an [Issue](https://github.com/FDio/govpp/issues)
74
+
-**Ask questions**: start a [Discussion](https://github.com/FDio/govpp/discussions)
+[Socket file does not exist](#socket-file-does-not-exist)
15
19
+[Connection refused](#connection-refused)
16
20
+[Permission denied](#permission-denied)
17
21
+[The socket is not ready](#the-socket-is-not-ready)
18
22
*[Problems with sending/receiving messages](#problems-with-sendingreceiving-messages)
19
23
+[Unknown message error](#unknown-message-error)
20
24
+[VPP not replying to some messages](#vpp-not-replying-to-some-messages)
21
-
*[Message versioning, deprecated and in-progesss messages](#message-versioning-deprecated-and-in-progesss-messages)
22
-
+[Message versioning](#message-versioning)
25
+
*[Message versioning](#message-versioning)
23
26
+[Deprecated messages](#deprecated-messages)
24
27
+[In-progress messages](#in-progress-messages)
25
28
26
29
---
27
30
28
-
## Enable debug logs
31
+
## Debug Logging
29
32
30
-
This section describes how to increase log verbosity to enable debug logs of various GoVPP components.
33
+
This section describes ways to enable debug logs for GoVPP and its components.
34
+
Most of the debug logs is controlled via the environment variable `DEBUG_GOVPP`.
31
35
32
-
### core
36
+
### Enable Debug
33
37
34
-
Set the environment variable `DEBUG_GOVPP` to any non-empty value.
38
+
To enable debug logs for GoVPP core, set the environment variable `DEBUG_GOVPP` to a **non-empty value**.
35
39
36
-
Example:
37
-
```
38
-
DEBUG_GOVPP=y ./bin/rpc-service
40
+
```sh
41
+
DEBUG_GOVPP=y ./app
39
42
```
40
43
41
-
To verify that it works, check for the following line in the console output:
44
+
The following line will be printed to _stderr_ output during program initialization:
45
+
42
46
```
43
47
DEBU[0000] govpp: debug level enabled
44
48
```
45
49
46
-
### msgid
50
+
### Debug Components
47
51
48
-
Assign value `msgid`to the variable `DEBUG_GOVPP`.
52
+
The environment variable `DEBUG_GOVPP` can be used also to enable debug logs for other GoVPP components separately.
49
53
50
-
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).
54
+
> **Note**
55
+
> Multiple components can be enabled silmutaneously, by separating values with comma, e.g. `DEBUG_GOVPP=socketclient,msgtable`
51
56
52
-
Example:
53
-
```
54
-
DEBUG_GOVPP=msgid ./bin/rpc-service
55
-
```
57
+
#### Debug Message IDs
56
58
57
-
It should output lines similar to this:
59
+
To enable debugging of message IDs, set `DEBUG_GOVPP=msgid`.
60
+
61
+
*log output sample:*
58
62
```
59
63
DEBU[0000] message "show_version" (show_version_51077d14) has ID: 1380
60
64
```
61
65
62
-
###socketclient
66
+
#### Debug Socket Client
63
67
64
-
Assign value`socketclient`to the variable `DEBUG_GOVPP`.
68
+
To debug`socketclient`package, set `DEBUG_GOVPP=socketclient`.
65
69
66
-
Example:
70
+
*log output sample:*
67
71
```
68
-
DEBUG_GOVPP=socketclient ./bin/rpc-service
72
+
DEBU[0000] govpp: debug level enabled for socketclient
69
73
```
70
74
71
-
To verify that it works, check for the following line in the console output:
75
+
Additionally, to debug the message table retrieved upon connecting to socket, set `DEBUG_GOVPP=socketclient,msgtable`.
76
+
77
+
*log output sample:*
72
78
```
73
-
DEBU[0000] govpp: debug level enabled for socketclient
(replace the `<ID>` with actual group ID; you can see the ID with `id -g`).
218
200
219
201
- 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`.
220
-
221
202
- Run GoVPP with `sudo`.
222
203
223
204
- Manually change permissions or ownership of the socket file.
- Increase the interval between reconnects (the third argument, `interval`, of the `govpp.AsyncConnect` function).
232
213
- Increase the timeout for waiting for the socket existence (variable `MaxWaitReady` in the file `adapter/socketclient/socketclient.go`).
233
214
234
-
**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.
235
-
236
-
215
+
> **Note**
216
+
> 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.
237
217
238
218
## Problems with sending/receiving messages
239
219
@@ -257,11 +237,7 @@ To solve it, you can try the following:
257
237
- Check if the VPP is frozen or crashed.
258
238
- Try sending the message with different values.
259
239
260
-
261
-
262
-
## Message versioning, deprecated and in-progesss messages
263
-
264
-
### Message versioning
240
+
## Message versioning
265
241
266
242
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.
267
243
@@ -270,6 +246,7 @@ When a GoVPP's message is updated, the message itself is not changed. Instead, a
270
246
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.
271
247
272
248
For example, here is an excerpt from the file `binapi/vhost_user/vhost_user.ba.go` (as of 31-Oct-2022):
// Deprecated: the message will be removed in the future versions
@@ -299,13 +276,15 @@ type CreateVhostUserIfV2Reply struct {
299
276
// ...
300
277
}
301
278
```
279
+
302
280
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.
303
281
304
282
### In-progress messages
305
283
306
284
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.
307
285
308
286
For example, here is an excerpt from the file `binapi/ip/ip.ba.go` (as of 31-Oct-2022):
@@ -335,4 +314,5 @@ type IPRouteAddDelV2Reply struct {
335
314
// ...
336
315
}
337
316
```
317
+
338
318
In this case, the messages `IPRouteAddDel` and `IPRouteAddDelReply` should be used; the messages `IPRouteAddDelV2` and `IPRouteAddDelV2Reply` are in-progress.
0 commit comments