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