Conception/architecture de BPF étendu¶

Un processus utilisateur peut créer plusieurs mappes (dont les paires clé/valeur sont des octets de données opaques) et y accéder par les descripteurs de fichier. Différents programmes eBPF peuvent accéder aux mêmes mappes en parallèle. Il appartient au processus utilisateur et au programme eBPF de décider ce qu'ils stockent dans leurs mappes.

Il existe un type de mappe spécial appelé un tableau de programmes (« program array »). Ce type de mappe stocke des descripteurs de fichiers qui renvoient à d'autres programmes eBPF. Quand une recherche est effectuée sur la mappe, le flux du programme est redirigé directement au début d'un autre programme eBPF et il ne renvoie rien au programme appelant. Le niveau de redirections est de 32 pour éviter de créer des boucles infinies. Au moment de l'exécution, les descripteurs de fichier du programme stockés dans la mappe peuvent être modifiés, donc la fonctionnalité de programme peut être modifiée sur la base d'exigences spécifiques. Tous les programmes auxquels renvoie une mappe tableau de programmes (program-array) doivent avoir été précédemment chargés dans le noyau avec bpf(). Si une recherche de mappe échoue, le programme en cours poursuit son exécution. Voir BPF_MAP_TYPE_PROG_ARRAY ci-dessous pour des détails.

Généralement, les programmes eBPF sont chargés par le processus de l'utilisateur et déchargés automatiquement quand le processus se termine. Dans certains cas, par exemple tc-bpf(8), le programme restera en vie dans le noyau même après que le processus qui l'a chargé est fini. Dans ce cas, le sous-système tc garde une référence au programme eBPF après que le descripteur de fichier est fermé par le programme de l'espace utilisateur. Ainsi, la survie d'un programme spécifique dans le noyau dépend de la manière dont il a été rattaché à un sous-système donné du noyau après qu'il a été chargé par bpf().

Chaque programme eBPF est un ensemble d'instructions qu'on peut exécuter en sécurité jusqu'à leur fin. Un vérificateur interne au noyau détermine de manière statique ce que le programme eBPF interrompt et s'il peut être exécuté en toute sécurité. Pendant la vérification, le noyau ajoute un numéro de référence de manière incrémentale pour chacune des mappes utilisées par le programme eBPF, si bien que les mappes qui y sont rattachées ne peuvent pas être supprimées avant que le programme soit déchargé.

Les programmes eBPF peuvent être rattachés à différents événements. Ces événements peuvent être l'arrivée de paquets réseaux, le traçage d'événements, la classification d'événements en disciplines de files d'attente réseau (pour les programmes eBPF rattachés à un classificateur tc(8)), et d'autres types qui pourront être ajoutés dans le futur. Un nouvel événement provoque l'exécution d'un programme eBPF, qui peut stocker des informations sur l’évènement dans des mappes eBPF. Par-delà les données stockées, les programmes eBPF peuvent appeler un ensemble fixé de fonctions d'aide internes au noyau.

Un même programme eBPF peut être rattaché à plusieurs événements (évt) et divers programmes eBPF peuvent accéder à la même mappe :

traçage     traçage    traçage    paquet       paquet      paquet
 évt A       évt B      évt C    sur eth0     sur eth1    sur eth2
  |             |         |          |           |           ^
  |             |         |          |           v           |
  --> traçage <--      traçage     socket    tc ingress   tc egress
       prog_1          prog_2      prog_3    classifieur   action
       |  |              |           |         prog_4      prog_5
    |---  -----|  |------|         mappe_3        |           |
 mappe_1     mappe_2                              -| mappe_4 |-

Arguments¶

La valeur fournie dans cmd est une parmi :

BPF_MAP_CREATE

Créer une mappe et renvoyer un descripteur de fichier qui s'y rapporte. Le drapeau de descripteur de fichier close-on-exec (voir fcntl(2)) est automatiquement activé pour le nouveau descripteur de fichier.

BPF_MAP_LOOKUP_ELEM

Chercher un élément par clé dans une mappe spécifiée et renvoyer sa valeur.

BPF_MAP_UPDATE_ELEM

Créer ou mettre à jour un élément (paire clé/valeur) dans une mappe spécifiée.

BPF_MAP_DELETE_ELEM

Chercher et effacer un élément par clé dans une mappe spécifiée.

BPF_MAP_GET_NEXT_KEY

