Skip to content

Commit c736147

Browse files
karimrakarimra
authored
Merge pull request #3 from karimra/docs
add initial docs
2 parents c41d3f6 + 838fa6d commit c736147

File tree

12 files changed

+360
-9
lines changed

12 files changed

+360
-9
lines changed

‎README.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,15 @@
11
`gribi` is a gRIBI CLI client that provides full support for gRIBI RPCs.
2+
It is intended to be used for educational and testing purposes.
3+
4+
## Features
5+
6+
* **Full Support for Get And Flush RPCs**
7+
8+
* **Modify RPC is supported with IPv4, IPv6, Next Hop Group and Next Hop AFTs**
9+
10+
* **Template based modify RPC operations configuration**
11+
12+
* **Concurrent multi target RPC execution**
213

314
Documentation available at [https://gribic.kmrd.dev](https://gribic.kmrd.dev)
415

‎app/flush.go‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ package app
22

33
import (
44
"context"
5+
"errors"
56
"fmt"
67

78
"github.com/karimra/gribic/api"
@@ -37,7 +38,9 @@ func (a *App) FlushPreRunE(cmd *cobra.Command, args []string) error {
3738
if err != nil {
3839
return err
3940
}
40-
// TODO: validate flags
41+
if !a.Config.FlushNetworkInstanceAll && a.Config.FlushNetworkInstance == "" {
42+
return errors.New("set a specific network-instance name to flush using --ns or flush all network-instances with --ns-all")
43+
}
4144
return nil
4245
}
4346

‎app/get.go‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -20,8 +20,7 @@ type getResponse struct {
2020
func (a *App) InitGetFlags(cmd *cobra.Command) {
2121
cmd.ResetFlags()
2222
//
23-
cmd.Flags().StringVarP(&a.Config.GetNetworkInstance, "ns", "", "", "network instance name")
24-
cmd.Flags().BoolVarP(&a.Config.GetNetworkInstanceAll, "ns-all", "", false, "run Get against all network instance(s)")
23+
cmd.Flags().StringVarP(&a.Config.GetNetworkInstance, "ns", "", "", "network instance name, an empty network-instance name means query all instances.")
2524
cmd.Flags().StringVarP(&a.Config.GetAFT, "aft", "", "ALL", "AFT type, one of: ALL, IPv4, IPv6, NH, NHG, MPLS, MAC or PF")
2625

2726
//
@@ -97,7 +96,7 @@ func (a *App) GetRunE(cmd *cobra.Command, args []string) error {
9796
func (a *App) gribiGet(ctx context.Context, t *target) (*spb.GetResponse, error) {
9897
opts := make([]api.GRIBIOption, 0, 2)
9998
opts = append(opts, api.AFTType(a.Config.GetAFT))
100-
if a.Config.GetNetworkInstanceAll {
99+
if a.Config.GetNetworkInstance == "" {
101100
opts = append(opts, api.NSAll())
102101
} else {
103102
opts = append(opts, api.NetworkInstance(a.Config.GetNetworkInstance))

‎config/config.go‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -60,10 +60,8 @@ type LocalFlags struct {
6060
// version
6161
UpgradeUsePkg bool
6262
// Get
63-
GetNetworkInstance string
64-
GetAFT string
65-
GetNetworkInstanceAll bool
66-
63+
GetNetworkInstance string
64+
GetAFT string
6765
// flush
6866
FlushNetworkInstance string
6967
FlushNetworkInstanceAll bool

‎docs/cmd/flush.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
### Description
2+
3+
The Flush Command runs a [gRIBI Flush RPC](https://github.com/openconfig/gribi/blob/master/v1/proto/service/gribi.proto#L47) as a client, sending a [FlushRequest](https://github.com/openconfig/gribi/blob/master/v1/proto/service/gribi.proto#L469) to a gRIBI server.
4+
The Server returns a single [FlushResponse](https://github.com/openconfig/gribi/blob/master/v1/proto/service/gribi.proto#L518).
5+
6+
### Usage
7+
8+
`gribic [global-flags] flush [local-flags]`
9+
10+
Alias: `f`
11+
12+
### Flags
13+
14+
#### ns
15+
16+
The `--ns` flag sets the network instance name the client wants to flush.
17+
18+
#### ns-all
19+
20+
The `--ns-all` flag indicates to the server that the client wants to flush all instances.
21+
22+
#### override
23+
24+
The `--override` flag indicates to the server that the client wants the server to not compare the election ID with already known `single-primary` clients.
25+
26+
### Examples
27+
28+
Flush all AFTs in network instance `default`
29+
30+
```bash
31+
gribic -a router1 -u admin -p admin --skip-verify flush --ns default
32+
```
33+
34+
Flush all AFTs in all network instances
35+
36+
```bash
37+
gribic -a router1 -u admin -p admin --skip-verify flush --ns-all
38+
```

‎docs/cmd/get.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
### Description
2+
3+
The Get Command runs a [gRIBI Get RPC](https://github.com/openconfig/gribi/blob/master/v1/proto/service/gribi.proto#L42) as a client, sending a [GetRequest](https://github.com/openconfig/gribi/blob/master/v1/proto/service/gribi.proto#L422) to a gRIBI server.
4+
The Server returns a stream of [GetResponse(s)](https://github.com/openconfig/gribi/blob/master/v1/proto/service/gribi.proto#L462) with the installed [AFTs](https://github.com/openconfig/gribi/blob/master/v1/proto/service/gribi.proto#L444).
5+
6+
The client can specify the type of AFTs as well as the network instance it is interested on. Or simply request ALL AFT types from ALL network instances.
7+
8+
### Usage
9+
10+
`gribic [global-flags] get [local-flags]`
11+
12+
Alias: `g`
13+
14+
### Flags
15+
16+
#### ns
17+
18+
The `--ns` flag sets the network instance name the client is interested on.
19+
20+
#### aft
21+
22+
The `--aft` flag sets the AFT type the client is interested on. It defaults to `ALL` which means all AFT types.
23+
24+
Accepted values:
25+
26+
- `all`
27+
- `nexthop` (or `nh`)
28+
- `nexthop-group` (or `nhg`)
29+
- `ipv4`
30+
- `ipv6`
31+
- `mac`
32+
- `mpls`
33+
- `policy-forwarding` (or `pf`)
34+
35+
### Examples
36+
37+
Query all AFTs in network instance `default`
38+
39+
```bash
40+
gribic -a router1 -u admin -p admin --skip-verify get --ns default
41+
```
42+
43+
Query all AFTs in all network instances
44+
45+
```bash
46+
gribic -a router1 -u admin -p admin --skip-verify get --ns-all
47+
```
48+
49+
Query AFT type `ipv4` in network instance `default`
50+
51+
```bash
52+
gribic -a router1 -u admin -p admin --skip-verify get --ns default --aft ipv4
53+
```
54+
55+
Query AFT type `nhg` (next hop group) in all network instances
56+
57+
```bash
58+
gribic -a router1 -u admin -p admin --skip-verify get --ns-all --aft nhg
59+
```

‎docs/cmd/modify.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
### Description
2+
3+
The Modify Command runs a [gRIBI Modify RPC](https://github.com/openconfig/gribi/blob/master/v1/proto/service/gribi.proto#L31) as a client, sending a stream of [ModifyRequest(s)](https://github.com/openconfig/gribi/blob/master/v1/proto/service/gribi.proto#L52) to a gRIBI server.
4+
The Server returns a stream of [ModifyResponse(s)](https://github.com/openconfig/gribi/blob/master/v1/proto/service/gribi.proto#L213).
5+
6+
The ModifyRequest is used to set the current session parameters (redundancy, persistence, and ack mode) as well as issuing AFT operation to the server.
7+
8+
The AFT operation can be an ADD, REPLACE or DELETE and references a single AFT entry of type IPV4, IPv6, Next Hop, Next Hop Group, MPLS, MAC or Policy Forwarding.
9+
10+
A single modifyRequest can carry multiple AFT operations.
11+
12+
A Modify RPC start with the client sending a ModifyRequest indicating the [session parameters](https://github.com/openconfig/gribi/blob/master/v1/proto/service/gribi.proto#L342) it wants to apply to the current session, the parameters are:
13+
14+
- Redundancy: specifies the client redundancy mode, either `ALL_PRIMARY` or `SINGLE_PRIMARY`
15+
- `ALL_PRIMARY`: is the default and indicates that the server should accept AFT operations from all clients.
16+
17+
When it comes to ADD operations, the server should add an entry when it first receives it from any client.
18+
While it should wait for the last delete to remove it from its RIB.
19+
20+
In other words, the server should keep track of the number of clients it received a specific entry from.
21+
22+
- `SINGLE_PRIMARY`: implies that the clients went through an election process and a single one came out as primary, it has the highest election ID which it sends to the server in the initial ModifyRequest as well as with each AFT Operation.
23+
24+
The server accepts AFT Operations only from the client with the highest election ID.
25+
26+
- Persistence: Specifies desired server behavior when the client disconnects.
27+
- `DELETE`: is the default, it means that all AFTs received from the client shall be deleted when it disconnects.
28+
- `PRESERVE`: the server should keep the RIB and FIB entries set by the client when it disconnects.
29+
30+
- Ack Mode: Specifies the Ack type expected by the client
31+
- `RIB_ACK`: the server must respond with `RIB_PROGRAMMED`
32+
- `RIB_AND_FIB_ACK`: the server must respond with `RIB_PROGRAMMED`, if the AFT entry is also programmed in the NE FIB, the server must response with `FIB_PROGRAMMED` instead.
33+
34+
### Usage
35+
36+
`gribic [global-flags] modify [local-flags]`
37+
38+
Alias: `mod`, `m`
39+
40+
### Flags
41+
42+
#### single-primary
43+
44+
The `--single-primary` flag set the session parameters redundancy to `SINGLE_PRIMARY`
45+
46+
#### preserve
47+
48+
The `--preserve` flag set the session parameters persistence to `PRESERVE`
49+
50+
#### fib
51+
52+
The `--fib` flag set the session parameters Ack mode to `RIB_AND_FIB_ACK`
53+
54+
#### input-file
55+
56+
The `--input-file` flag points to a modify input file
57+
58+
See [here](https://github.com/karimra/gribic/examples) for some input file examples
59+
60+
### Examples
61+
62+
Run all operations defined in the input-file in `single-primary` redundancy mode, with persistence `preserve` and ack mode `RIB_FIB`
63+
64+
```bash
65+
gribic -a router1 -u admin -p admin --skip-verify modify \
66+
--single-primary \
67+
--preserve \
68+
--fib \
69+
--election-id 1:2 \
70+
--input-file <path/to/modify/operations>
71+
```

‎docs/index.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,75 @@
11
# Welcome to gRIBIc
22

3+
`gRIBIc` is a gRIBI CLI client that implements the Openconfig gRIBI RPCs.
4+
It is intended to be used for educational and testing purposes.
5+
6+
## Features
7+
8+
* **Full Support for Get And Flush RPCs**
9+
10+
* **Modify RPC is supported with IPv4, IPv6, Next Hop Group and Next Hop AFTs**
11+
12+
* **Template based modify RPC operations configuration**
13+
14+
* **Concurrent multi target RPC execution**
15+
16+
## Quick start guide
17+
18+
### Installation
19+
20+
```
21+
bash -c "$(curl -sL https://get-gribic.kmrd.dev)"
22+
```
23+
24+
### Get Request
25+
26+
Query all AFTs in all network instances
27+
28+
```bash
29+
gribic -a router1 -u admin -p admin --skip-verify get
30+
```
31+
32+
Query all AFTs in network instance `default`
33+
34+
```bash
35+
gribic -a router1 -u admin -p admin --skip-verify get --ns default
36+
```
37+
38+
Query AFT type `ipv4` in network instance `default`
39+
40+
```bash
41+
gribic -a router1 -u admin -p admin --skip-verify get --ns default --aft ipv4
42+
```
43+
44+
Query AFT type `nhg` (next hop group) in all network instances
45+
46+
```bash
47+
gribic -a router1 -u admin -p admin --skip-verify get --aft nhg
48+
```
49+
50+
### Flush Request
51+
52+
Flush all AFTs in network instance `default`
53+
54+
```bash
55+
gribic -a router1 -u admin -p admin --skip-verify flush --ns default
56+
```
57+
58+
Flush all AFTs in all network instances
59+
60+
```bash
61+
gribic -a router1 -u admin -p admin --skip-verify flush --ns-all
62+
```
63+
64+
### Modify Request
65+
66+
Run all operations defined in the input-file in `single-primary` redundancy mode, with persistence `preserve` and ack mode `RIB_FIB`
67+
68+
```bash
69+
gribic -a router1 -u admin -p admin --skip-verify modify \
70+
--single-primary \
71+
--preserve \
72+
--fib \
73+
--election-id 1:2 \
74+
--input-file <path/to/modify/operations>
75+
```

0 commit comments

Comments
 (0)