eBPF Program Catalog¶

Contains the available eBPF programs to be installed in the Execution Environment.

Schema¶

Field	Type	Required	Readonly	Auto Managed	Example
`id`	String	True	True	False	packet-counter
`config`	Config	True	False	False
`parameters`	List(Parameter)	False	False	False
`description`	String	False	False	False	Transparent service to capture packets flowing through the interface it is attached to, apply filters and obtain capture in .pcap format.

Config Schema¶

Field	Type	Required	Readonly	Auto Managed	Example
`code`	String	True	False	False
`metrics`	List(Metric)	False	False	False

Metric Schema¶

Field	Type	Required	Readonly	Auto Managed	Example
`name`	String	True	False	False	packets_total
`map_name`	String	True	False	False	PKT_COUNTER
`open_metrics_metadata`	List(OpenMetricsMetadata)	False	False	False

Open Metrics Metadata Schema¶

Field	Type	Required	Readonly	Auto Managed	Example
`type`	String	True	False	False	counter
`help`	String	False	False	False	This metric represents the number of packets that has traveled trough this probe.
`labels`	List(OpenMetricsMetadataLabel)	False	False	False

Open Metrics Metadata Label Schema¶

Field	Type	Required	Readonly	Auto Managed	Example
`name`	String	True	False	False	IP_PROTO
`value`	Any	True	False	False	UDP

Parameter Schema¶

Field	Type	Required	Readonly	Auto Managed	Example
`id`	String	True	True	False	start
`type`	Enum(String) 1	True	False	False	integer
`list`	Boolean	False	False	False	False
`values`	Enum(Any)	False	False	False	yes, no
`description`	String	False	False	False	Network Interface to attach.
`example`	String	False	False	False	10s

1: Possible values are “integer”, “number”, “time-duration”, “string”, “choice”, “boolean”, and “binary”.

Warning

It is not possible to update readonly fields.
it is not possible to set the Auto managed fields.

Note

id is required but it is auto-generated if not provided.

Create¶

To create a new eBPF program in the catalog use the following REST call:

POST /catalog/ebpf-program/(string: id)¶

with the request body in JSON format:

POST /catalog/ebpf-program HTTP/1.1
Host: cb-manager.example.com
Content-Type: application/json

{
    "id": "<ebpf-program-id>",
    "config": {
        "code": "<source-code>",
        "metrics": [
            {
                "name": "<metric-name>",
                "map-name": "<map-name>",
                "open-metrics-metadata": {
                    "type": "<metric-type>",
                    "help": "<metric-help>",
                    "labels": [
                        {
                            "name": "<label-name>",
                            "value": "<label-value>"
                        }
                    ]
                }
            }
        ]
    },
    "parameters": [
        {
            "id": "<parameter-id>",
            "type": "<parameter-type>",
            "example": "<parameter-example>",
            "description": "<parameter-human-readable-description>"
        }
    ]
}

Parameters

id – optional eBPF program id.

Request Headers

Authorization – JWT Authentication.
Content-Type – application/json

Response Headers

Content-Type – application/json

Status Codes

201 Created – eBPF Programs correctly created.
204 No Content – No content to create eBPF programs for the catalog based on the request.
400 Bad Request – Request not valid.
401 Unauthorized – Authentication failed.
406 Not Acceptable – Request validation failed.
415 Unsupported Media Type – Media type not supported.
422 Unprocessable Entity – Not possible to create ore or more eBPF programs for the catalog based on the request.
500 Internal Server Error – Server not available to satisfy the request.

Replace the data with the correct values, for example <ebpf-program-id> with nprobe.

If the creation is correctly executed the response is:

HTTP/1.1 201 Created
Content-Type: application/json

[
    {
        "status": "Created",
        "code": 201,
        "error": false,
        "message": "eBPF program with id=<ebpf-program-id> correctly created"
    }
]

Otherwise, if, for example, an eBPF program with the given id is already found in the catalog, this is the response:

HTTP/1.1 406 Not Acceptable
Content-Type: application/json