Chercher un élément par clé dans une mappe spécifiée et renvoyer la clé de l'élément suivant.

BPF_PROG_LOAD

Vérifier et charger un programme eBPF, en renvoyant un nouveau descripteur de fichier associé au programme. Le drapeau de descripteur de fichier close-on-exec (voir fcntl(2)) est activé automatiquement pour le nouveau descripteur de fichier.

L'union bpf_attr consiste dans diverses structures anonymes utilisées par différentes commandes bpf() :

union bpf_attr {
    struct {    /* Utilisé par BPF_MAP_CREATE */
        __u32         map_type;
        __u32         key_size;    /* taille de la clé en octets */
        __u32         value_size;  /* taille de la valeur en octets */
        __u32         max_entries; /* nombre maximal d'entrées
                                      dans une mappe */
    };
    struct {    /* Utilisé par les commandes BPF_MAP_*_ELEM et
                   BPF_MAP_GET_NEXT_KEY */
        __u32         map_fd;
        __aligned_u64 key;
        union {
            __aligned_u64 value;
            __aligned_u64 next_key;
        };
        __u64         flags;
    };
    struct {    /* Utilisé par BPF_PROG_LOAD */
        __u32         prog_type;
        __u32         insn_cnt;
        __aligned_u64 insns;      /* 'const struct bpf_insn *' */
        __aligned_u64 license;    /* 'const char *' */
        __u32         log_level;  /* niveau de précisions du vérificateur */
        __u32         log_size;   /* taille du tampon utilisateur */
        __aligned_u64 log_buf;    /* l'utilisateur a fourni le tampon
                                     'char *' */
        __u32         kern_version;
                                  /* vérifié si prog_type=kprobe
                                     (depuis Linux 4.1) */
    };
} __attribute__((aligned(8)));

mappes eBPF¶

Chaque type de mappe a les attributs suivants :

• type
• nombre maximal d'éléments
• taille de la clé en octets
• valeur de la clé en octets

Les fonctions enveloppe suivantes montrent la manière dont diverses commandes bpf() peuvent être utilisées pour accéder aux mappes. Les fonctions utilisent le paramètre cmd pour appeler différentes opérations.

BPF_MAP_CREATE

La commande BPF_MAP_CREATE crée une nouvelle mappe, renvoyant un nouveau descripteur de fichier qui s'y rapporte.

int
bpf_create_map(enum bpf_map_type map_type,
               unsigned int key_size,
               unsigned int value_size,
               unsigned int max_entries)
{
    union bpf_attr attr = {
        .map_type    = map_type,
        .key_size    = key_size,
        .value_size  = value_size,
        .max_entries = max_entries
    };
    return bpf(BPF_MAP_CREATE, &attr, sizeof(attr));
}

    

La nouvelle mappe possède le type indiqué avec map_type et les attributs indiqués dans key_size, value_size et max_entries. En cas de succès, cette opération renvoie un descripteur de fichier. En cas d'erreur, -1 est renvoyé et errno est positionné sur EINVAL, EPERM ou ENOMEM.

Les attributs key_size et value_size seront utilisés par le vérificateur lors du chargement du programme pour vérifier que le programme appelle les fonctions d'aide bpf_map_*_elem() avec une key correctement initialisée et pour vérifier que le programme n'accède pas à une value de l'élément de la mappe au-delà de la value_size indiquée. Par exemple, quand une mappe est créée avec key_size de 8 et que le programme eBPF appelle un

bpf_map_lookup_elem(map_fd, fp - 4)

    

le programme sera rejeté, puisque la fonction d'aide du noyau

    bpf_map_lookup_elem(map_fd, void *key)
    

s'attend à lire 8 octets à l'endroit où pointe key, mais l'adresse de départ fp - 4 (où fp est le haut de la pile) crée un accès de la pile hors limites.

De même, lorsqu'une mappe est créée avec une value_size de 1 et que le programme eBPF contient

value = bpf_map_lookup_elem(...);
*(u32 *) value = 1;

    

le programme sera rejeté puisqu'il accède au pointeur value au-delà de la la limite value_size d’un octet spécifiée.

Actuellement, les valeurs suivantes sont prises en charge par map_type :

