\" Copyright (c) 1996 Free Software Foundation, Inc.
.\" Ce programme est distribu en accord avec la Licence Publique Gnrale Gnu.
.\" Voir le fichier COPYING dans le rpertoire des sources du noyau.
.\" MJ 30/07/21 modutils-2.4.22
.TH INSMOD 8 "30 juillet 2003" modutils "Manuel de l'administrateur Linux"
.SH NOM
insmod \- Charge des modules dans le noyau.
.hy 0
.SH SYNOPSIS
.B insmod
[\-fhkLmnpqrsSvVxXyYN] [\-e\ \fIpersist_name\fR] [\-o\ \fImodule_name\fR]
[\-O\ \fIblob_name\fR] [\-P\ \fIprefix\fR] \fImodule\fR
[\ \fBsymbol\fR=\fIvalue\fR\ ...\ ]
.SH DESCRIPTION
.B insmod
charge un module dans le noyau en cours d'utilisation.
.PP
.B insmod
essaie de lier un module dans le noyau en cours d'excution en rsolvant les noms
de symboles  partir de la table des symboles exports par le noyau.
.PP
Si le nom du fichier objet est donn sans rpertoire et sans extension,
.B insmod
cherchera le module dans quelques rpertoires par dfaut.
La variable d'environnement MODPATH peut surcharger ces rpertoires par dfaut.
Si un fichier de configuration comme /etc/modules.conf existe, il surchargera
les chemins indiqus dans \fBMODPATH\fP.
.PP
La variable d'environnement MODULECONF peut slectionner un fichier de
configuration diffrent de \fI/etc/modules.conf\fP (ou
\fI/etc/conf.modules\fR ( viter)).
Cette variable d'environnement prvaudra sur toutes les dfinitions prcdentes.
.PP
Quand la variable d'environnement
.B UNAME_MACHINE
est remplie, modutils l'utilisera  la place du champ "machine" de
l'appel-systme uname(). Ceci est surtout utile si vous compilez des modules
64 bits dans un espace utilisateur 32 bits ou
inversement\ ; remplissez
.B UNAME_MACHINE
avec le type de modules construits.
La version actuelle de modutils ne supporte pas la construction croise complte
de modules, elle est limite au choix entre 32 et 64 bits de l'architecture
hte.
.SS OPTIONS
.TP
\fB\-e\fR \fIpersist_name\fR, \fB\-\-persist\fR=\fIpersist_name\fR 
Indique o les donnes persistantes du modules doivent tre lues au chargement
et crite lorsque cette instance du module est dcharge. Cette option est
ignore silencieusement si le module n'a pas de donnes persistantes. Les
donnes persistantes ne sont lues par \fBinsmod\fR que si cette option est
prsente. Par dfaut \fBinsmod\fR ne traite pas les donnes persistantes.
.TP
.B ""
Sous forme raccourcie, \fB\-e\ ""\fR\ (une chane vide) est interprt par
\fBinsmod\fR comme la valeur de \fBpersistdir\fR dfinie dans
\fImodules.conf\fR, suivie du nom du fichier du module par rapport au chemin
de recherche o il a t trouv, en liminant toute extension
".gz", ".o" ou ".mod".  Si \fBmodules.conf\fR spcifie
"\fBpersistdir\ =\fR" (\fBpersistdir\fR est un champ vide) alors ce raccourci
est ignor silencieusement.  (Voir \fBmodules.conf\fR (5).)
.TP 
.BR \-f ", " \-\-force
Tentera de charger un module mme si la version du noyau en cours et celle pour
laquelle le module a t compil le module ne correspondent pas. Ceci ne
surcharge que la vrification du numro de noyau, et n'a aucun effet sur la
vrification des noms de symbole. Si le nom d'un symbole du module ne correspond
pas au noyau, il n'y a aucun moyen de forcer \fBinsmod\fP  le charger.
.TP
.BR \-h ", " \-\-help
Affiche une page d'aide et se termine.
.TP
.BR \-k ", " \-\-autoclean 
Marque le module pour auto-nettoyage. Ceci permettra 
\fBkerneld\fP(8) d'enlever les modules qui ne sont pas utiliss
durant une certaine priode - habituellement une minute.
.TP 
.BR \-L ", " \-\-lock 
Utiliser \fBflock\fR(2) pour empcher deux chargements simultans du mme module.
.TP
.BR \-m ", " \-\-map 
Affiche la carte de chargement, rendant plus facile le dbogage en cas de
panique du noyau.
.TP 
.BR \-n ", " \-\-noload
Fausse excution. Tout faire, mais ne rien charger dans le noyau. Avec option
\fB\-m\fR ou \fB\-O\fR, l'excution produira les fichiers carte ou blob.
Comme le module n'est pas charg, l'adresse relle du noyau est inconuue,
ainsi les fichiers utilisent une adresse de chargement arbitraire
0x12340000.
.TP
\fB\-o\fR \fImodule_name\fR, \fB\-\-name\fR=\fImodule_name\fR
Indique explicitement le nom du module, plutt que d'utiliser le celui dduit
du fichier objet.
.TP
\fB\-O\fR \fIblob_name\fR, \fB\-\-blob\fR=\fIblob_name\fR
Sauver le fichier objet dans \fIblob_name\fR. Le rsultat est un blob binaire
(pas d'en-tte ELF) montrant exactement ce qui est charg dans noyau
aprs manipulation et dplacemen des sections.
L' option \fB\-m\fR est recommande pour obtenir une carte de cet objet.
.TP
.BR \-p ", " \-\-probe
Vrifie si le module peut tre charg avec succs. Cela inclut la position du
fichier objet dans le chemin des modules, la vrification
des numros de versions, et la rsolution des commandes. Elle ne vrifie pas
les dplacements et ne produit pas de fichier blob.
.TP
\fB\-P\fR \fIprefix\fR, \fB\-\-prefix\fR=\fIprefix\fR
Cette option sert pour les modules avec numros de version, et les noyaux smp
ou bigmem, car ces modules ont un prfixe supplmentaire ajout aux noms des
symboles. Si le noyau a t construit avec les numros de versions pour les
symboles, alors \fBinsmodfP extraiera automatiquement le prfix de la dfinition
de "get_module_symbol" ou "inter_module_get", l'un des deux doit exister dans
tous les noyaux qui supportent les modules. Si le noyau n'a pas de version
pour les symboles, mais que le module en a, alors
l'utilisateur doit fournir l'option
.BR \-P .
.TP
.BR \-q ", " \-\-quiet
Ne pas afficher la listes des commandes non rsolues.
Ne pas signaler les problmes de numros de versions.
Les problmes ne seront visibles que dans le statut de sortie de \fBinsmod\fR.
.TP
.BR \-r ", " \-\-root
.TP
.B ""
Certains utilisateurs compilent les modules sans droits root et les installent
en tant root. Ceci risque de crer des modules n'appartenant pas  root, mme
si le rpertoire des modules est proprit du root.
Si un tel compte utilisateur est pirat, un intrus peut modifier ces modules
et les utiliser pour obtenir un accs root.
.TP
.B ""
Par dfaut, modutils rejettera les demandes d'utilisation d'un module qui
n'appartient  root. L'option \fB-r\fR supprimera l'erreur et autorisera le
chargement de module n'appartenant pas  root. \fBNote\ :\fR la valeur par
dfaut pour la vrification d'appartenance  root peut tre modifie dans
la configuration de modutils.
.TP
.I ""
\fBL'utilisation de -r ou la configuration "pas de vrification root" 
est un danger pour la scurit et est
dconseille.\fR
.TP
.BR \-s ", " \-\-syslog
Envoie les messages  \fBsyslog\fP(3) plutt que sur le terminal.
.TP
.BR \-S ", " \-\-kallsyms
Force le module charg  avoir des donnes \fBkallsyms\fR, mme si le noyau ne
le supporte pas. Cette option sert sur les petits systmes o le noyau est 
charg sans donnes \fBkallsyms\fR, mais que les modules ont besoin de
\fBkallsyms\fR pour le dbogage. Configuration par dfaut sur Red Hat Linux.
.TP
.BR \-v ", " \-\-verbose
Rends insmod plus volubile.
.TP
.BR \-V ", " \-\-version
Affiche le numro de version de \fBinsmod\fR.
.TP
.BR \-X ", " \-\-export "; " \-x ", " \-\-noexport
Respectivement, exporter ou non tous les symboles externes du module. La valeur
par dfaut est l'exportation des symboles. Cette noption n'est effective que
si le module n'exporte pas explicitement sa propre table de symbole,
ce qui est dconseill.
.TP
.BR \-Y ", " \-\-ksymoops "; " \-y ", " \-\-noksymoops
Respectivement ajoute ou non les symboles ksymoops  ksyms. Ces symboles servent
 ksymoops pour aider au dbogage si il y a un problme (Oops) dans le module.
La valeur par dfaut est de dfinir les symboles \fBksymoops\fR. Cette option
est indpendante de  \fB\-X\fR/\fB\-x\fR.
.TP
.B ""
Les symboles \fBksymoops\fR ajoutent environ 260 octets par module charg. 
moins d'tre vraiment  court de mmoire pour le noyau et de tenter de rduire
ksyms au minimum, utilisez la configuration par dfaut pour tre plus  l'aise
au dbogage. Les symboles \fBksymoops\fR sont ncessaires pour la sauvegarde
de donnes persistantes de modules.
.TP
.BR \-N ", " \-\-numeric-only
Ne vrifie que la partie numrique de la version du module par rapport  celle
du noyau, c'est--dire ignore le suffixe EXTRAVERSION pour savoir si le module
appartient au noyau.
Cette option est automatiquement active pour les noyaux  partir du 2.5, et
optionnel pour les prcdents.
.SS "PARAMTRES DES MODULES"
Des modules acceptent des paramtres au chargement pour adapter leur action.
Ces paramtres sont souvent des ports E/S et des numros d'IRQ variant d'une
machine  l'autre et ne peuvent tre dtermins  partir du matriel.
.PP
Dans les modules pour les noyau 2.0, tout symbole d'entier ou de pointeur
caractre peut tre manipul comme un paramtre et tre modifi. Depuis les
noyaux 2.1, les symboles sont explicitement marqus comme des paramtres, afin
que seules des donnes spcifiques soient modifiables. De plus le type est
indiqu pour vrifier la valeur fournie au chargement.
.PP
Pour les entiers, les valeurs peuvent tre en base 10, 8 ou 16, comme en C\ :
17, O21 ou Ox11. Les lments de tableau sont fournis en squence, spars par
des virgules. Des lments peuvent tre `sauts'
en omettant leur valeur.
.PP
Dans les modules 2.0, les valeurs ne dbutant pas par un nombre sont considres
comme des chanes. Depuis les 2.1, l'information sur le type de paramtre indique
si la valeur doit tre considre comme une chane. Si la valeur commence par
un guillemet
 (\fB"\fP),
.\" juste pour la coloration syntaxique : on ferme le guillemet prcdent.
 la chane est interprte comme en C, avec squence d'chappement
et le reste. Notez que depuis la ligne de commande du shell, les guillemets
doivent tre protgs pour viter leur interprtation par ce dernier.
.SS "SYMBOLES ET MODULES SOUS LICENCE GPL"
Depuis le noyau 2.4.10, les modules doivent avoir une chane indiquant leur
licence, dfinie par \fBMODULE_LICENSE()\fR. Plusieurs chanes sont reconnues
comme tant compatibles GPL, tout autre chane de licence ou l'absence de
licence est considre comme propritaire. Voir
\fIinclude/linux/module.h\fR pour une liste des chanes compatibles GPL.
.PP
Si le noyau supporte l'attribut \fI/proc/sys/kernel/tainted\fR, alors
\fBinsmod\fR fera un OU entre l'attribut et '1' au chargement d'un module sans
licence GPL. Un avertissement sera affich si le noyau supporte le mode tach
(tainted) et qu'on charge un module sans licence. Un avertissement est fourni
pour tout module ayant \fBMODULE_LICENSE()\fR non compatible GPL, mme sur les
noyaux anciens ne supportant pas l'entachement. Ceci limite les avertissements
quand les modutils rcents sont utiliss sur des noyaux anciens.
.PP
Le mode \fBinsmod\ \-f\fR (force) fera un OU entre l'attribut tainted et '2'
sur les noyaux supportant l'entachment. Ceci dclenche toujours un avertissement.
.PP
Certains dveloppeurs du noyau rclament que les symboles exports par leur code
ne soit utiliss que dans des modules avec une licence compatible GPL. Ces
symboles sont exports avec \fBEXPORT_SYMBOL_GPL\fR plutt qu'avec le normal
\fBEXPORT_SYMBOL\fR. Les symboles GPL-seulement exports par le noyau et d'autres
modules ne sont visibles que des modules ayant une licence compatible GPL. Ils
apparaissent dans \fI/proc/ksyms\fR avec le prfixe '\fBGPLONLY_\fR'.
\fBinsmod\fR ignore le prfixe \fBGPLONLY_\fR des symboles en chargeant un module
avec une licence compatible GPL, afin que le module fasse rfrence au nom du
symbole sans le prfixe. Les symboles GPL-seulement ne sont pas rendus
disponibles aux modules sans licence compatible GPL, ou sans licence
indique.
.SS "AIDE KSYMOOPS"
Pour aider au dbogage des problmes du noyau avec des modules, \fBinsmod\fP
ajoute par dfaut des symboles dans ksyms, voir l'option \fB-Y\fP.
Ces symboles dbutent avec \fB__insmod_modulename_\fP. Le \fImodulename\fP est
ncessaire pour rendre les symboles uniques, il est possible de charger le mme
objet plusieurs fois sous diffrents noms de modules.
Actuellement les commandes dfinies sont\ :
.TP
.B __insmod_modulename_Oobjectfile_Mmtime_Vversion
\fIobjectfile\fP est le nom du fichier depuis lequel l'objet a t charg.
Ceci garanti que ksymoops peut accder correctement au code de l'objet.
\fImtime\fP est l'horodatage en hexadcimal de la dernire modification du
fichier en hexadcimal, zro si \fBstat\fP(2) a chou. \fIversion\fP est la
version du noyau pour lequel le module a t compil, -1 si la version n'est
pas disponible. Le symbole _0 est l'adresse de dbut de l'en-tte du module.
.TP
.B __insmod_modulename_Ssectionname_Llength
Ce symbole apparat au dbut des sections ELF slectionnes,
actuellement .text, .rodata, .data .bss, et .sbss. Elle apparat seulement si la
section a une taille non-nulle. \fIsectionname\fP est le nom de la section ELF,
\fIlength\fP  est la longueur en dcimal de la section. Ces symboles aident
ksymoops  dterminer les adresses des sections dans lesquelles aucun symbole
n'est disponible.
.TP
.B __insmod_modulename_Ppersistent_filename
Cr par \fBinsmod\fR seulement si le module a un ou plusieurs paramtres qui
sont marqus comme donnes persistantes, et si un fichier de sauvegarde
(voir\fB\-e\fR, plus haut) est disponible.
.PP
L'autre problme avec le dbogage des problmes du noyau dans les modules est
que le contenu de \fI/proc/ksyms\fR et \fI/proc/modules\fR peut changer entre
l'instant du Oops et le moment o vous analysez le fichier journal. Pour pallier
ce problme, si le rpertoire \fI/var/log/ksymoops\fR existe alors \fBinsmod\fR
et \fBrmmod\fR copieront automatiquement \fI/proc/ksyms\fR et \fI/proc/modules\fR
dans \fI/var/log/ksymoops\fR avec le prfixe `date\ +%Y%m%d%H%M%S`.
L'administrateur systme peut indiquer  ksymoops quel fichier employer pour
dboguer un Oops. Il n'y a pas d'option pour dsactiver cette copie automatique,
si vous ne voulez pas qu'elle se produise, il ne faut pas crer de rpertoire
\fI/var/log/ksymoops\fR. Si le rpertoire existe, il doit appartenir  root,
avoir le mode 644 ou 600 et vous devriez lancer chaque jour le script suivant,
install comme \fBinsmod_clean_ksymoops\fR.
.PP
.ne 8
.nf
  #!/bin/sh
  # Supprime la sauvegarde de ksyms et des modules sans accs depuis 2 jours
  if [ -d /var/log/ksymoops ]
  then
	  set -e
	  # S'assurer qu'il y en a toujours au moins une version
	  d=`date +%Y%m%d%H%M%S`
	  cp -a /proc/ksyms /var/log/ksymoops/${d}.ksyms
	  cp -a /proc/modules /var/log/ksymoops/${d}.modules
	  find /var/log/ksymoops -type f -atime +2 -exec rm {} \\;
  fi
.SH "VOIR AUSSI"
.BR rmmod (8), 
.BR modprobe (8), 
.BR depmod (8), 
.BR lsmod (8),
.BR ksyms (8),
.BR modules (2),
.BR genksyms (8), 
.BR kerneld (8),
.BR ksymoops (noyau).
.SH HISTORIQUE
Le support des modules a t conu par Illustre Anonyme
.br
La version initiale pour Linux a t faite par Bas Laarhoven <bas@vimec.nl>
.br
La version 0.99.14 a t faite par Jon Tombs <jon@gtex02.us.es>
.br
Complte par Bjorn Ekwall <bj0rn@blox.se>
.br
Aide ELF originelle de Eric Youngdale <eric@aib.com>
.br
Rcrite pour 2.1.17 par Richard Henderson <rth@tamu.edu>
.br
Complte par Bjorn Ekwall <bj0rn@blox.se> pour modutils-2.2.*, Mars 1999
.br
Support pour ksymoops par Keith Owens <kaos@ocs.com.au>, Mai 1999
.br
Mainteneur actuel\ :  Keith Owens <kaos@ocs.com.au>.
.SH TRADUCTION
Jrome Signouret, 2000.
.br
Christophe Blaess, 2003.