man/modprobe.xml

   1 <?xml version='1.0'?>
   2 <!--*-nxml-*-->
   3 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   4         "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   5 <refentry id="modprobe">
   6   <refentryinfo>
   7     <title>modprobe</title>
   8     <productname>kmod</productname>
   9
  10     <authorgroup>
  11       <author>
  12         <contrib>Developer</contrib>
  13         <firstname>Jon</firstname>
  14         <surname>Masters</surname>
  15         <email>jcm@jonmasters.org</email>
  16       </author>
  17       <author>
  18         <contrib>Developer</contrib>
  19         <firstname>Robby</firstname>
  20         <surname>Workman</surname>
  21         <email>rworkman@slackware.com</email>
  22       </author>
  23       <author>
  24         <contrib>Developer</contrib>
  25         <firstname>Lucas</firstname>
  26         <surname>De Marchi</surname>
  27         <email>lucas.de.marchi@gmail.com</email>
  28       </author>
  29     </authorgroup>
  30   </refentryinfo>
  31
  32   <refmeta>
  33     <refentrytitle>modprobe</refentrytitle>
  34     <manvolnum>8</manvolnum>
  35   </refmeta>
  36
  37   <refnamediv>
  38     <refname>modprobe</refname>
  39     <refpurpose>Add and remove modules from the Linux Kernel</refpurpose>
  40   </refnamediv>
  41
  42   <refsynopsisdiv>
  43     <cmdsynopsis>
  44       <command>modprobe</command>
  45       <arg><option>-v</option></arg>
  46       <arg><option>-V</option></arg>
  47       <arg><option>-C <replaceable>config-file</replaceable></option></arg>
  48       <arg><option>-n</option></arg>
  49       <arg><option>-i</option></arg>
  50       <arg><option>-q</option></arg>
  51       <arg><option>-b</option></arg>
  52       <arg><replaceable>modulename</replaceable></arg>
  53       <arg rep='repeat'><option><replaceable>module parameters</replaceable></option></arg>
  54     </cmdsynopsis>
  55     <cmdsynopsis>
  56       <command>modprobe</command>
  57       <arg>-r</arg>
  58       <arg><option>-v</option></arg>
  59       <arg><option>-n</option></arg>
  60       <arg><option>-i</option></arg>
  61       <arg rep='repeat'><option><replaceable>modulename</replaceable></option></arg>
  62     </cmdsynopsis>
  63     <cmdsynopsis>
  64       <command>modprobe</command>
  65       <arg>-c</arg>
  66     </cmdsynopsis>
  67     <cmdsynopsis>
  68       <command>modprobe</command>
  69       <arg>--dump-modversions</arg> <arg><replaceable>filename</replaceable></arg>
  70     </cmdsynopsis>
  71   </refsynopsisdiv>
  72   <refsect1>
  73     <title>Description</title>
  74
  75     <para>
  76       <command>modprobe</command> intelligently adds or removes a
  77       module from the Linux kernel: note that for convenience, there
  78       is no difference between _ and - in module names (automatic
  79       underscore conversion is performed).
  80       <command>modprobe</command> looks in the module directory
  81       <filename>/lib/modules/`uname -r`</filename> for all
  82       the modules and other files, except for the optional
  83       configuration files in the
  84       <filename>/etc/modprobe.d</filename> directory
  85       (see <citerefentry>
  86         <refentrytitle>modprobe.d</refentrytitle><manvolnum>5</manvolnum>
  87       </citerefentry>). <command>modprobe</command> will also use module
  88       options specified on the kernel command line in the form of
  89       &lt;module&gt;.&lt;option&gt; and blacklists in the form of
  90       modprobe.blacklist=&lt;module&gt;.
  91     </para>
  92     <para>
  93       Note that unlike in 2.4 series Linux kernels (which are not supported
  94       by this tool) this version of <command>modprobe</command> does not
  95       do anything to the module itself: the work of resolving symbols
  96       and understanding parameters is done inside the kernel.  So
  97       module failure is sometimes accompanied by a kernel message: see
  98       <citerefentry>
  99         <refentrytitle>dmesg</refentrytitle><manvolnum>8</manvolnum>
 100       </citerefentry>.
 101     </para>
 102     <para>
 103       <command>modprobe</command> expects an up-to-date
 104       <filename>modules.dep.bin</filename> file as generated
 105       by the corresponding <command>depmod</command> utility shipped
 106       along with <command>modprobe</command> (see
 107       <citerefentry><refentrytitle>depmod</refentrytitle><manvolnum>8</manvolnum>
 108       </citerefentry>).  This file lists what other modules each
 109       module needs (if any), and <command>modprobe</command> uses this
 110       to add or remove these dependencies automatically.
 111     </para>
 112     <para>
 113       If any arguments are given after the
 114       <replaceable>modulename</replaceable>, they are passed to the
 115       kernel (in addition to any options listed in the configuration
 116       file).
 117     </para>
 118   </refsect1>
 119
 120   <refsect1><title>OPTIONS</title>
 121     <variablelist>
 122       <varlistentry>
 123         <term>
 124           <option>-a</option>
 125         </term>
 126         <term>
 127           <option>--all</option>
 128         </term>
 129         <listitem>
 130           <para>Insert all module names on the command line.</para>
 131         </listitem>
 132       </varlistentry>
 133       <varlistentry>
 134         <term>
 135           <option>-b</option>
 136         </term>
 137         <term>
 138           <option>--use-blacklist</option>
 139         </term>
 140         <listitem>
 141           <para>
 142             This option causes <command>modprobe</command> to apply the
 143             <command>blacklist</command> commands in the configuration files
 144             (if any) to module names as well.  It is usually used by
 145             <citerefentry>
 146               <refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum>
 147             </citerefentry>.
 148           </para>
 149         </listitem>
 150       </varlistentry>
 151       <varlistentry>
 152         <term>
 153           <option>-C</option>
 154         </term>
 155         <term>
 156           <option>--config</option>
 157         </term>
 158         <listitem>
 159           <para>This option overrides the default configuration directory
 160             (<filename>/etc/modprobe.d</filename>).
 161           </para>
 162           <para>
 163             This option is passed through <command>install</command>
 164             or <command>remove</command> commands to other
 165             <command>modprobe</command> commands in the
 166             MODPROBE_OPTIONS environment variable.
 167           </para>
 168         </listitem>
 169       </varlistentry>
 170       <varlistentry>
 171         <term>
 172           <option>-c</option>
 173         </term>
 174         <term>
 175           <option>--showconfig</option>
 176         </term>
 177         <listitem>
 178           <para>
 179             Dump out the effective configuration from the config directory and
 180             exit.
 181           </para>
 182         </listitem>
 183       </varlistentry>
 184       <varlistentry>
 185         <term>
 186           <option>--dump-modversions</option>
 187         </term>
 188         <listitem>
 189           <para>
 190             Print out a list of module versioning information required by a
 191             module. This option is commonly used by distributions in order to
 192             package up a Linux kernel module using module versioning deps.
 193           </para>
 194         </listitem>
 195       </varlistentry>
 196       <varlistentry>
 197         <term>
 198           <option>-d</option>
 199         </term>
 200         <term>
 201           <option>--dirname</option>
 202         </term>
 203         <listitem>
 204           <para>
 205             Root directory for modules, <filename>/</filename> by default.
 206           </para>
 207         </listitem>
 208       </varlistentry>
 209       <varlistentry>
 210         <term>
 211           <option>--first-time</option>
 212         </term>
 213         <listitem>
 214           <para>
 215             Normally, <command>modprobe</command> will succeed (and do
 216             nothing) if told to insert a module which is already
 217             present or to remove a module which isn't present.  This is
 218             ideal for simple scripts; however, more complicated scripts often
 219             want to know whether <command>modprobe</command> really
 220             did something: this option makes modprobe fail in the
 221             case that it actually didn't do anything.
 222           </para>
 223         </listitem>
 224       </varlistentry>
 225       <varlistentry>
 226         <term>
 227           <option>--force-vermagic</option>
 228         </term>
 229         <listitem>
 230           <para>
 231             Every module contains a small string containing important
 232             information, such as the kernel and compiler versions.  If a module
 233             fails to load and the kernel complains that the "version magic"
 234             doesn't match, you can use this option to remove it.  Naturally,
 235             this check is there for your protection, so using this option is
 236             dangerous unless you know what you're doing.
 237           </para>
 238           <para>
 239             This applies to any modules inserted: both the module (or alias) on
 240             the command line and any modules on which it depends.
 241           </para>
 242         </listitem>
 243       </varlistentry>
 244       <varlistentry>
 245         <term>
 246           <option>--force-modversion</option>
 247         </term>
 248         <listitem>
 249           <para>
 250             When modules are compiled with CONFIG_MODVERSIONS set, a section
 251             detailing the versions of every interfaced used by (or supplied by)
 252             the module is created.  If a module fails to load and the kernel
 253             complains that the module disagrees about a version of some
 254             interface, you can use "--force-modversion" to remove the version
 255             information altogether.  Naturally, this check is there for your
 256             protection, so using this option is dangerous unless you know what
 257             you're doing.
 258           </para>
 259           <para>
 260             This applies any modules inserted: both the module (or alias) on
 261             the command line and any modules on which it depends.
 262           </para>
 263         </listitem>
 264       </varlistentry>
 265       <varlistentry>
 266         <term>
 267           <option>-f</option>
 268         </term>
 269         <term>
 270           <option>--force</option>
 271         </term>
 272         <listitem>
 273           <para>
 274             Try to strip any versioning information from the module which might
 275             otherwise stop it from loading: this is the same as using both
 276             <option>--force-vermagic</option> and
 277             <option>--force-modversion</option>.  Naturally, these checks are
 278             there for your protection, so using this option is dangerous unless
 279             you know what you are doing.
 280           </para>
 281           <para>
 282             This applies to any modules inserted: both the module (or alias) on
 283             the command line and any modules it on which it depends.
 284           </para>
 285         </listitem>
 286       </varlistentry>
 287       <varlistentry>
 288         <term>
 289           <option>-i</option>
 290         </term>
 291         <term>
 292           <option>--ignore-install</option>
 293         </term>
 294         <term>
 295           <option>--ignore-remove</option>
 296         </term>
 297         <listitem>
 298           <para>
 299             This option causes <command>modprobe</command> to ignore
 300             <command>install</command> and <command>remove</command> commands
 301             in the configuration file (if any) for the module specified on the
 302             command line (any dependent modules are still subject to commands
 303             set for them in the configuration file). Both
 304             <command>install</command> and <command>remove</command> commands
 305             will currently be ignored when this option is used regardless of
 306             whether the request was more specifically made with only one or
 307             other (and not both) of <option>--ignore-install</option> or
 308             <option>--ignore-remove</option>.  See <citerefentry>
 309               <refentrytitle>modprobe.d</refentrytitle><manvolnum>5</manvolnum>
 310             </citerefentry>.
 311           </para>
 312         </listitem>
 313       </varlistentry>
 314       <varlistentry>
 315         <term>
 316           <option>-n</option>
 317         </term>
 318         <term>
 319           <option>--dry-run</option>
 320         </term>
 321         <term>
 322           <option>--show</option>
 323         </term>
 324         <listitem>
 325           <para>
 326             This option does everything but actually insert or delete the
 327             modules (or run the install or remove commands).  Combined with
 328             <option>-v</option>, it is useful for debugging problems. For
 329             historical reasons both <option>--dry-run</option> and
 330             <option>--show</option> actually mean the same thing and are
 331             interchangeable.
 332           </para>
 333         </listitem>
 334       </varlistentry>
 335       <varlistentry>
 336         <term>
 337           <option>-q</option>
 338         </term>
 339         <term>
 340           <option>--quiet</option>
 341         </term>
 342         <listitem>
 343           <para>
 344             With this flag, <command>modprobe</command> won't print an error
 345             message if you try to remove or insert a module it can't find (and
 346             isn't an alias or
 347             <command>install</command>/<command>remove</command> command).
 348             However, it will still return with a non-zero exit status. The
 349             kernel uses this to opportunistically probe for modules which might
 350             exist using request_module.
 351           </para>
 352         </listitem>
 353       </varlistentry>
 354       <varlistentry>
 355         <term>
 356           <option>-R</option>
 357         </term>
 358         <term>
 359           <option>--resolve-alias</option>
 360         </term>
 361         <listitem>
 362           <para>
 363             Print all module names matching an alias. This can be useful for
 364             debugging module alias problems.
 365           </para>
 366         </listitem>
 367       </varlistentry>
 368       <varlistentry>
 369         <term>
 370           <option>-r</option>
 371         </term>
 372         <term>
 373           <option>--remove</option>
 374         </term>
 375         <listitem>
 376           <para>
 377             This option causes <command>modprobe</command> to remove rather
 378             than insert a module.  If the modules it depends on are also
 379             unused, <command>modprobe</command> will try to remove them too.
 380             Unlike insertion, more than one module can be specified on the
 381             command line (it does not make sense to specify module parameters
 382             when removing modules).
 383           </para>
 384           <para>
 385             There is usually no reason to remove modules, but some buggy
 386             modules require it.  Your distribution kernel may not have been
 387             built to support removal of modules at all.
 388           </para>
 389         </listitem>
 390       </varlistentry>
 391       <varlistentry>
 392         <term>
 393           <option>-S</option>
 394         </term>
 395         <term>
 396           <option>--set-version</option>
 397         </term>
 398         <listitem>
 399           <para>
 400             Set the kernel version, rather than using
 401             <citerefentry><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 402             to decide on the kernel version (which dictates where to find the
 403             modules).
 404           </para>
 405         </listitem>
 406       </varlistentry>
 407       <varlistentry>
 408         <term>
 409           <option>--show-depends</option>
 410         </term>
 411         <listitem>
 412           <para>
 413             List the dependencies of a module (or alias), including the module
 414             itself.  This produces a (possibly empty) set of module filenames,
 415             one per line, each starting with "insmod" and is typically used by
 416             distributions to determine which modules to include when generating
 417             initrd/initramfs images.  <command>Install</command> commands which
 418             apply are shown prefixed by "install".  It does not run any of the
 419             install commands.  Note that
 420             <citerefentry><refentrytitle>modinfo</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 421             can be used to extract dependencies of a module from the module
 422             itself, but knows nothing of aliases or install commands.
 423           </para>
 424         </listitem>
 425       </varlistentry>
 426       <varlistentry>
 427         <term>
 428           <option>-s</option>
 429         </term>
 430         <term>
 431           <option>--syslog</option>
 432         </term>
 433         <listitem>
 434           <para>
 435             This option causes any error messages to go through the syslog
 436             mechanism (as LOG_DAEMON with level LOG_NOTICE) rather than to
 437             standard error.  This is also automatically enabled when stderr is
 438             unavailable.
 439           </para>
 440           <para>
 441             This option is passed through <command>install</command> or
 442             <command>remove</command> commands to other
 443             <command>modprobe</command> commands in the MODPROBE_OPTIONS
 444             environment variable.
 445           </para>
 446         </listitem>
 447       </varlistentry>
 448       <varlistentry>
 449         <term>
 450           <option>-V</option>
 451         </term>
 452         <term>
 453           <option>--version</option>
 454         </term>
 455         <listitem>
 456           <para>Show version of program and exit.</para>
 457         </listitem>
 458       </varlistentry>
 459       <varlistentry>
 460         <term>
 461           <option>-v</option>
 462         </term>
 463         <term>
 464           <option>--verbose</option>
 465         </term>
 466         <listitem>
 467           <para>
 468             Print messages about what the program is doing.  Usually
 469             <command>modprobe</command> only prints messages if something goes
 470             wrong.
 471           </para>
 472           <para>
 473             This option is passed through <command>install</command> or
 474             <command>remove</command> commands to other
 475             <command>modprobe</command> commands in the MODPROBE_OPTIONS
 476             environment variable.
 477           </para>
 478         </listitem>
 479       </varlistentry>
 480     </variablelist>
 481   </refsect1>
 482
 483   <refsect1><title>ENVIRONMENT</title>
 484     <para>
 485       The MODPROBE_OPTIONS environment variable can also be used to pass
 486       arguments to <command>modprobe</command>.
 487     </para>
 488   </refsect1>
 489
 490   <refsect1><title>COPYRIGHT</title>
 491     <para>
 492       This manual page originally Copyright 2002, Rusty Russell, IBM
 493       Corporation. Maintained by Jon Masters and others.
 494     </para>
 495   </refsect1>
 496
 497   <refsect1>
 498     <title>SEE ALSO</title>
 499     <para>
 500       <citerefentry>
 501         <refentrytitle>modprobe.d</refentrytitle><manvolnum>5</manvolnum>
 502       </citerefentry>,
 503       <citerefentry>
 504         <refentrytitle>insmod</refentrytitle><manvolnum>8</manvolnum>
 505       </citerefentry>,
 506       <citerefentry>
 507         <refentrytitle>rmmod</refentrytitle><manvolnum>8</manvolnum>
 508       </citerefentry>,
 509       <citerefentry>
 510         <refentrytitle>lsmod</refentrytitle><manvolnum>8</manvolnum>
 511       </citerefentry>,
 512       <citerefentry>
 513         <refentrytitle>modinfo</refentrytitle><manvolnum>8</manvolnum>
 514       </citerefentry>
 515       <citerefentry>
 516         <refentrytitle>depmod</refentrytitle><manvolnum>8</manvolnum>
 517       </citerefentry>
 518     </para>
 519   </refsect1>
 520 </refentry>