enum bpf_map_type {
    BPF_MAP_TYPE_UNSPEC,  /* Réserver 0 comme type de mappe non valable */
    BPF_MAP_TYPE_HASH,
    BPF_MAP_TYPE_ARRAY,
    BPF_MAP_TYPE_PROG_ARRAY,
    BPF_MAP_TYPE_PERF_EVENT_ARRAY,
    BPF_MAP_TYPE_PERCPU_HASH,
    BPF_MAP_TYPE_PERCPU_ARRAY,
    BPF_MAP_TYPE_STACK_TRACE,
    BPF_MAP_TYPE_CGROUP_ARRAY,
    BPF_MAP_TYPE_LRU_HASH,
    BPF_MAP_TYPE_LRU_PERCPU_HASH,
    BPF_MAP_TYPE_LPM_TRIE,
    BPF_MAP_TYPE_ARRAY_OF_MAPS,
    BPF_MAP_TYPE_HASH_OF_MAPS,
    BPF_MAP_TYPE_DEVMAP,
    BPF_MAP_TYPE_SOCKMAP,
    BPF_MAP_TYPE_CPUMAP,
};

    

map_type sélectionne une des implémentations de mappe disponibles dans le noyau. Pour tous les types de mappe, les programmes eBPF accèdent aux mappes avec les mêmes fonctions d'aide bpf_map_lookup_elem() et bpf_map_update_elem(). Vous trouverez ci-dessous plus de détails sur les différents types de mappes.

BPF_MAP_LOOKUP_ELEM

La commande BPF_MAP_LOOKUP_ELEM cherche un élément avec une key donnée dans la mappe à laquelle se rapporte le descripteur de fichier fd.

int
bpf_lookup_elem(int fd, const void *key, void *value)
{
    union bpf_attr attr = {
        .map_fd = fd,
        .key    = ptr_to_u64(key),
        .value  = ptr_to_u64(value),
    };
    return bpf(BPF_MAP_LOOKUP_ELEM, &attr, sizeof(attr));
}

    

Si un élément est trouvé, l'opération renvoie zéro et stocke la valeur de l'élément dans value, qui doit pointer vers un tampon de value_size octets.

Si aucun élément n'est trouvé, l'opération renvoie -1 et errno est positionné sur ENOENT.

BPF_MAP_UPDATE_ELEM

La commande BPF_MAP_UPDATE_ELEM crée ou met à jour un élément avec une key/value donnée dans la mappe à laquelle se rapporte le descripteur de fichier fd.

int
bpf_update_elem(int fd, const void *key, const void *value,
                uint64_t flags)
{
    union bpf_attr attr = {
        .map_fd = fd,
        .key    = ptr_to_u64(key),
        .value  = ptr_to_u64(value),
        .flags  = flags,
    };
    return bpf(BPF_MAP_UPDATE_ELEM, &attr, sizeof(attr));
}

    

Le paramètre flags devrait être formé d'une des manières suivantes :

En cas de succès, l'opération renvoie zéro. En cas d'erreur, -1 est renvoyé et errno est positionné sur EINVAL, EPERM, ENOMEM ou E2BIG. E2BIG indique que le nombre d'éléments de la mappe a atteint la limite max_entries spécifiée au moment de la création de la mappe. EEXIST sera renvoyé si flags spécifie BPF_NOEXIST et si l'élément contenant key existe déjà sur la mappe. ENOENT sera renvoyé si flags spécifie BPF_EXIST et si l'élément contenant key n'existe pas sur la mappe.

BPF_MAP_DELETE_ELEM

La commande BPF_MAP_DELETE_ELEM efface l'élément dont la clé est key sur la mappe à laquelle se rapporte le descripteur de fichier fd.

int
bpf_delete_elem(int fd, const void *key)
{
    union bpf_attr attr = {
        .map_fd = fd,
        .key    = ptr_to_u64(key),
    };
    return bpf(BPF_MAP_DELETE_ELEM, &attr, sizeof(attr));
}

    

S'il réussit, cet appel système renvoie 0. Si l'élément n'est pas trouvé, -1 est renvoyé et errno est positionné sur ENOENT.

BPF_MAP_GET_NEXT_KEY

La commande BPF_MAP_GET_NEXT_KEY recherche un élément par key sur la mappe à laquelle se réfère le descripteur de fichier fd et elle définit le pointeur next_key vers la clé du prochain élément.

