doc/modprobe.sgml

   1 <!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
   2   <!ENTITY debian  "<productname>Debian GNU/Linux</productname>">
   3   <!ENTITY docbook "<productname>DocBook</productname>">
   4   <!ENTITY sgml    "<abbrev>SGML</abbrev>">
   5 ]>
   6
   7 <!-- Stolen from manual page for docbook-to-man, DocBook source file
   8      (C) 1999 W. Borgert debacle@debian.org
   9
  10      $Id: docbook-to-man.sgml,v 1.8 2002/04/27 15:28:02 debacle Exp $ -->
  11
  12 <refentry>
  13   <refentryinfo>
  14     <address>
  15       <email>rusty@rustcorp.com.au</email>
  16     </address>
  17     <author>
  18       <firstname>Rusty</firstname>
  19       <surname>Russell</surname>
  20     </author>
  21     <date>2002-12-27</date>
  22   </refentryinfo>
  23   <refmeta>
  24     <refentrytitle>modprobe</refentrytitle>
  25     <manvolnum>8</manvolnum>
  26   </refmeta>
  27   <refnamediv>
  28     <refname>modprobe</refname> <refpurpose>program to add and remove modules from the Linux Kernel</refpurpose>
  29   </refnamediv>
  30   <refsynopsisdiv>
  31     <cmdsynopsis>
  32       <command>modprobe</command>
  33       <arg><option>-v</option></arg>
  34       <arg><option>-V</option></arg>
  35       <arg><option>-C <replaceable>config-file</replaceable></option></arg>
  36       <arg><option>-n</option></arg>
  37       <arg><option>-i</option></arg>
  38       <arg><option>-q</option></arg>
  39       <arg><option>-o</option> <replaceable>modulename</replaceable></arg>
  40       <arg><replaceable>modulename</replaceable></arg>
  41       <arg rep='repeat'><option><replaceable>module parameters</replaceable></option></arg>
  42     </cmdsynopsis>
  43     <cmdsynopsis>
  44       <command>modprobe</command>
  45       <arg>-r</arg>
  46       <arg><option>-v</option></arg>
  47       <arg><option>-n</option></arg>
  48       <arg><option>-i</option></arg>
  49       <arg rep='repeat'><option><replaceable>modulename</replaceable></option></arg>
  50     </cmdsynopsis>
  51     <cmdsynopsis>
  52       <command>modprobe</command>
  53       <arg>-l</arg>
  54       <arg>-t <replaceable>dirname</replaceable></arg>
  55       <arg><option><replaceable>wildcard</replaceable></option></arg>
  56     </cmdsynopsis>
  57     <cmdsynopsis>
  58       <command>modprobe</command>
  59       <arg>-c</arg>
  60     </cmdsynopsis>
  61     <cmdsynopsis>
  62       <command>modprobe</command>
  63       <arg>--dump-modversions</arg>
  64     </cmdsynopsis>
  65   </refsynopsisdiv>
  66   <refsect1>
  67     <title>Description</title>
  68
  69     <para>
  70       <command>modprobe</command> intelligently adds or removes a
  71       module from the Linux kernel: note that for convenience, there
  72       is no difference between _ and - in module names.
  73       <command>modprobe</command> looks in the module directory
  74       <filename>/lib/modules/`uname -r`</filename> for all
  75       the modules and other files, except for the optional
  76       <filename>/etc/modprobe.conf</filename> configuration file and
  77       <filename>/etc/modprobe.d</filename> directory
  78       (see <citerefentry>
  79         <refentrytitle>modprobe.conf</refentrytitle><manvolnum>5</manvolnum>
  80       </citerefentry>). <command>modprobe</command> will also use module
  81       options specified on the kernel command line in the form of
  82       &lt;module&gt;.&lt;option&gt;.
  83     </para>
  84     <para>
  85       Note that this version of <command>modprobe</command> does not
  86       do anything to the module itself: the work of resolving symbols
  87       and understanding parameters is done inside the kernel.  So
  88       module failure is sometimes accompanied by a kernel message: see
  89       <citerefentry>
  90         <refentrytitle>dmesg</refentrytitle><manvolnum>8</manvolnum>
  91       </citerefentry>.
  92     </para>
  93     <para>
  94       <command>modprobe</command> expects an up-to-date
  95       <filename>modules.dep</filename> file, as generated by
  96       <command>depmod</command> (see <citerefentry>
  97       <refentrytitle>depmod</refentrytitle><manvolnum>8</manvolnum>
  98       </citerefentry>).  This file lists what other modules each
  99       module needs (if any), and <command>modprobe</command> uses this
 100       to add or remove these dependencies automatically.  See
 101       <citerefentry>
 102       <refentrytitle>modules.dep</refentrytitle><manvolnum>5</manvolnum>
 103       </citerefentry>).
 104     </para>
 105     <para>
 106       If any arguments are given after the
 107       <replaceable>modulename</replaceable>, they are passed to the
 108       kernel (in addition to any options listed in the configuration
 109       file).
 110     </para>
 111   </refsect1>
 112   <refsect1>
 113     <title>OPTIONS</title>
 114     <variablelist>
 115       <varlistentry>
 116         <term><option>-v</option> <option>--verbose</option>
 117         </term>
 118         <listitem>
 119           <para>
 120             Print messages about what the program is doing.  Usually
 121             <command>modprobe</command> only prints messages if
 122             something goes wrong.
 123           </para>
 124           <para>
 125             This option is passed through <command>install</command>
 126             or <command>remove</command> commands to other
 127             <command>modprobe</command> commands in the
 128             MODPROBE_OPTIONS environment variable.
 129           </para>
 130         </listitem>
 131       </varlistentry>
 132       <varlistentry>
 133         <term><option>-C</option> <option>--config</option>
 134         </term>
 135         <listitem>
 136           <para>This option overrides the default configuration file
 137                 (<filename>/etc/modprobe.conf</filename> or
 138                 <filename>/etc/modprobe.d/</filename> if that isn't found).
 139           </para>
 140           <para>
 141             This option is passed through <command>install</command>
 142             or <command>remove</command> commands to other
 143             <command>modprobe</command> commands in the
 144             MODPROBE_OPTIONS environment variable.
 145           </para>
 146         </listitem>
 147       </varlistentry>
 148       <varlistentry>
 149         <term><option>-c</option> <option>--showconfig</option>
 150         </term>
 151         <listitem>
 152           <para>Dump out the configuration file and exit.
 153           </para>
 154         </listitem>
 155       </varlistentry>
 156       <varlistentry>
 157         <term><option>-n</option> <option>--dry-run</option>
 158         </term>
 159         <listitem>
 160           <para>This option does everything but actually insert or
 161                 delete the modules (or run the install or remove
 162                 commands).  Combined with <option>-v</option>, it is
 163                 useful for debugging problems.
 164           </para>
 165         </listitem>
 166       </varlistentry>
 167       <varlistentry>
 168         <term><option>-i</option> <option>--ignore-install</option> <option>--ignore-remove</option>
 169         </term>
 170         <listitem>
 171           <para>This option causes <command>modprobe</command> to
 172                 ignore <command>install</command> and
 173                 <command>remove</command> commands in the
 174                 configuration file (if any), for the module on the
 175                 command line (any dependent modules are still subject
 176                 to commands set for them in the configuration file).
 177                 See <citerefentry>
 178 <refentrytitle>modprobe.conf</refentrytitle><manvolnum>5</manvolnum>
 179 </citerefentry>.
 180           </para>
 181         </listitem>
 182       </varlistentry>
 183       <varlistentry>
 184         <term><option>-q</option> <option>--quiet</option>
 185         </term>
 186         <listitem>
 187           <para>
 188             Normally <command>modprobe</command> will report an error
 189             if you try to remove or insert a module it can't find (and
 190             isn't an alias or
 191             <command>install</command>/<command>remove</command>
 192             command).  With this flag, <command>modprobe</command>
 193             will simply ignore any bogus names (the kernel uses this
 194             to opportunistically probe for modules which might exist).
 195           </para>
 196         </listitem>
 197       </varlistentry>
 198       <varlistentry>
 199         <term><option>-r</option> <option>--remove</option>
 200         </term>
 201         <listitem>
 202           <para>
 203             This option causes <command>modprobe</command> to remove,
 204             rather than insert a module.  If the modules it depends on
 205             are also unused, <command>modprobe</command> will try to
 206             remove them, too.  Unlike insertion, more than one module
 207             can be specified on the command line (it does not make
 208             sense to specify module parameters when removing modules).
 209           </para>
 210           <para>
 211             There is usually no reason to remove modules, but some
 212             buggy modules require it.  Your kernel may not support
 213             removal of modules.
 214           </para>
 215         </listitem>
 216       </varlistentry>
 217       <varlistentry>
 218         <term><option>-w</option> <option>--wait</option>
 219         </term>
 220         <listitem>
 221           <para>
 222             This option is applicable only with the -r or --remove option.
 223             It causes modprobe to block in the kernel (within the kernel
 224             module handling code itself) waiting for the specified modules'
 225             reference count to reach zero. Default operation is for modprobe
 226             to operate like rmmod, which exits with EWOULDBLOCK if the
 227             modules reference count is non-zero.
 228           </para>
 229         </listitem>
 230       </varlistentry>
 231       <varlistentry>
 232         <term><option>-V</option> <option>--version</option>
 233         </term>
 234         <listitem>
 235           <para>Show version of program, and exit.  See below for caveats when run on older kernels.</para>
 236         </listitem>
 237       </varlistentry>
 238       <varlistentry>
 239         <term><option>-f</option> <option>--force</option>
 240         </term>
 241         <listitem>
 242           <para>
 243             Try to strip any versioning information from the module,
 244             which might otherwise stop it from loading: this is the
 245             same as using both <option>--force-vermagic</option> and
 246             <option>--force-modversion</option>.  Naturally, these
 247             checks are there for your protection, so using this option
 248             is dangerous.
 249          </para>
 250          <para>
 251             This applies to any modules inserted: both the module (or
 252             alias) on the command line, and any modules it depends on.
 253          </para>
 254         </listitem>
 255       </varlistentry>
 256       <varlistentry>
 257         <term><option>--force-vermagic</option>
 258         </term>
 259         <listitem>
 260           <para>
 261             Every module contains a small string containing important
 262             information, such as the kernel and compiler versions.  If
 263             a module fails to load and the kernel complains that the
 264             "version magic" doesn't match, you can use this option to
 265             remove it.  Naturally, this check is there for your
 266             protection, so this using option is dangerous.
 267          </para>
 268          <para>
 269             This applies to any modules inserted: both the module (or
 270             alias) on the command line, and any modules it depends on.
 271          </para>
 272         </listitem>
 273       </varlistentry>
 274       <varlistentry>
 275         <term><option>--force-modversion</option>
 276         </term>
 277         <listitem>
 278           <para>
 279             When modules are compiled with CONFIG_MODVERSIONS set, a
 280             section is created detailing the versions of every
 281             interface used by (or supplied by) the module.  If a
 282             module fails to load and the kernel complains that the
 283             module disagrees about a version of some interface, you
 284             can use "--force-modversion" to remove the version
 285             information altogether.  Naturally, this check is there
 286             for your protection, so using this option is dangerous.
 287          </para>
 288          <para>
 289             This applies any modules inserted: both the module (or
 290             alias) on the command line, and any modules it depends on.
 291          </para>
 292         </listitem>
 293       </varlistentry>
 294       <varlistentry>
 295         <term><option>-l</option> <option>--list</option>
 296         </term>
 297         <listitem>
 298           <para>List all modules matching the given wildcard (or "*"
 299                 if no wildcard is given).  This option is provided for
 300                 backwards compatibility: see
 301             <citerefentry>
 302               <refentrytitle>find</refentrytitle><manvolnum>1</manvolnum>
 303             </citerefentry> and
 304             <citerefentry>
 305               <refentrytitle>basename</refentrytitle><manvolnum>1</manvolnum>
 306             </citerefentry> for a more flexible alternative.
 307          </para>
 308         </listitem>
 309       </varlistentry>
 310       <varlistentry>
 311         <term><option>-a</option> <option>--all</option>
 312         </term>
 313         <listitem>
 314           <para>Insert all module names on the command line.
 315          </para>
 316         </listitem>
 317       </varlistentry>
 318       <varlistentry>
 319         <term><option>-t</option> <option>--type</option>
 320         </term>
 321         <listitem>
 322           <para>Restrict <option>-l</option> to modules
 323                 in directories matching the
 324                 <replaceable>dirname</replaceable> given.  This option
 325                 is provided for backwards compatibility: see
 326             <citerefentry>
 327               <refentrytitle>find</refentrytitle><manvolnum>1</manvolnum>
 328             </citerefentry>
 329             and
 330             <citerefentry>
 331               <refentrytitle>basename</refentrytitle><manvolnum>1</manvolnum>
 332             </citerefentry> or a more flexible alternative.
 333          </para>
 334         </listitem>
 335       </varlistentry>
 336       <varlistentry>
 337         <term><option>-s</option> <option>--syslog</option>
 338         </term>
 339         <listitem>
 340           <para>
 341             This option causes any error messages to go through the
 342             syslog mechanism (as LOG_DAEMON with level LOG_NOTICE)
 343             rather than to standard error.  This is also automatically
 344             enabled when stderr is unavailable.
 345           </para>
 346           <para>
 347             This option is passed through <command>install</command>
 348             or <command>remove</command> commands to other
 349             <command>modprobe</command> commands in the
 350             MODPROBE_OPTIONS environment variable.
 351           </para>
 352         </listitem>
 353       </varlistentry>
 354       <varlistentry>
 355         <term><option>--set-version</option>
 356         </term>
 357         <listitem>
 358           <para>
 359             Set the kernel version, rather than using
 360             <citerefentry><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry> to decide on the kernel version (which dictates where to
 361             find the modules).  This also disables backwards
 362             compatibility checks (so
 363             <citerefentry>
 364               <refentrytitle>modprobe.old</refentrytitle><manvolnum>8</manvolnum></citerefentry> will never be run).
 365           </para>
 366         </listitem>
 367       </varlistentry>
 368       <varlistentry>
 369         <term><option>--show-depends</option>
 370         </term>
 371         <listitem>
 372           <para>
 373             List the dependencies of a module (or alias), including
 374             the module itself.  This produces a (possibly empty) set
 375             of module filenames, one per line, each starting with
 376             "insmod".  Install commands which apply are shown prefixed by
 377             "install".  It does not run any of the install commands.  Note that
 378             <citerefentry><refentrytitle>modinfo</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 379             can be used to extract dependencies of a module from the
 380             module itself, but knows nothing of aliases or install commands.
 381           </para>
 382         </listitem>
 383       </varlistentry>
 384       <varlistentry>
 385         <term><option>-o</option> <option>--name</option>
 386         </term>
 387         <listitem>
 388           <para>
 389             This option tries to rename the module which is being
 390             inserted into the kernel.  Some testing modules can
 391             usefully be inserted multiple times, but the kernel
 392             refuses to have two modules of the same name.  Normally,
 393             modules should not require multiple insertions, as that
 394             would make them useless if there were no module support.
 395           </para>
 396         </listitem>
 397       </varlistentry>
 398       <varlistentry>
 399         <term><option>--first-time</option>
 400         </term>
 401         <listitem>
 402           <para>
 403             Normally, <command>modprobe</command> will succeed (and do
 404             nothing) if told to insert a module which is already
 405             present, or remove a module which isn't present.  This is
 406             backwards compatible with the modutils, and ideal for
 407             simple scripts.  However, more complicated scripts often
 408             want to know whether <command>modprobe</command> really
 409             did something: this option makes modprobe fail for that
 410             case.
 411           </para>
 412         </listitem>
 413       </varlistentry>
 414       <varlistentry>
 415         <term><option>--dump-modversions</option>
 416         </term>
 417         <listitem>
 418           <para>
 419             Print out a list of module versioning information required by a
 420             module. This option is commonly used by distributions in order to
 421             package up a Linuxx kernel module using module versioning deps.
 422           </para>
 423         </listitem>
 424       </varlistentry>
 425       <varlistentry>
 426         <term><option>--use-blacklist</option>
 427         </term>
 428         <listitem>
 429           <para>
 430             This option causes <command>modprobe</command> to apply the
 431             <command>blacklist</command> commands in the configuration file (if
 432             any) to module names as well.  It is usually used by <citerefentry>
 433             <refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum>
 434             </citerefentry>.
 435           </para>
 436         </listitem>
 437       </varlistentry>
 438     </variablelist>
 439   </refsect1>
 440   <refsect1>
 441     <title>BACKWARDS COMPATIBILITY</title>
 442
 443     <para>
 444       This version of <command>modprobe</command> is for kernels
 445       <literal>2.5.48</literal> and above.  If it detects a kernel
 446       with support for old-style modules (for which much of the work
 447       was done in userspace), it will attempt to run
 448       <command>modprobe.old</command> in its place, so it is
 449       completely transparent to the user.
 450     </para>
 451   </refsect1>
 452   <refsect1>
 453     <title>ENVIRONMENT</title>
 454     <para>
 455       The MODPROBE_OPTIONS environment variable can also be used to
 456       pass arguments to <command>modprobe</command>.
 457     </para>
 458   </refsect1>
 459   <refsect1>
 460     <title>COPYRIGHT</title>
 461     <para>
 462       This manual page Copyright 2002, Rusty Russell, IBM Corporation.
 463     </para>
 464   </refsect1>
 465   <refsect1>
 466     <title>SEE ALSO</title>
 467     <para>
 468       <citerefentry>
 469         <refentrytitle>modprobe.conf</refentrytitle><manvolnum>5</manvolnum>
 470       </citerefentry>,
 471       <citerefentry>
 472         <refentrytitle>lsmod</refentrytitle><manvolnum>8</manvolnum>
 473       </citerefentry>,
 474       <citerefentry>
 475         <refentrytitle>modprobe.old</refentrytitle><manvolnum>8</manvolnum>
 476       </citerefentry>
 477     </para>
 478   </refsect1>
 479 </refentry>
 480
 481 <!-- Keep this comment at the end of the file
 482 Local variables:
 483 mode: sgml
 484 sgml-omittag:t
 485 sgml-shorttag:t
 486 sgml-minimize-attributes:nil
 487 sgml-always-quote-attributes:t
 488 sgml-indent-step:2
 489 sgml-indent-data:t
 490 sgml-parent-document:nil
 491 sgml-default-dtd-file:nil
 492 sgml-exposed-tags:nil
 493 sgml-local-catalogs:nil
 494 sgml-local-ecat-files:nil
 495 End:
 496 -->