.\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>.
.\" Permission is granted to distribute possibly modified copies
.\" of this page provided the header is included verbatim,
.\" and in case of nontrivial modification author and date
.\" of the modification is added to the header.
.\" $Id: packet.7,v 1.13 2000/08/14 08:03:45 ak Exp $
.\" Traduction Christophe Blaess <ccb@club-internet.fr> 
.\" 08/06/2001 - LDP-man-pages-1.37
.TH PACKET 7 "8 juin 2001" Linux "Manuel de l'administrateur Linux"
.SH NAME
packet, PF_PACKET \- Interface par paquet au niveau p�riph�rique.

.\" yes, this is ugly.
.SH SYNOPSIS
.nf
.B #include <sys/socket.h>
.br
.B #include <features.h>	/* pour avoir la version GlibC */
.br
.B #if __GLIBC__ >= 2 && __GLIBC_MINOR >= 1 
.br
.B #include <netpacket/packet.h>
.br
.B #include <net/ethernet.h>	/* protocoles L2 */
.br
.B #else
.br
.B #include <asm/types.h>
.br
.B #include <linux/if_packet.h>
.br
.B #include <linux/if_ether.h>	/* protocoles L2 */ 
.br
.B #endif
.sp
.PP
.BI "packet_socket = socket(PF_PACKET, int " socket_type ", int "protocol ); 
.fi
.SH DESCRIPTION
Les sockets packets sont utilis�es pour envoyer ou recevoir des paquets de donn�es
bruts au pilote de p�riph�rique (Niveau OSI 2).
Elles permettent d'impl�menter des modules protocoles dans l'espace utilisateur
au dessus du niveau physique.

L'argument
.I socket_type
est soit
.B SOCK_RAW 
pour les paquets incluant l'ent�te du niveau liaison, soit
.B SOCK_DGRAM
pour les paquets pr�par�s sans l'ent�te de la couche liaison. Les informations de l'ent�te
du niveau liaison sont disponibles dans un format commun, par l'interm�diaire d'un
.BR sockaddr_ll . 
.I protocol 
est un num�ro de protocole IEEE 802.3 dans l'ordre des octets du r�seau. Voir le fichier d'ent�te
.B <linux/if_ether.h> 
pour avoir une liste des protocoles autoris�s. Lorsque le num�ro demand�
est
.B htons(ETH_P_ALL) 
alors tous les protocoles sont re�us.
Tous les paquets entrants du protocole indiqu� seront pass�s � la socket packet avant d'�tre
transmis aux protocoles impl�ment�s dans le noyau.
 
Seuls les processus avec un UID effectif nul ou la capacit�
.B CAP_NET_RAW
peuvent ouvrir des sockets packet.

Les paquets des sockets
.B SOCK_RAW
sont transmis depuis et vers le pilote de p�riph�rique sans aucune modification des donn�es des paquets.
Lors de la r�ception, l'adresse est toujours examin�e et fournie dans une structure standard
.B sockaddr_ll
Lors de l'�mission d'un paquet, le buffer fourni par l'utilisateur doit contenir l'ent�te du niveau
physique. Le paquet est alors mis en file sans modification
� l'attention du pilote de p�riph�rique correspondant � l'interface d�finie par
l'adresse de destination. Certains pilotes de p�riph�rique ajoute toujours d'autres ent�te.
.B SOCK_RAW
est identique mais non compatible avec l'ancient
.B SOCK_PACKET
de Linux 2.0.

.B SOCK_DGRAM 
op�re � un niveau l�g�rement plus �lev�. L'ent�te du niveau physique est supprim� avant que le
paquet ne soit transmis � l'utilisateur. Les paquets envoy�s par une socket packet
.B SOCK_DGRAM
recoivent un ent�te de niveau physique correct, en fonction des informations dans
l'adresse destination
.B sockaddr_ll 
avant d'�tre mis en file.

Par d�faut tous les paquets du type de protocole indiqu� sont
pass�s � la socket packet. Pour ne recevoir que les paquets d'une interface donn�e
utilisez
.BR bind (2)
en indiquant une adresse dans une 
.B struct sockaddr_ll
pour attacher la socket � une interface. Seuls les champs d'adresse
.B sll_protocol 
et
.B sll_ifindex
sont utilis�s pour l'attachement.

L'op�ration
.BR connect (3)
n'est pas support�e sur les sockets packet.

Lorsque l'attribut
.B MSG_TRUNC
est transmis � 
.BR recvmsg (2),
.BR recv (2),
.BR recvfrom (2)
la v�ritable longueur du paquet sur le r�seau est toujours renvoy�e, m�me si elle
est plus grande que le buffer.

.SH "TYPES D'ADRESSE"
La structure sockaddr_ll est une adresse du niveau physique d�pendant du p�riph�rique.