int
bpf_get_next_key(int fd, const void *key, void *next_key)
{
    union bpf_attr attr = {
        .map_fd   = fd,
        .key      = ptr_to_u64(key),
        .next_key = ptr_to_u64(next_key),
    };
    return bpf(BPF_MAP_GET_NEXT_KEY, &attr, sizeof(attr));
}

    

Si key est trouvée, l'opération renvoie zéro et next_key pointe vers la clé de l'élément suivant. Si key n'est pas trouvée, l'opération renvoie zéro et next_key pointe vers la clé du premier élément. Si key est le dernier élément, -1 est renvoyé et errno est positionné sur ENOENT. Les autres valeurs possibles de errno sont ENOMEM, EFAULT, EPERM et EINVAL. Cette méthode peut être utilisée pour itérer entre tous les éléments d'une mappe.

close(map_fd)

Effacer la mappe à laquelle se réfère le descripteur de fichier map_fd. Quand le programme de l'espace utilisateur ayant créé la mappe se termine, toutes les mappes sont effacées automatiquement (mais voir REMARQUES).

Types de mappe eBPF¶

BPF_MAP_TYPE_HASH

Les mappes table de hachage (hash-table) présentent les caractéristiques suivantes :

Les mappes table de hachage (hash-table) sont optimisées pour accélérer la recherche.

BPF_MAP_TYPE_ARRAY

Les mappes tableau (array) présentent les caractéristiques suivantes :

Voici quelques cas d'usage des mappes tableau (array) :

BPF_MAP_TYPE_PROG_ARRAY (depuis Linux 4.2)

Une mappe tableau de programmes est un type spécial de mappe tableau dont les valeurs ne contiennent que des descripteurs de fichier qui se rapportent à d'autres programmes eBPF. Ainsi, tant key_size que value_size doivent être d'exactement quatre octets. Cette mappe est utilisée en association avec l'aide bpf_tail_call().

Cela signifie qu'un programme eBPF auquel est rattaché un tableau de programmes (program array) peut appeler à partir du noyau

void bpf_tail_call(void *context, void *prog_map,
                   unsigned int index);

    

et donc remplacer le flux de son propre programme par celui du programme sur la tranche du tableau de programmes donné s'il y en a un. Vous pouvez considérer cela comme un saut de tableau vers un autre programme eBPF. Le programme appelé réutilisera ensuite la même pile. Quand un saut vers un nouveau programme a été fait, il ne renverra plus à l'ancien programme.

