INSMOD(8)

NOM
insmod - Charger des modules dans le noyau

SYNOPSIS
insmod [-fhkLmnpqrsSvVxXyYN] [-e persist_name] [-o module_name] [-O blob_name] [-P prefix] module [ symbol=value ... ]

DESCRIPTION
insmod charge un module dans le noyau en cours d'utilisation.

insmod essaie de lier un module dans le noyau en cours d'exécution en résolvant les noms de symboles à partir de la table des symboles exportés par le noyau.

Si le nom du fichier objet est donné sans répertoire ni extension, insmod cherchera le module dans quelques répertoires par défaut. La variable d'environnement MODPATH peut surcharger ces répertoires par défaut. Si un fichier de configuration comme /etc/modules.conf existe, il surchargera les chemins indiqués dans MODPATH.

La variable d'environnement MODULECONF peut sélectionner un fichier de configuration différent de /etc/modules.conf (ou /etc/conf.modules (obsolète)). Cette variable d'environnement prévaudra sur toutes les définitions précédentes.

Quand la variable d'environnement UNAME_MACHINE est remplie, modutils l'utilisera à la place du champ « machine » de l'appel système uname(2). Ceci est surtout utile si vous compilez des modules 64 bits dans un espace utilisateur 32 bits ou inversement ; remplissez UNAME_MACHINE avec le type de modules construits. La version actuelle de modutils ne supporte pas la construction croisée complète de modules, elle est limitée au choix entre 32 et 64 bits de l'architecture hôte.

  OPTIONS

-e persist_name, --persist=persist_name
    Indique où les données persistantes du module doivent être lues au chargement et écrites lorsque cette instance du module est déchargée. Cette option est ignorée silencieusement si le module n'a pas de données persistantes. Les données persistantes ne sont lues par insmod que si cette option est présente. Par défaut, insmod ne traite pas les données persistantes.

    Sous forme raccourcie, -e "" (une chaîne vide) est interprété par insmod comme la valeur de persistdir définie dans modules.conf, 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 modules.conf spécifie « persistdir = » (persistdir est un champ vide), alors ce raccourci est ignoré silencieusement. (Voir modules.conf (5).)

-f, --force
    Tentera de charger un module, même 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 vérification du numéro de noyau, et n'a aucun effet sur la vérification 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 insmod à le charger.

-h, --help
    Affiche un résumé des options et se termine.

-k, --autoclean
    Marque le module pour auto-nettoyage. Ceci permettra à kerneld(8) d'enlever les modules qui ne sont pas utilisés durant une certaine période - habituellement une minute.

-L, --lock
    Utiliser flock(2) pour empêcher deux chargements simultanés du même module.

-m, --map
    Affiche la carte de chargement, rendant plus facile le débogage en cas de panique du noyau.

-n, --noload
    Fausse exécution. Tout faire, mais ne rien charger dans le noyau. Avec l'option -m ou -O, l'exécution produira les fichiers carte ou blob. Comme le module n'est pas chargé, l'adresse réelle du noyau est inconnue. Ainsi, les fichiers utilisent une adresse de chargement arbitraire 0x12340000.

-o module_name, --name=module_name
    Indiquer explicitement le nom du module, plutôt que d'utiliser celui déduit du fichier objet.

