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>rusty@rustcorp.com.au</email>
  16     </address>
  17     <author>
  18       <firstname>Rusty</firstname>
  19       <surname>Russell</surname>
  20     </author>
  21     <date>2005-06-01</date>
  22   </refentryinfo>
  23   <refmeta>
  24     <refentrytitle>modprobe.d</refentrytitle>
  25     <manvolnum>5</manvolnum>
  26     <refentrytitle>modprobe.conf</refentrytitle>
  27     <manvolnum>5</manvolnum>
  28   </refmeta>
  29   <refnamediv>
  30     <refname>modprobe.conf</refname><refname>modprobe.d</refname> <refpurpose>Configuration file/directory for modprobe</refpurpose>
  31   </refnamediv>
  32   <refsect1>
  33     <title>DESCRIPTION</title>
  34
  35     <para>Because the <command>modprobe</command> command can add or
  36       remove extra more than one module, due to module dependencies,
  37       we need a method of specifying what options are to be used with
  38       those modules.  <filename>/etc/modprobe.conf</filename> (or, if that does not exist, all files under the <filename>/etc/modprobe.d</filename> directory) specifies
  39       those options, as required.  It can also be used to create
  40       convenient aliases: alternate names for a module.  Finally, it
  41       can override the normal <command>modprobe</command> behavior
  42       altogether, for those with very special requirements (such as
  43       inserting more than one module).
  44     </para>
  45     <para>
  46       Note that module and alias names (like other module names) can
  47       have - or _ in them: both are interchangable throughout all the
  48       module commands.
  49     </para>
  50     <para>
  51       The format of <filename>modprobe.conf</filename> and files under <filename>modprobe.d</filename> is simple: one
  52       command per line, with blank lines and lines starting with #
  53       ignored (useful for adding comments).  A \ at the end of a line
  54       causes it to continue on the next line, which makes the file a
  55       bit neater.
  56     </para>
  57     <para>
  58       The syntax is a simplification of <filename>modules.conf</filename>, used in 2.4 kernels and earlier.
  59     </para>
  60   </refsect1>
  61   <refsect1>
  62     <title>COMMANDS</title>
  63     <variablelist>
  64       <varlistentry>
  65         <term>alias <replaceable>wildcard</replaceable> <replaceable>modulename</replaceable>
  66         </term>
  67         <listitem>
  68           <para>
  69             This allows you to give alternate names for a module.  For
  70             example: "alias my-mod really_long_modulename"
  71             means you can use "modprobe my-mod" instead of "modprobe
  72             really_long_modulename".  You can also use shell-style
  73             wildcards, so "alias my-mod* really_long_modulename"
  74             means that "modprobe my-mod-something" has the same
  75             effect.  You can't have aliases to other aliases (that
  76             way lies madness), but aliases can have options, which
  77             will be added to any other options.
  78           </para>
  79           <para>
  80             Note that modules can also contain their own aliases,
  81             which you can see using <command>modinfo</command>.  These
  82             aliases are used as a last resort (ie. if there is no real
  83             module, <command>install</command>,
  84             <command>remove</command>, or <command>alias</command>
  85             command in the configuration).
  86           </para>
  87         </listitem>
  88       </varlistentry>
  89       <varlistentry>
  90         <term>options <replaceable>modulename</replaceable> <replaceable>option...</replaceable>
  91         </term>
  92         <listitem>
  93           <para>
  94             This command allows you to add options to the module
  95             <replaceable>modulename</replaceable> (which might be an
  96             alias) every time it is inserted into the kernel: whether
  97             directly (using <command>modprobe</command>
  98             <replaceable>modulename</replaceable>, or because the
  99             module being inserted depends on this module.
 100           </para>
 101           <para>
 102             All options are added together: they can come from an
 103             <command>option</command> for the module itself, for an
 104             alias, and on the command line.
 105           </para>
 106         </listitem>
 107       </varlistentry>
 108       <varlistentry>
 109         <term>install <replaceable>modulename</replaceable> <replaceable>command...</replaceable>
 110         </term>
 111         <listitem>
 112           <para>
 113             This is the most powerful primitive in
 114             <filename>modprobe.conf</filename>: it tells
 115             <command>modprobe</command> to run your command instead of
 116             inserting the module in the kernel as normal.  The command
 117             can be any shell command: this allows you to do any kind
 118             of complex processing you might wish.  For example, if the
 119             module "fred" worked better with the module "barney"
 120             already installed (but it didn't depend on it, so
 121             <command>modprobe</command> won't automatically load it),
 122             you could say "install fred /sbin/modprobe barney;
 123             /sbin/modprobe --ignore-install fred", which would do what
 124             you wanted.  Note the <option>--ignore-install</option>,
 125             which stops the second <command>modprobe</command> from
 126             re-running the same <command>install</command> command.
 127             See also <command>remove</command> below.
 128           </para>
 129           <para>
 130             You can also use <command>install</command> to make up
 131             modules which don't otherwise exist.  For example:
 132             "install probe-ethernet /sbin/modprobe e100 ||
 133             /sbin/modprobe eepro100", which will try first the e100
 134             driver, then the eepro100 driver, when you do "modprobe
 135             probe-ethernet".
 136           </para>
 137           <para>
 138             If you use the string "$CMDLINE_OPTS" in the command, it
 139             will be replaced by any options specified on the modprobe
 140             command line.  This can be useful because users expect
 141             "modprobe fred opt=1" to pass the "opt=1" arg to the
 142             module, even if there's an install command in the
 143             configuration file.  So our above example becomes "install
 144             fred /sbin/modprobe barney; /sbin/modprobe
 145             --ignore-install fred $CMDLINE_OPTS"
 146           </para>
 147         </listitem>
 148       </varlistentry>
 149       <varlistentry>
 150         <term>remove <replaceable>modulename</replaceable> <replaceable>command...</replaceable>
 151         </term>
 152         <listitem>
 153           <para>
 154             This is similar to the <command>install</command> command
 155             above, except it is invoked when "modprobe -r" is run.
 156             The removal counterparts to the two examples above would
 157             be: "remove fred /sbin/modprobe -r --ignore-remove fred &&
 158             /sbin/modprobe -r barney", and "remove probe-ethernet
 159             /sbin/modprobe -r eepro100 || /sbin/modprobe -r e100".
 160           </para>
 161         </listitem>
 162       </varlistentry>
 163       <varlistentry>
 164         <term>include <replaceable>filename</replaceable>
 165         </term>
 166         <listitem>
 167           <para>
 168             Using this command, you can include other configuration
 169             files, or whole directories, which is occasionally useful.  Note that aliases in
 170             the included file will override aliases previously
 171             declared in the current file.
 172           </para>
 173         </listitem>
 174       </varlistentry>
 175       <varlistentry>
 176         <term>blacklist <replaceable>modulename</replaceable>
 177         </term>
 178         <listitem>
 179           <para>
 180             Modules can contain their own aliases: usually these are
 181             aliases describing the devices they support, such as
 182             "pci:123...".  These "internal" aliases can be overridden
 183             by normal "alias" keywords, but there are cases where two
 184             or more modules both support the same devices, or a module
 185             invalidly claims to support a device: the
 186             <command>blacklist</command> keyword indicates that all of
 187             that particular module's internal aliases are to be ignored.
 188           </para>
 189         </listitem>
 190       </varlistentry>
 191     </variablelist>
 192   </refsect1>
 193   <refsect1>
 194     <title>Backwards Compatibility</title>
 195
 196     <para>
 197       There is a <command>generate_modprobe.conf</command> program
 198       which should do a reasonable job of generating
 199       <filename>modprobe.conf</filename> from your current (2.4 or
 200       2.2) modules setup.
 201     </para>
 202     <para>
 203       Although the syntax is similar to the older
 204       <filename>/etc/modules.conf</filename>, there are many features
 205       missing.  There are two reasons for this: firstly, install and
 206       remove commands can do just about anything, and secondly, the
 207       module-init-tools modprobe is designed to be simple enough that
 208       it can be easily replaced.
 209     </para>
 210     <para>
 211       With the complexity of actual module insertion reduced to three
 212       system calls (open, read, init_module), and the
 213       <filename>modules.dep</filename> file being simple and open,
 214       producing a more powerful modprobe variant can be done
 215       independently if there is a need.
 216     </para>
 217   </refsect1>
 218   <refsect1>
 219     <title>COPYRIGHT</title>
 220     <para>
 221       This manual page Copyright 2004, Rusty Russell, IBM Corporation.
 222     </para>
 223   </refsect1>
 224   <refsect1>
 225     <title>SEE ALSO</title>
 226
 227     <para><citerefentry>
 228         <refentrytitle>modprobe</refentrytitle><manvolnum>8</manvolnum>
 229       </citerefentry>,
 230       <citerefentry>
 231         <refentrytitle>modules.dep</refentrytitle><manvolnum>5</manvolnum>
 232       </citerefentry>
 233     </para>
 234   </refsect1>
 235 </refentry>
 236
 237 <!-- Keep this comment at the end of the file
 238 Local variables:
 239 mode: sgml
 240 sgml-omittag:t
 241 sgml-shorttag:t
 242 sgml-minimize-attributes:nil
 243 sgml-always-quote-attributes:t
 244 sgml-indent-step:2
 245 sgml-indent-data:t
 246 sgml-parent-document:nil
 247 sgml-default-dtd-file:nil
 248 sgml-exposed-tags:nil
 249 sgml-local-catalogs:nil
 250 sgml-local-ecat-files:nil
 251 End:
 252 -->