Si aucun programme eBPF n'est trouvé sur l'indice donné du tableau de programmes (car la tranche de la mappe ne contient pas de descripteur de fichier de programme valable, la recherche d'indice/clé indiquée dépasse la plage ou la limite de 32 appels en interne a été dépassée), l'exécution continue avec le programme eBPF actuel. Cela peut être utilisé comme solution de repli pour les cas par défaut.

Une mappe tableau de programmes sert, par exemple, à tracer ou mettre en réseau, à gérer des appels système individuels ou des protocoles dans leurs propres sous-programmes et à utiliser leurs identifiants comme identifiant individuel de mappe. Cette approche peut apporter des gains de performance et permet de dépasser la limite du nombre d'instructions d'un programme eBPF. Dans des environnements dynamiques, un démon de l'espace utilisateur pourrait remplacer de manière atomique des sous-programmes au moment de leur exécution par de nouvelles versions, pour modifier le comportement général d'un programme, par exemple, si les règles globales changent.

Programmes eBPF¶

char bpf_log_buf[LOG_BUF_SIZE];
int
bpf_prog_load(enum bpf_prog_type type,
              const struct bpf_insn *insns, int insn_cnt,
              const char *license)
{
    union bpf_attr attr = {
        .prog_type = type,
        .insns     = ptr_to_u64(insns),
        .insn_cnt  = insn_cnt,
        .license   = ptr_to_u64(license),
        .log_buf   = ptr_to_u64(bpf_log_buf),
        .log_size  = LOG_BUF_SIZE,
        .log_level = 1,
    };
    return bpf(BPF_PROG_LOAD, &attr, sizeof(attr));
}

prog_type est un des types de programme suivants :

enum bpf_prog_type {
    BPF_PROG_TYPE_UNSPEC,        /* Réserver 0 comme type de
                                    programme non valable */
    BPF_PROG_TYPE_SOCKET_FILTER,
    BPF_PROG_TYPE_KPROBE,
    BPF_PROG_TYPE_SCHED_CLS,
    BPF_PROG_TYPE_SCHED_ACT,
};

    

Pour plus de détails sur le type de programme eBPF, voir ci-dessous.

Les autres champs de bpf_attr sont définis comme suit :

• insns est un tableau d'instructions struct bpf_insn.
• insn_cnt est le nombre d'instructions du programme auquel se rapporte insns.
• license est une chaîne de licence, qui doit être compatible GPL pour appeler les fonctions d'aide marquées comme gpl_only (les règles de licence sont les mêmes que celles pour les modules du noyau, pour que même des licences duales, telles que « Dual BSD/GPL », puissent être utilisées).
• log_buf est un pointeur vers un tampon alloué à l’appelant (caller-allocated) où le vérificateur du noyau peut stocker le journal de sa vérification. Ce journal est une chaîne de plusieurs lignes qui peut être vérifiée par l'auteur du programme pour comprendre la manière par laquelle le vérificateur est arrivé à la conclusion que le programme eBPF n'est pas sûr. Le format de sortie peut changer n'importe quand puisque le vérificateur évolue.
• log_size dimensionne le tampon vers lequel pointe log_buf. Si la taille du tampon n'est pas assez grande pour stocker tous les messages du vérificateur, -1 est renvoyé et errno est positionné sur ENOSPC.
• Le niveau de précisions log_level du vérificateur. Une valeur de zéro signifie que le vérificateur ne génèrera aucun journal ; dans ce cas log_buf doit être un pointeur NULL et log_size doit valoir zéro.

Le fait d'appliquer close(2) au descripteur de fichier renvoyé par BPF_PROG_LOAD déchargera le programme eBPF (mais voir les REMARQUES).

Les mappes sont accessibles à partir des programmes eBPF et elles sont utilisées pour échanger des données entre des programmes eBPF et entre des programmes eBPF et d'autres de l'espace utilisateur. Par exemple, des programmes eBPF peuvent traiter divers événements (comme kprobe, packets) et stocker leurs données dans une mappe, et les programmes de l'espace utilisateur peuvent alors récupérer ces données dans la mappe. Inversement, des programmes de l'espace utilisateur peuvent utiliser une mappe en tant que mécanisme de configuration, la mappe étant peuplée par des valeurs vérifiées par le programme eBPF qui modifie ensuite son comportement à la volée en fonction de ces valeurs.

Types de programme eBPF¶

Par exemple, un programme de traçage n'a pas exactement le même sous-jeu de fonctions d'aide qu'un programme de filtrage de socket (bien qu'ils peuvent en avoir en commun). De même l'entrée (le contexte) d'un programme de traçage est un jeu de valeurs de registre, alors que ce sera un paquet réseau pour le filtrage de socket.

Le jeu de fonctions disponibles pour les programmes eBPF d'un type donné pourra augmenter dans le futur.

Les types de programmes suivants sont pris en charge :

BPF_PROG_TYPE_SOCKET_FILTER (depuis Linux 3.19)

Actuellement, le jeu de fonctions pour BPF_PROG_TYPE_SOCKET_FILTER est :

bpf_map_lookup_elem(map_fd, void *key)
                    /* rechercher la clé dans une map_fd */
bpf_map_update_elem(map_fd, void *key, void *value)
                    /* mettre à jour la clé/valeur */
bpf_map_delete_elem(map_fd, void *key)
                    /* effacer la clé d'une map_fd */

    

Le paramètre bpf_context est un pointeur vers une struct __sk_buff.

BPF_PROG_TYPE_KPROBE (depuis Linux 4.1)

[À documenter]

BPF_PROG_TYPE_SCHED_CLS (depuis Linux 4.1)

[À documenter]

BPF_PROG_TYPE_SCHED_ACT (depuis Linux 4.1)

[À documenter]

Événements¶

Depuis Linux 3.19, l'appel suivant rattachera le programme prog_fd au socket sockfd, qui a été précédemment créé par un appel socket(2) :

setsockopt(sockfd, SOL_SOCKET, SO_ATTACH_BPF,
           &prog_fd, sizeof(prog_fd));

Depuis Linux 4.1, l'appel suivant peut être utilisé pour rattacher un programme eBPF auquel se rapporte le descripteur de fichier prog_fd à un descripteur de fichier d'événement perf, event_fd, créé par un appel précédent à perf_event_open(2) :

ioctl(event_fd, PERF_EVENT_IOC_SET_BPF, prog_fd);