-O blob_name, --blob=blob_name
    Sauver le fichier objet dans blob_name. Le résultat est un bloc binaire (pas d'en-tête ELF) montrant exactement ce qui est chargé dans le noyau après manipulation et déplacement des sections. L'option -m est recommandée pour obtenir une carte de cet objet.

-p, --probe
    Vérifier si le module peut être chargé avec succès. Cela inclut la position du fichier objet dans le chemin des modules, la vérification des numéros de versions, et la résolution des commandes. Elle ne vérifie pas les déplacements et ne produit pas de fichier blob.

-P prefix, --prefix=prefix
    Cette option sert pour les modules avec numéros de version, et les noyaux smp ou bigmem, car ces modules ont un préfixe supplémentaire ajouté aux noms des symboles. Si le noyau a été construit avec les numéros de versions pour les symboles, alors insmodfP extrairera automatiquement le préfixe de la définition 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 -P.

-q, --quiet
    Ne pas afficher la liste des commandes non résolues. Ne pas signaler les problèmes de numéros de versions. Les problèmes ne seront visibles que dans le statut de sortie de insmod.

-r, --root

    Certains utilisateurs compilent les modules sans droits root et les installent en étant root. Ceci risque de créer des modules n'appartenant pas à root, même si le répertoire des modules est propriété du root. Si un tel compte utilisateur est piraté, un intrus peut modifier ces modules et les utiliser pour obtenir un accès root.

    Par défaut, modutils rejettera les demandes d'utilisation d'un module qui n'appartient pas à root. L'option -r supprimera l'erreur et autorisera le chargement de module n'appartenant pas à root. Note : la valeur par défaut pour la vérification d'appartenance à root peut être modifiée dans la configuration de modutils.

    L'utilisation de -r ou la configuration « pas de vérification root » est un danger pour la sécurité et est déconseillée.

-s, --syslog
    Envoie les messages à syslog(3) plutôt que sur le terminal.

-S, --kallsyms
    Force le module chargé à avoir des données kallsyms, même si le noyau ne le supporte pas. Cette option sert sur les petits systèmes où le noyau est chargé sans données kallsyms, mais que les modules ont besoin de kallsyms pour le débogage. -v, --verbose Rend insmod plus volubile.

-V, --version
    Affiche le numéro de version de insmod.

-X, --export; -x, --noexport
    Respectivement, exporter ou non tous les symboles externes du module. La valeur par défaut est l'exportation des symboles. Cette option n'est effective que si le module n'exporte pas explicitement sa propre table de symboles, ce qui est déconseillé.

-Y, --ksymoops; -y, --noksymoops
    Respectivement, ajoute ou non les symboles ksymoops à ksyms. Ces symboles servent à ksymoops pour aider au débogage s'il y a un problème (Oops) dans le module. La valeur par défaut est de définir les symboles ksymoops. Cette option est indépendante de -X/-x.

    Les symboles ksymoops ajoutent environ 260 octets par module chargé. À moins d'être vraiment à court de mémoire pour le noyau et de tenter de réduire ksyms au minimum, utilisez la configuration par défaut pour être plus à l'aise au débogage. Les symboles ksymoops sont nécessaires pour la sauvegarde de données persistantes de modules.

-N, --numeric-only
    Ne vérifie que la partie numérique de la version du module par rapport à celle du noyau, c.-à-d. 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 précédents.

  PARAMÈTRES DES MODULES
Des modules acceptent des paramètres au chargement pour adapter leur action. Ces paramètres sont souvent des ports d'entrées-sorties et des numéros d'IRQ variant d'une machine à l'autre et ne peuvent être déterminés à partir du matériel.

Dans les modules pour les noyau 2.0, tout symbole d'entier ou de pointeur caractère peut être manipulé comme un paramètre et être modifié. Depuis les noyaux 2.1, les symboles sont explicitement marqués comme des paramètres, afin que seules des données spécifiques soient modifiables. De plus, le type est indiqué pour vérifier la valeur fournie au chargement.

Pour les entiers, les valeurs peuvent être en base 10, 8 ou 16, comme en C : 17, O21 ou Ox11. Les éléments de tableau sont fournis en séquence, séparés par des virgules. Des éléments peuvent être « sautés » en omettant leur valeur.

Dans les modules 2.0, les valeurs ne débutant pas par un nombre sont considérées comme des chaînes. Depuis les 2.1, l'information sur le type de paramètre indique si la valeur doit être considérée comme une chaîne. Si la valeur commence par un guillemet
 ("), la chaîne est interprétée comme en C, avec séquence d'échappement et le reste. Notez que depuis la ligne de commande du shell, les guillemets doivent être protégés pour éviter leur interprétation par ce dernier.

  SYMBOLES ET MODULES SOUS LICENCE GPL
Depuis le noyau 2.4.10, les modules doivent avoir une chaîne indiquant leur licence, définie par MODULE_LICENSE(). Plusieurs chaînes sont reconnues comme étant compatibles GPL, tout autre chaîne de licence ou l'absence de licence est considérée comme propriétaire. Voir include/linux/module.h pour une liste des chaînes compatibles GPL.

Si le noyau supporte l'attribut /proc/sys/kernel/tainted, alors insmod 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 tâché (tainted) et qu'on charge un module sans licence. Un avertissement est fourni pour tout module ayant MODULE_LICENSE() non compatible GPL, même sur les noyaux anciens ne supportant pas l'entâchement. Ceci limite les avertissements quand les modutils récents sont utilisés sur des noyaux anciens.

Le mode insmod -f (force) fera un OU entre l'attribut tainted et « 2 » sur les noyaux supportant l'entâchement. Ceci déclenche toujours un avertissement.

Certains développeurs du noyau réclament que les symboles exportés par leur code ne soit utilisés que dans des modules avec une licence compatible GPL. Ces symboles sont exportés avec EXPORT_SYMBOL_GPL plutôt qu'avec le normal EXPORT_SYMBOL. Les symboles GPL-seulement exportés par le noyau et d'autres modules ne sont visibles que des modules ayant une licence compatible GPL. Ils apparaissent dans /proc/ksyms avec le préfixe « GPLONLY_ ». insmod ignore le préfixe GPLONLY_ des symboles en chargeant un module avec une licence compatible GPL, afin que le module fasse référence au nom du symbole sans le préfixe. Les symboles GPL-seulement ne sont pas rendus disponibles aux modules sans licence compatible GPL, ou sans licence indiquée.

  AIDE KSYMOOPS
Pour aider au débogage des problèmes du noyau avec des modules, insmod ajoute par défaut des symboles dans ksyms, voir l'option -Y. Ces symboles débutent avec __insmod_modulename_. Le modulename est nécessaire pour rendre les symboles uniques, il est possible de charger le même objet plusieurs fois sous différents noms de modules. Actuellement, les commandes définies sont :

__insmod_modulename_Oobjectfile_Mmtime_Vversion
    objectfile est le nom du fichier depuis lequel l'objet a été chargé. Ceci garanti que ksymoops peut accéder correctement au code de l'objet. mtime est l'horodatage en hexadécimal de la dernière modification du fichier en hexadécimal, zéro si stat(2) a échoué. version 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 début de l'en-tête du module.

__insmod_modulename_Ssectionname_Llength
    Ce symbole apparaît au début des sections ELF sélectionnées, actuellement .text, .rodata, .data .bss, et .sbss. Elle apparaît seulement si la section a une taille non-nulle. sectionname est le nom de la section ELF, length est la longueur en décimal de la section. Ces symboles aident ksymoops à déterminer les adresses des sections dans lesquelles aucun symbole n'est disponible.

__insmod_modulename_Ppersistent_filename
    Créé par insmod seulement si le module a un ou plusieurs paramètres qui sont marqués comme données persistantes, et si un fichier de sauvegarde (voir -e, plus haut) est disponible.

L'autre problème avec le débogage des problèmes du noyau dans les modules est que le contenu de /proc/ksyms et /proc/modules peut changer entre l'instant du Oops et le moment où vous analysez le fichier journal. Pour pallier ce problème, si le répertoire /var/log/ksymoops existe alors insmod et rmmod copieront automatiquement /proc/ksyms et /proc/modules dans /var/log/ksymoops avec le préfixe « date +%Y%m%d%H%M%S ». L'administrateur système peut indiquer à ksymoops quel fichier employer pour déboguer un Oops. Il n'y a pas d'option pour désactiver cette copie automatique. Si vous ne voulez pas qu'elle se produise, il ne faut pas créer de répertoire /var/log/ksymoops. Si le répertoire existe, il doit appartenir à root, avoir le mode 644 ou 600 et vous devriez lancer chaque jour le script suivant, installé comme insmod_clean_ksymoops.

  #!/bin/sh
  # Supprime la sauvegarde de ksyms et des modules sans accès 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

VERSIONS

  Historique
Le support des modules a été conçu par un illustre inconnu.
La version initiale pour Linux a été faite par Bas Laarhoven <bas@vimec.nl>
La version 0.99.14 a été faite par Jon Tombs <jon@gtex02.us.es>
Complétée par Bjorn Ekwall <bj0rn@blox.se>
Aide ELF originelle de Eric Youngdale <eric@aib.com>
Réécrite pour 2.1.17 par Richard Henderson <rth@tamu.edu>
Complétée par Bjorn Ekwall <bj0rn@blox.se> pour modutils-2.2.*, Mars 1999
Support pour ksymoops par Keith Owens <kaos@ocs.com.au>, Mai 1999
Mainteneur actuel : Keith Owens <kaos@ocs.com.au>.

VOIR AUSSI
rmmod(8), modprobe(8), depmod(8), lsmod(8), ksyms(8), modules(2), genksyms(8), kerneld(8), ksymoops(noyau).

TRADUCTION

Ce document est une traduction réalisée par Jérome Signouret en 2000 et révisée le 19 novembre 2007.

L'équipe de traduction a fait le maximum pour réaliser une adaptation française de qualité. La version anglaise la plus à jour de ce document est toujours consultable via la commande : « LANG=C man 8 insmod ». N'hésitez pas à signaler à l'auteur ou au traducteur, selon le cas, toute erreur dans cette page de manuel.