.RS
.nf
.ta 4n 20n 35n
struct sockaddr_ll {�
	unsigned short	sll_family;   /* Toujours AF_PACKET        */
	unsigned short	sll_protocol; /* Protocole niveau physique */
	int	sll_ifindex;          /* Num�ro d'interface        */
	unsigned short	sll_hatype;   /* Type d'ent�te             */
	unsigned char	sll_pkttype;  /* Type de paquet            */
	unsigned char	sll_halen;    /* Longueur de l'adresse     */
	unsigned char	sll_addr[8];  /* Adresse niveau physique   */
};
.ta
.fi
.RE

.B sll_protocol 
est le type de protocole standard ethernet, dans l'ordre des octets du,
comme d�fini dans le fichier d'ent�te.
.B linux/if_ether.h   
Par d�faut il s'agit du protocole de la socket.
.B sll_ifindex 
est le numr�ro de l'interface
(voir
.BR netdevice (2));
0 correspond � n'importe quelle interface (autoris� uniquement pour l'attachement).
.B sll_hatype 
est un type ARP, comme d�fini dans le fichier d'ent�te
.B linux/if_arp.h 
Le champ
.B sll_pkttype 
contient le type de paquet. Les types valides sont
.B PACKET_HOST
pour un paquet destin� � l'h�te local,
.B PACKET_BROADCAST
pour un paquet broadcast du niveau physique,
.B PACKET_MULTICAST
pour un paquet envoy� � une adresse multicast du niveau physique,
.B PACKET_OTHERHOST
pour un paquet destin� � un autre h�te captur� par un pilote de p�riph�rique en
mode promiscuous, et
.B PACKET_OUTGOING
pour un paquet provenant de l'h�te local reboucl� sur une socket packet.
Ceci n'a de signification qu'en r�ception.
.B sll_addr
et
.B sll_halen
contiennent l'adresse de niveau physique (par exemple IEEE 802.3) et sa longueur. L'interpr�tation
exacte d�pend du p�riph�rique.

Lorsqu'on envoie des paquets, il suffit d'indiquer
.BR sll_family ,
.BR sll_addr ,
.BR sll_halen ,
.BR sll_ifindex .
Les autres champs devraient �tre � z�ro.
.B sll_hatype
et
.B sll_pkttype
sont remplis en r�ception pour information.
Pour l'attachement, seuls
.B sll_protocol
et
.B sll_ifindex
sont utilis�s.

.SH "OPTIONS DES SOCKETS"
Les options des sockets packets permettent de configurer le multicasting du niveau physique
et le mode promiscuous. Cela fonctionne en appelant
.BR setsockopt (2) 
sur une socket packet avec SOL_PACKET et l'option
.B PACKET_ADD_MEMBERSHIP 
pour ajouter un attachement ou
.B PACKET_DROP_MEMBERSHIP
pour en supprimer un.
Toutes les deux attendent une structure
.B packet_mreq
en argument :

.RS
.nf
.ta 4n 20n 35n
struct packet_mreq
{
	int            mr_ifindex;    /* Num�ro d'interface      */
	unsigned short mr_type;       /* Action                  */
	unsigned short mr_alen;       /* Longueur d'adresse      */
	unsigned char  mr_address[8]; /* Adresse niveau physique */
};
.ta
.fi
.RE 

.B mr_ifindex
contient le num�ro de l'interface dont le statut doit
�tre modifi�.
Le param�tre
.B mr_type
indique l'action � effectuer.
.B PACKET_MR_PROMISC
valide la r�ception de tous les paquets circulant sur le segment de r�seau commun. Souvent appel�
``mode promiscuous''.
.B PACKET_MR_MULTICAST 
attache la socket au groupe multicast de niveau physique indiqu� dans 
.B mr_address
et
.BR mr_alen ,
et
.B PACKET_MR_ALLMULTI
demande � la socket de recevoir tous les paquets multicast arrivant sur l'interface.

De plus, les ioctls classiques
.B SIOCSIFFLAGS,
.B SIOCADDMULTI, 
.B SIOCDELMULTI
peuvent donner les m�mes r�sultats.


.SH IOCTLS
.B SIOCGSTAMP
peut servir � obtenir l'horodatage du dernier paquet re�u. L'argument est une
structure
.B struct timeval.

De plus, les ioctls standards d�finis dans
.BR netdevice (7)
et
.BR socket (7)
sont valides sur les sockets packets.

.SH "GESTION D'ERREUR"
Les sockets packets ne g�re pas d'autres erreurs que celles se produisant durant la transmission
des paquets au pilote de p�riph�rique. Elles ne traitent pas le concept
de file d'erreurs.

.SH COMPATIBILIT�
Sous Linux 2.0, la seule mani�re d'obtenir une socket packet �tait l'appel
.BI "socket(PF_INET, SOCK_PACKET, " protocol )\fR.
Ceci est encore support� mais fortement d�conseill�.
La principale diff�rence entre les deux m�thodes est que
.B SOCK_PACKET
utilise l'ancienne
.B struct sockaddr_pkt
pour indiquer l'interface, ce qui ne fournit aucune ind�pendance vis-�-vis du niveau physique.