[
    {
        "status": "Not Acceptable",
        "code": 406,
        "error": true,
        "message": "Id already found"
    }
]

If some required data is missing (for example type of one parameter), the response could be:

HTTP/1.1 406 Not Acceptable
Content-Type: application/json

[
    {
        "status": "Not Acceptable",
        "code": 406,
        "error": true,
        "message": {
            "parameter.type": "required"
        }
    }
]

Read¶

To get the list of the eBPF programs available in the catalog:

GET /catalog/ebpf-program/(string: id)¶

The response includes all the eBPF programs.

It is possible to filter the results using the following request body:

GET /catalog/ebpf-program HTTP/1.1
Host: cb-manager.example.com
Content-Type: application/json

{
    "select": [ "parameters" ],
    "where": {
        "equals": {
            "target": "id",
            "expr": "<ebpf-program-id>"
        }
    }
}

In this way, it will be returned only the parameters of the eBPF program in the catalog with id = “<ebpf-program-id>”.

Update¶

To update an eBPF program in the catalog, use:

PUT /catalog/ebpf-program/(string: id)¶

PUT /catalog/ebpf-program HTTP/1.1
Host: cb-manager.example.com
Content-Type: application/json

{
    "id": "<ebpf-program-id>",
    "parameters": [
        {
            "id": "<parameter-id>",
            "type": "<new-parameter-type>"
        }
    ]
}

Parameters

id – optional eBPF program id.

Request Headers

Authorization – JWT Authentication.
Content-Type – application/json

Response Headers

Content-Type – application/json

Status Codes

200 OK – All eBPF programs in the catalog correctly updated.
204 No Content – No content to update eBPF programs in the catalog based on the request.
304 Not Modified – Update for one or more eBPF programs in the catalog not necessary.
400 Bad Request – Request not valid.
401 Unauthorized – Authentication failed.
406 Not Acceptable – Request validation failed.
415 Unsupported Media Type – Media type not supported.
422 Unprocessable Entity – Not possible to update one or more eBPF programs in the catalog based on the request.
500 Internal Server Error – Server not available to satisfy the request.

This example updates the new type of the parameter with id = “<parameter-id>” of the eBPF program with id = “<ebpf-program-id>”.

A possible response is:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "status": "OK",
        "code": 200,
        "error": false,
        "message": "eBPF Program catalog with id=<ebpf-program-id> correctly updated"
    }
]

Instead, if the are not changes the response is:

HTTP/1.1 304 Not Modified
Content-Type: application/json

[
    {
        "status": "Not Modified",
        "code": 304,
        "error": false,
        "message": "Update for eBPF program catalog with id=<ebpf-program-id> not necessary"
    }
]

Delete¶

To delete eBPF programs from the catalog, use:

DELETE /catalog/ebpf-program/(string: id)¶

DELETE /catalog/ebpf-program HTTP/1.1
Host: cb-manager.example.com
Content-Type: application/json

{
    "where": {
        "equals": {
            "target": "id",
            "expr": "<ebpf-program-id>"
        }
    }
}

Parameters

id – optional eBPF program id from the catalog.

Request Headers

Authorization – JWT Authentication.
Content-Type – application/json

Response Headers

Content-Type – application/json

Status Codes

205 Reset Content – All eBPF programs correctly deleted from the catalog.
400 Bad Request – Request not valid.
401 Unauthorized – Authentication failed.
404 Not Found – eBPF programs based on the request query not found in the catalog.
406 Not Acceptable – Request validation failed.
415 Unsupported Media Type – Media type not supported.
422 Unprocessable Entity – Not possible to delete one or more eBPF programs from the catalog based on the request query.
500 Internal Server Error – Server not available to satisfy the request.

This request removes from the catalog the eBPF program with id = “<ebpf-program-id>”.

This is a possible response:

HTTP/1.1 205 Reset Content
Content-Type: application/json

[
    {
        "status": "Reset Content",
        "code": 200,
        "error": false,
        "message": "eBPF program catalog the id=<agent-id> correctly deleted"
    }
]

Caution

Without request body, it removes all the eBPF programs from the catalog.