doc/modprobe.conf.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>jcm@jonmasters.org</email>
  16     </address>
  17     <author>
  18       <firstname>Jon</firstname>
  19       <surname>Masters</surname>
  20     </author>
  21     <date>2010-03-09</date>
  22   </refentryinfo>
  23   <refmeta>
  24     <refentrytitle>modprobe.conf</refentrytitle>
  25     <manvolnum>5</manvolnum>
  26   </refmeta>
  27   <refnamediv>
  28     <refname>modprobe.d</refname><refname>modprobe.conf</refname> <refpurpose>Configuration directory/file for modprobe</refpurpose>
  29   </refnamediv>
  30   <refsect1>
  31     <title>DESCRIPTION</title>
  32
  33     <para>Because the <command>modprobe</command> command can add or
  34       remove more than one module, due to modules having dependencies,
  35       we need a method of specifying what options are to be used with
  36       those modules.  All files underneath the
  37       <filename>/etc/modprobe.d</filename> directory which end with the
  38       <filename>.conf</filename> extension specify those options as
  39       required. (the <filename>/etc/modprobe.conf</filename> file can
  40       also be used if it exists, but that will be removed in a future
  41       version).  They can also be used to create convenient aliases:
  42       alternate names for a module, or they can override the normal
  43       <command>modprobe</command> behavior altogether for those with
  44       special requirements (such as inserting more than one module).
  45     </para>
  46     <para>
  47       Note that module and alias names (like other module names) can
  48       have - or _ in them: both are interchangable throughout all the
  49       module commands as underscore conversion happens automatically.
  50     </para>
  51     <para>
  52       The format of and files under <filename>modprobe.d</filename> and
  53       <filename>/etc/modprobe.conf</filename> is simple: one
  54       command per line, with blank lines and lines starting with '#'
  55       ignored (useful for adding comments).  A '\' at the end of a line
  56       causes it to continue on the next line, which makes the file a
  57       bit neater.
  58     </para>
  59   </refsect1>
  60   <refsect1>
  61     <title>COMMANDS</title>
  62     <variablelist>
  63       <varlistentry>
  64         <term>alias <replaceable>wildcard</replaceable> <replaceable>modulename</replaceable>
  65         </term>
  66         <listitem>
  67           <para>
  68             This allows you to give alternate names for a module.  For
  69             example: "alias my-mod really_long_modulename"
  70             means you can use "modprobe my-mod" instead of "modprobe
  71             really_long_modulename".  You can also use shell-style
  72             wildcards, so "alias my-mod* really_long_modulename"
  73             means that "modprobe my-mod-something" has the same
  74             effect.  You can't have aliases to other aliases (that
  75             way lies madness), but aliases can have options, which
  76             will be added to any other options.
  77           </para>
  78           <para>
  79             Note that modules can also contain their own aliases,
  80             which you can see using <command>modinfo</command>.  These
  81             aliases are used as a last resort (ie. if there is no real
  82             module, <command>install</command>,
  83             <command>remove</command>, or <command>alias</command>
  84             command in the configuration).
  85           </para>
  86         </listitem>
  87       </varlistentry>
  88       <varlistentry>
  89         <term>blacklist <replaceable>modulename</replaceable>
  90         </term>
  91         <listitem>
  92           <para>
  93             Modules can contain their own aliases: usually these are
  94             aliases describing the devices they support, such as
  95             "pci:123...".  These "internal" aliases can be overridden
  96             by normal "alias" keywords, but there are cases where two
  97             or more modules both support the same devices, or a module
  98             invalidly claims to support a device that it does not: the
  99             <command>blacklist</command> keyword indicates that all of
 100             that particular module's internal aliases are to be ignored.
 101           </para>
 102         </listitem>
 103       </varlistentry>
 104       <varlistentry>
 105         <term>install <replaceable>modulename</replaceable> <replaceable>command...</replaceable>
 106         </term>
 107         <listitem>
 108           <para>
 109             This command instructs <command>modprobe</command> to run your
 110             command instead of inserting the module in the kernel as normal.
 111             The command can be any shell command: this allows you to do any
 112             kind of complex processing you might wish.  For example, if the
 113             module "fred" works better with the module "barney"
 114             already installed (but it doesn't depend on it, so
 115             <command>modprobe</command> won't automatically load it),
 116             you could say "install fred /sbin/modprobe barney;
 117             /sbin/modprobe --ignore-install fred", which would do what
 118             you wanted.  Note the <option>--ignore-install</option>,
 119             which stops the second <command>modprobe</command> from
 120             running the same <command>install</command> command again.
 121             See also <command>remove</command> below.
 122           </para>
 123           <para>The long term future of this command as a solution to the
 124             problem of providing additional module dependencies is not assured
 125             and it is intended to replace this command with a warning about
 126             its eventual removal or deprecation at some point in a future
 127             release. Its use complicates the automated determination of module
 128             dependencies by distribution utilities, such as mkinitrd (because
 129             these now need to somehow interpret what the
 130             <command>install</command> commands might be doing.
 131             In a perfect world, modules would provide all dependency
 132             information without the use of this command and work is underway
 133             to implement soft dependency support within the Linux kernel.
 134           </para>
 135           <para>
 136             If you use the string "$CMDLINE_OPTS" in the command, it
 137             will be replaced by any options specified on the modprobe
 138             command line.  This can be useful because users expect
 139             "modprobe fred opt=1" to pass the "opt=1" arg to the
 140             module, even if there's an install command in the
 141             configuration file.  So our above example becomes "install
 142             fred /sbin/modprobe barney; /sbin/modprobe
 143             --ignore-install fred $CMDLINE_OPTS"
 144           </para>
 145         </listitem>
 146       </varlistentry>
 147       <varlistentry>
 148         <term>options <replaceable>modulename</replaceable> <replaceable>option...</replaceable>
 149         </term>
 150         <listitem>
 151           <para>
 152             This command allows you to add options to the module
 153             <replaceable>modulename</replaceable> (which might be an
 154             alias) every time it is inserted into the kernel: whether
 155             directly (using <command>modprobe</command>
 156             <replaceable>modulename</replaceable> or because the
 157             module being inserted depends on this module.
 158           </para>
 159           <para>
 160             All options are added together: they can come from an
 161             <command>option</command> for the module itself, for an
 162             alias, and on the command line.
 163           </para>
 164         </listitem>
 165       </varlistentry>
 166       <varlistentry>
 167         <term>remove <replaceable>modulename</replaceable> <replaceable>command...</replaceable>
 168         </term>
 169         <listitem>
 170           <para>
 171             This is similar to the <command>install</command> command
 172             above, except it is invoked when "modprobe -r" is run.
 173           </para>
 174         </listitem>
 175       </varlistentry>
 176       <varlistentry>
 177         <term>softdep <replaceable>modulename</replaceable> pre: <replaceable>modules...</replaceable> post: <replaceable>modules...</replaceable>
 178         </term>
 179         <listitem>
 180           <para>
 181             The <command>softdep</command> command allows you to specify soft,
 182             or optional, module dependencies. <replaceable>modulename</replaceable>
 183             can be used without these optional modules installed, but usually with
 184             some features missing. For example, a driver for a storage HBA might
 185             require another module be loaded in order to use management features.
 186           </para>
 187           <para>
 188             pre-deps and post-deps modules are lists of names and/or aliases of other
 189             modules that modprobe will attempt to install (or remove) in order
 190             before and after the main module given in the
 191             <replaceable>modulename</replaceable> argument.
 192           </para>
 193           <para>
 194             Example: Assume "softdep c pre: a b post: d e" is provided in the
 195             configuration. Running "modprobe c" is now equivalent to
 196             "modprobe a b c d e" without the softdep.
 197             Flags such as --use-blacklist are applied to all the specified
 198             modules, while module parameters only apply to module c.
 199           </para>
 200           <para>
 201             Note: if there are <command>install</command> or
 202             <command>remove</command> commands with the same
 203             <replaceable>modulename</replaceable> argument,
 204             <command>softdep</command> takes precedence.
 205           </para>
 206         </listitem>
 207       </varlistentry>
 208     </variablelist>
 209   </refsect1>
 210   <refsect1>
 211     <title>COMPATIBILITY</title>
 212     <para>
 213       A future version of module-init-tools will come with a strong warning
 214       to avoid use of the <command>install</command> as explained above. This
 215       will happen once support for soft dependencies in the kernel is complete.
 216       That support will complement the existing softdep support within this
 217       utility by providing such dependencies directly within the modules.
 218     </para>
 219   </refsect1>
 220   <refsect1>
 221     <title>COPYRIGHT</title>
 222     <para>
 223       This manual page originally Copyright 2004, Rusty Russell, IBM
 224       Corporation. Maintained by Jon Masters and others.
 225     </para>
 226   </refsect1>
 227   <refsect1>
 228     <title>SEE ALSO</title>
 229
 230     <para><citerefentry>
 231         <refentrytitle>modprobe</refentrytitle><manvolnum>8</manvolnum>
 232       </citerefentry>,
 233       <citerefentry>
 234         <refentrytitle>modules.dep</refentrytitle><manvolnum>5</manvolnum>
 235       </citerefentry>
 236     </para>
 237   </refsect1>
 238 </refentry>
 239
 240 <!-- Keep this comment at the end of the file
 241 Local variables:
 242 mode: sgml
 243 sgml-omittag:t
 244 sgml-shorttag:t
 245 sgml-minimize-attributes:nil
 246 sgml-always-quote-attributes:t
 247 sgml-indent-step:2
 248 sgml-indent-data:t
 249 sgml-parent-document:nil
 250 sgml-default-dtd-file:nil
 251 sgml-exposed-tags:nil
 252 sgml-local-catalogs:nil
 253 sgml-local-ecat-files:nil
 254 End:
 255 -->