.RS
.nf
.ta 4n 20n 35n
struct sockaddr_pkt
{
	unsigned short	spkt_family;
	unsigned char	spkt_device[14];
	unsigned short	spkt_protocol;
};
.ta
.fi
.RE

.B spkt_family 
contient le
type de p�riph�rique
.B spkt_protocol 
est le type de protocole IEEE 802.3 comme d�fini dans
.B <sys/if_ether.h>
et
.B spkt_device 
est le nom du p�riph�rique sous forme de cha�ne termin�e par un caract�re nul, par exemple eth0.

Cette structure est obsol�te et ne doit pas �tre employ� dans des nouveaux programmes.

.SH NOTES
Pour la portabiblit�, il est conseill� d'utiliser les fonctionnalit�s
.B PF_PACKET
par l'interm�diaire de l'interface
.BR pcap (3);
bien que cela ne couvre qu'un sous-ensembles des
possibilit�s de
.BR PF_PACKET .

Les sockets packet
.B SOCK_DGRAM
n'essayent pas de cr�er ou de traiter les ent�tes IEEE 802.2 LLC pour
une trame IEEE 802.3.
Lorsque le protocole
.B ETH_P_802_3 
est indiqu� en �mission, le noyau cr�e la trame
802.3 et remplit le champ de longueur. L'utilisateur doit fournir l'ent�te
LLC pour obtenir un paquet enti�rement conforme. Les paquets 802.3 entrants ne sont pas
multiplex�s sur les champs du protocole DSAP/SSAP. A la place, ils sont fournis � l'utilisateur
sous le protocole
.B ETH_P_802_2
sans ent�te LLC ajout�. Il n'est donc pas possible de faire d'attachement
.B ETH_P_802_3;
L'attachement
.B ETH_P_802_2 
doit �tre r�alis� � la place, et le multiplexage de protocole doit �tre r�alis� manuellement.
Le comportement par d�faut en �mission est l'encapsulation Ethernet DIX standard, avec le
protocole renseign�.

Les sockets packets ne sont pas soumises aux cha�nes de firewall en entr�e ou sortie.

.SH ERREURS
.TP
.B ENETDOWN
L'interface n'est pas en marche.

.TP
.B ENOTCONN
No interface address passed.

.TP
.B ENODEV
Unknown device name or interface index specified in interface address.

.TP
.B EMSGSIZE
Le paquet est plus grand que le MTU de l'interface.

.TP
.B ENOBUFS
Pas assez de m�moire pour le paquet.

.TP
.B EFAULT
Adresse m�moire invalide.

.TP
.B EINVAL
Argument invalide.

.TP
.B ENXIO
Num�ro d'interface ill�gal.

.TP
.B EPERM
L'utilisateur n'a pas les privil�ges n�cessaires pour l'op�ration.

.TP
.B EADDRNOTAVAIL
Adresse de groupe multicast inconnue.

.TP
.B ENOENT
Pas de paquet re�u.

De plus, d'autres erreurs peuvent �tre engendr�es par le pilote bas-niveau.
.SH VERSIONS
.B PF_PACKET 
est une nouveaut� de Linux 2.2. Les versions Linux pr�c�dente ne supportaient que
.B SOCK_PACKET.

.SH BOGUES
La GlibC 2.1 ne d�finit pas la constante symbolique
.B SOL_PACKET.
Pour contourner ce probl�me, il est conseill� d'�crire :
.RS
.nf
#ifndef SOL_PACKET
#define SOL_PACKET 263
#endif
.fi
.RE
Ceci est corrig� dans les derni�res versions de la GlibC et ne se produit pas sur les LibC5.

La gestion des ent�tes LLC IEEE 802.2/802.3 devrait �tre consid�r�e comme un bogue.

Les filtres des sockets ne sont pas document�s.

L'extension
.I MSG_TRUNC
de recmsg est une bidouille horrible et devrait �tre remplac�e par un message de commande.
Il n'y a actuellement aucun moyen d'obtenir l'adresse de destination originale des
paquets via SOCK_DGRAM.

.SH CR�DITS
Cette page de manuel a �t� �crite par Andi Kleen avec l'aide de Matthew Wilcox.
PF_PACKET sous Linux 2.2 a �t� impl�ment�
par Alexey Kuznetsov, d'apr�s du code d'Alan Cox et d'autres.

.SH "VOIR AUSSI"
.BR ip (7),
.BR socket (7),
.BR socket (2),
.BR raw (7),
.BR pcap (3).

RFC 894 pour l'encapsulation standard Ethernet.

RFC 1700 pour l'encapsulation IP IEEE 802.3.

Le fichier d'ent�te
.BR linux/if_ether.h
pour les protocoles du niveau physique.
 
.SH TRADUCTION
Christophe Blaess, 2001.