man/modprobe.8.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>@MODULE_DIRECTORY@/`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     <para>
 119       When loading modules, <replaceable>modulename</replaceable> can also
 120       be a path to the module. If the path is relative, it must
 121       explicitly start with "./". Note that this may fail when using a
 122       path to a module with dependencies not matching the installed depmod
 123       database.
 124     </para>
 125   </refsect1>
 126
 127   <refsect1><title>OPTIONS</title>
 128     <variablelist>
 129       <varlistentry>
 130         <term>
 131           <option>-a</option>
 132         </term>
 133         <term>
 134           <option>--all</option>
 135         </term>
 136         <listitem>
 137           <para>Insert all module names on the command line.</para>
 138         </listitem>
 139       </varlistentry>
 140       <varlistentry>
 141         <term>
 142           <option>-b</option>
 143         </term>
 144         <term>
 145           <option>--use-blacklist</option>
 146         </term>
 147         <listitem>
 148           <para>
 149             This option causes <command>modprobe</command> to apply the
 150             <command>blacklist</command> commands in the configuration files
 151             (if any) to module names as well.  It is usually used by
 152             <citerefentry>
 153               <refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum>
 154             </citerefentry>.
 155           </para>
 156         </listitem>
 157       </varlistentry>
 158       <varlistentry>
 159         <term>
 160           <option>-C</option>
 161         </term>
 162         <term>
 163           <option>--config</option>
 164         </term>
 165         <listitem>
 166           <para>This option overrides the default configuration directory
 167             (<filename>/etc/modprobe.d</filename>).
 168           </para>
 169           <para>
 170             This option is passed through <command>install</command>
 171             or <command>remove</command> commands to other
 172             <command>modprobe</command> commands in the
 173             MODPROBE_OPTIONS environment variable.
 174           </para>
 175         </listitem>
 176       </varlistentry>
 177       <varlistentry>
 178         <term>
 179           <option>-c</option>
 180         </term>
 181         <term>
 182           <option>--showconfig</option>
 183         </term>
 184         <listitem>
 185           <para>
 186             Dump out the effective configuration from the config directory and
 187             exit.
 188           </para>
 189         </listitem>
 190       </varlistentry>
 191       <varlistentry>
 192         <term>
 193           <option>--dump-modversions</option>
 194         </term>
 195         <listitem>
 196           <para>
 197             Print out a list of module versioning information required by a
 198             module. This option is commonly used by distributions in order to
 199             package up a Linux kernel module using module versioning deps.
 200           </para>
 201         </listitem>
 202       </varlistentry>
 203       <varlistentry>
 204         <term>
 205           <option>-d</option>
 206         </term>
 207         <term>
 208           <option>--dirname</option>
 209         </term>
 210         <listitem>
 211           <para>
 212             Root directory for modules, <filename>/</filename> by default.
 213           </para>
 214         </listitem>
 215       </varlistentry>
 216       <varlistentry>
 217         <term>
 218           <option>--first-time</option>
 219         </term>
 220         <listitem>
 221           <para>
 222             Normally, <command>modprobe</command> will succeed (and do
 223             nothing) if told to insert a module which is already
 224             present or to remove a module which isn't present.  This is
 225             ideal for simple scripts; however, more complicated scripts often
 226             want to know whether <command>modprobe</command> really
 227             did something: this option makes modprobe fail in the
 228             case that it actually didn't do anything.
 229           </para>
 230         </listitem>
 231       </varlistentry>
 232       <varlistentry>
 233         <term>
 234           <option>--force-vermagic</option>
 235         </term>
 236         <listitem>
 237           <para>
 238             Every module contains a small string containing important
 239             information, such as the kernel and compiler versions.  If a module
 240             fails to load and the kernel complains that the "version magic"
 241             doesn't match, you can use this option to remove it.  Naturally,
 242             this check is there for your protection, so using this option is
 243             dangerous unless you know what you're doing.
 244           </para>
 245           <para>
 246             This applies to any modules inserted: both the module (or alias) on
 247             the command line and any modules on which it depends.
 248           </para>
 249         </listitem>
 250       </varlistentry>
 251       <varlistentry>
 252         <term>
 253           <option>--force-modversion</option>
 254         </term>
 255         <listitem>
 256           <para>
 257             When modules are compiled with CONFIG_MODVERSIONS set, a section
 258             detailing the versions of every interfaced used by (or supplied by)
 259             the module is created.  If a module fails to load and the kernel
 260             complains that the module disagrees about a version of some
 261             interface, you can use "--force-modversion" to remove the version
 262             information altogether.  Naturally, this check is there for your
 263             protection, so using this option is dangerous unless you know what
 264             you're doing.
 265           </para>
 266           <para>
 267             This applies any modules inserted: both the module (or alias) on
 268             the command line and any modules on which it depends.
 269           </para>
 270         </listitem>
 271       </varlistentry>
 272       <varlistentry>
 273         <term>
 274           <option>-f</option>
 275         </term>
 276         <term>
 277           <option>--force</option>
 278         </term>
 279         <listitem>
 280           <para>
 281             Try to strip any versioning information from the module which might
 282             otherwise stop it from loading: this is the same as using both
 283             <option>--force-vermagic</option> and
 284             <option>--force-modversion</option>.  Naturally, these checks are
 285             there for your protection, so using this option is dangerous unless
 286             you know what you are doing.
 287           </para>
 288           <para>
 289             This applies to any modules inserted: both the module (or alias) on
 290             the command line and any modules it on which it depends.
 291           </para>
 292         </listitem>
 293       </varlistentry>
 294       <varlistentry>
 295         <term>
 296           <option>-i</option>
 297         </term>
 298         <term>
 299           <option>--ignore-install</option>
 300         </term>
 301         <term>
 302           <option>--ignore-remove</option>
 303         </term>
 304         <listitem>
 305           <para>
 306             This option causes <command>modprobe</command> to ignore
 307             <command>install</command> and <command>remove</command> commands
 308             in the configuration file (if any) for the module specified on the
 309             command line (any dependent modules are still subject to commands
 310             set for them in the configuration file). Both
 311             <command>install</command> and <command>remove</command> commands
 312             will currently be ignored when this option is used regardless of
 313             whether the request was more specifically made with only one or
 314             other (and not both) of <option>--ignore-install</option> or
 315             <option>--ignore-remove</option>.  See <citerefentry>
 316               <refentrytitle>modprobe.d</refentrytitle><manvolnum>5</manvolnum>
 317             </citerefentry>.
 318           </para>
 319         </listitem>
 320       </varlistentry>
 321       <varlistentry>
 322         <term>
 323           <option>-n</option>
 324         </term>
 325         <term>
 326           <option>--dry-run</option>
 327         </term>
 328         <term>
 329           <option>--show</option>
 330         </term>
 331         <listitem>
 332           <para>
 333             This option does everything but actually insert or delete the
 334             modules (or run the install or remove commands).  Combined with
 335             <option>-v</option>, it is useful for debugging problems. For
 336             historical reasons both <option>--dry-run</option> and
 337             <option>--show</option> actually mean the same thing and are
 338             interchangeable.
 339           </para>
 340         </listitem>
 341       </varlistentry>
 342       <varlistentry>
 343         <term>
 344           <option>-q</option>
 345         </term>
 346         <term>
 347           <option>--quiet</option>
 348         </term>
 349         <listitem>
 350           <para>
 351             With this flag, <command>modprobe</command> won't print an error
 352             message if you try to remove or insert a module it can't find (and
 353             isn't an alias or
 354             <command>install</command>/<command>remove</command> command).
 355             However, it will still return with a non-zero exit status. The
 356             kernel uses this to opportunistically probe for modules which might
 357             exist using request_module.
 358           </para>
 359         </listitem>
 360       </varlistentry>
 361       <varlistentry>
 362         <term>
 363           <option>-R</option>
 364         </term>
 365         <term>
 366           <option>--resolve-alias</option>
 367         </term>
 368         <listitem>
 369           <para>
 370             Print all module names matching an alias. This can be useful for
 371             debugging module alias problems.
 372           </para>
 373         </listitem>
 374       </varlistentry>
 375       <varlistentry>
 376         <term>
 377           <option>-r</option>
 378         </term>
 379         <term>
 380           <option>--remove</option>
 381         </term>
 382         <listitem>
 383           <para>
 384             This option causes <command>modprobe</command> to remove rather
 385             than insert a module.  If the modules it depends on are also
 386             unused, <command>modprobe</command> will try to remove them too.
 387             Unlike insertion, more than one module can be specified on the
 388             command line (it does not make sense to specify module parameters
 389             when removing modules).
 390           </para>
 391           <para>
 392             There is usually no reason to remove modules, but some buggy
 393             modules require it.  Your distribution kernel may not have been
 394             built to support removal of modules at all.
 395           </para>
 396         </listitem>
 397       </varlistentry>
 398       <varlistentry>
 399         <term>
 400           <option>-w</option>
 401         </term>
 402         <term>
 403         <option>--wait=</option>TIMEOUT_MSEC
 404         </term>
 405         <listitem>
 406           <para>
 407             This option causes <command>modprobe -r</command> to continue trying to
 408             remove a module if it fails due to the module being busy, i.e. its refcount
 409             is not 0 at the time the call is made. Modprobe tries to remove the module
 410             with an incremental sleep time between each tentative up until the maximum
 411             wait time in milliseconds passed in this option.
 412           </para>
 413         </listitem>
 414       </varlistentry>
 415       <varlistentry>
 416         <term>
 417           <option>-S</option>
 418         </term>
 419         <term>
 420           <option>--set-version</option>
 421         </term>
 422         <listitem>
 423           <para>
 424             Set the kernel version, rather than using
 425             <citerefentry><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 426             to decide on the kernel version (which dictates where to find the
 427             modules).
 428           </para>
 429         </listitem>
 430       </varlistentry>
 431       <varlistentry>
 432         <term>
 433           <option>--show-depends</option>
 434         </term>
 435         <listitem>
 436           <para>
 437             List the dependencies of a module (or alias), including the module
 438             itself.  This produces a (possibly empty) set of module filenames,
 439             one per line, each starting with "insmod" and is typically used by
 440             distributions to determine which modules to include when generating
 441             initrd/initramfs images.  <command>Install</command> commands which
 442             apply are shown prefixed by "install".  It does not run any of the
 443             install commands.  Note that
 444             <citerefentry><refentrytitle>modinfo</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 445             can be used to extract dependencies of a module from the module
 446             itself, but knows nothing of aliases or install commands.
 447           </para>
 448         </listitem>
 449       </varlistentry>
 450       <varlistentry>
 451         <term>
 452           <option>-s</option>
 453         </term>
 454         <term>
 455           <option>--syslog</option>
 456         </term>
 457         <listitem>
 458           <para>
 459             This option causes any error messages to go through the syslog
 460             mechanism (as LOG_DAEMON with level LOG_NOTICE) rather than to
 461             standard error.  This is also automatically enabled when stderr is
 462             unavailable.
 463           </para>
 464           <para>
 465             This option is passed through <command>install</command> or
 466             <command>remove</command> commands to other
 467             <command>modprobe</command> commands in the MODPROBE_OPTIONS
 468             environment variable.
 469           </para>
 470         </listitem>
 471       </varlistentry>
 472       <varlistentry>
 473         <term>
 474           <option>-V</option>
 475         </term>
 476         <term>
 477           <option>--version</option>
 478         </term>
 479         <listitem>
 480           <para>Show version of program and exit.</para>
 481         </listitem>
 482       </varlistentry>
 483       <varlistentry>
 484         <term>
 485           <option>-v</option>
 486         </term>
 487         <term>
 488           <option>--verbose</option>
 489         </term>
 490         <listitem>
 491           <para>
 492             Print messages about what the program is doing.  Usually
 493             <command>modprobe</command> only prints messages if something goes
 494             wrong.
 495           </para>
 496           <para>
 497             This option is passed through <command>install</command> or
 498             <command>remove</command> commands to other
 499             <command>modprobe</command> commands in the MODPROBE_OPTIONS
 500             environment variable.
 501           </para>
 502         </listitem>
 503       </varlistentry>
 504     </variablelist>
 505   </refsect1>
 506
 507   <refsect1><title>ENVIRONMENT</title>
 508     <para>
 509       The MODPROBE_OPTIONS environment variable can also be used to pass
 510       arguments to <command>modprobe</command>.
 511     </para>
 512   </refsect1>
 513
 514   <refsect1><title>COPYRIGHT</title>
 515     <para>
 516       This manual page originally Copyright 2002, Rusty Russell, IBM
 517       Corporation. Maintained by Jon Masters and others.
 518     </para>
 519   </refsect1>
 520
 521   <refsect1>
 522     <title>SEE ALSO</title>
 523     <para>
 524       <citerefentry>
 525         <refentrytitle>modprobe.d</refentrytitle><manvolnum>5</manvolnum>
 526       </citerefentry>,
 527       <citerefentry>
 528         <refentrytitle>insmod</refentrytitle><manvolnum>8</manvolnum>
 529       </citerefentry>,
 530       <citerefentry>
 531         <refentrytitle>rmmod</refentrytitle><manvolnum>8</manvolnum>
 532       </citerefentry>,
 533       <citerefentry>
 534         <refentrytitle>lsmod</refentrytitle><manvolnum>8</manvolnum>
 535       </citerefentry>,
 536       <citerefentry>
 537         <refentrytitle>modinfo</refentrytitle><manvolnum>8</manvolnum>
 538       </citerefentry>
 539       <citerefentry>
 540         <refentrytitle>depmod</refentrytitle><manvolnum>8</manvolnum>
 541       </citerefentry>
 542     </para>
 543   </refsect1>
 544 </refentry>