Provided by: dkms_2.2.0.3-1.1ubuntu5_all bug

NAME

       dkms - Dynamic Kernel Module Support

SYNOPSIS

       dkms [action] [options] [module/module-version] [/path/to/source-tree]
            [/path/to/tarball.tar] [/path/to/driver.rpm]

DESCRIPTION

       dkms is a framework which allows kernel modules to be dynamically built
       for each kernel on your system in a simplified and organized fashion.

ACTIONS

       add [module/module-version] [/path/to/source-tree]
           [/path/to/tarball.tar]

           Adds a module/module-version combination to the tree for builds and
           installs.   If  module/module-version, -m module/module-version, or
           -m module -v version are passed as options, this  command  requires
           source in /usr/src/<module>-<module-version>/ as well as a properly
           formatted dkms.conf file. If /path/to/source-tree is passed  as  an
           option,  and  source-tree  contains  a dkms.conf file, it will copy
           /path/to/source-tree   to    /usr/src/module-module-version.     If
           /path/to/tarball.tar  is  passed,  this  command  behaves  like the
           ldtarball command.

       remove [module/module-version] [-k kernel/arch] [--all]

           Removes a module/version or module/version/kernel/arch  combination
           from  the  tree.   If  the  module is currently installed, it first
           uninstalls  it  and  if  applicable,  will  replace  it  with   its
           original_module.   Use  the  --all  option  in  order to remove all
           instances for every kernel at once.

       build [module/module-version] [-k kernel/arch]

           Builds  the  specified  module/version  combo  for  the   specified
           kernel/arch.  If  the  -k option is not specified it builds for the
           currently running kernel  and  arch..   All  builds  occur  in  the
           directory  /var/lib/dkms/<module>/<module-version>/build/.   If the
           module/module-version combo has not been added, dkms  will  try  to
           add it, and in that case build can take the same arguments that add
           can.

       install [module/module-version] [-k kernel/arch] [/path/to/driver.rpm]

           Installs a built module/version combo onto the kernel it was  built
           for. If the kernel option is not specified it assumes the currently
           running kernel.  If the module has not been built, dkms will try to
           build  it.   If the module has not been added, dkms will try to add
           it.  In both cases, the install command  can  then  take  the  same
           arguments  as  the build or add commands.  If you pass a .rpm file,
           dkms will try to install that file with rpm  -Uvh  ,  and  it  will
           perform  an  autoinstall  action to mesure that everything is built
           for your kernel if the RPM installed sucessfully.

       uninstall [module/module-version] [-k kernel/arch]

           Uninstalls  an  installed  module/module-version  combo  from   the
           kernel/arch  passed  in the -k option, or the current kernel if the
           -k option was not passed.  upon.  After uninstall  completion,  the
           driver  will  be  left  in the built state.  To completely remove a
           driver, the remove action should be utilized.

       match [--templatekernel kernel/arch] [-k kernel/arch]

           Match installs modules onto the specified kernel by looking at  the
           configuration  of  the specified templatekernel.  Every module that
           is installed on the templatekernel within dkms is then installed on
           that specified kernel.

       mkdriverdisk [-d distro] [-r release] [--media mediatype]
                    [-k kernel/arch] [module/version]

           Creates a floppy driver disk image for use when updated drivers are
           needed  to  install  an OS.  Currently, the supported distributions
           are redhat,  suse  and  UnitedLinux.  For  Red  Hat  driver  disks,
           necessary    driver    disk   files   are   looked   for   in   the
           redhat_driver_disk subdirectory of your  module  source  directory.
           You  must specify the distro while using this action.  Driver disks
           can be made for single kernels or can be made to  support  multiple
           kernels.   To  create a driver disk image with modules for multiple
           kernels, just specify multiple -k parameters on  the  command  line
           (-k kernel1/arch1 -k kernel2/arch2).

           Red  Hat  began  supporting multi-arched driver disks in RHEL3.  To
           force creation of a driver disk with arch information,  specify  -d
           redhat2  or  if  you specify multiple architectures on the command-
           line and use -d redhat , DKMS will create a version 2 driver  disk.
           By  specifying  -d  redhat1 , you can force a version 1 driver disk
           image.

           Note  that  redhat1  driver  disks  actually   supported   multiple
           architectures  when  the second arch was i386 and the kernel module
           was for the BOOT kernel.  DKMS allows for this, and as such you can
           create  a  redhat1 style driver disk if the only other arch is i386
           and the kernel name ends in BOOT.

           Red Hat introduced DDv3 starting with  RHEL6.  To  create  Red  Hat
           DDv3,  specify  -d  redhat3  and  specify  the specfile to use with
           --spec=specfile.  If  no  specfile  is  specified,  DKMS  will  use
           /etc/dkms/template-dkms-redhat-kmod.spec

           See  http://people.redhat.com/dledford  for more information on the
           Red Hat driver disk standards and which files are necessary to make
           a driver disk.

           Fedora  Core  5  and  higher, RHEL5 and higher require DKMS version
           2.0.14 or higher to generate a proper driver disk image.

           For            suse/UnitedLinux            driver            disks,
           /usr/share/YaST2/modules/Vendor.ycp  will  also  be  copied  to the
           driver disk;  no  other  files  are  needed.   However,  for  these
           distros,  you  must specify a -r release. For SuSE 9.1, it would be
           -d suse -r 9.1. For SLES9, it would be -d suse -r sles9.

           By default the disk image it creates is 1440 (k) in size.  This can
           be  overridden  by  specifying a different --size #### which should
           should be given as a number in kilobytes divisible by 20.

           You may have more content than will fit on  a  floppy.   Therefore,
           DKMS  can  now  generate  image  files of different types.  --media
           floppy (default) to generate a floppy disk image, or --media iso to
           generate a CD-ROM ISO file, or --media tar to generate a tar file.

           You  may  copy the floppy or ISO image file to a USB key to be used
           with OS installer.

       mktarball [module/module-version] [-k kernel/arch]
                 [--archive /path/to/tarball.tar] [--source-only] [--binaries-
                 only]

           Creates a tarball archive for the specified module/version  of  all
           files  in  the DKMS tree for that module/version combination.  This
           includes the source and any built modules for kernels in  the  tree
           (as  specified).   Otherwise,  you can specify a singular kernel to
           archive only, or multiple kernels to archive (-k  kernel1/arch1  -k
           kernel2/arch2).   Optionally,  you can use --archive to specify the
           file that you would like to save this tarball  to.   You  can  also
           specify  --binaries-only  if  you want the resultant tarball not to
           include the module source.  Likewise, --source-only can be used  to
           specify  that  no  prebuilt  binaries  should  be  included  in the
           tarball.  In general, mktarball is  great  for  systems  management
           purposes  as  you can build your driver on just one system and then
           use ldtarball on all of your other systems to get  the  same  built
           modules loaded without having to wait for anything to compile.

       ldtarball

           This  takes  a tarball made from the mktarball command and loads it
           into your DKMS tree.  This will leave any newly  added  modules  in
           the  built  state and dkms install should then be called to install
           any of them.  If files already exist where ldtarball is  attempting
           to  place  them,  it will warn and not copy over them.  The --force
           option should be used to override this.

       mkrpm [module/module-version] [-k kernel/arch] [--source-only]
             [--binaries-only]

           This  action  allows  you  to create an RPM package for a specified
           module  /  version.   It  uses  a  template  .spec  file  found  in
           /etc/dkms/template-dkms-mkrpm.spec   as  the  basis  for  the  RPM.
           Alternatively,     if     DKMS     finds     a     file      called
           /usr/src/<module>-<module-version>/<module>-dkms-mkrpm.spec it will
           use that .spec file instead.  In general, a DKMS tarball is  placed
           inside  the  contents of this RPM, and the RPM itself calls various
           DKMS commands to load this tarball, build and  install  modules  on
           the  end user's system.  If you do not want your RPM to contain any
           prebuilt binaries, be sure to specify --source-only  in  the  mkrpm
           command.

              mkdeb
             [module/module-version] [-k kernel/arch] [--binaries-only]
             [--source-only]

           This action allows you to create a  debian  binary  package  for  a
           specified  module  /  version.  It uses a template debian directory
           found  in  /etc/dkms/template-dkms-mkdeb  as  the  basis  for   the
           package.    Alternatively,    if   DKMS   finds   a   file   called
           /usr/src/<module>-<module-version>/<module>-dkms-mkdeb it will  use
           that  folder  instead.  In general, a DKMS tarball is placed inside
           the contents of this package, and the package itself calls  various
           DKMS  commands  to  load this tarball, build and install modules on
           the end user's system.  If you do not want your debian  package  to
           contain  any prebuilt binaries, be sure to specify --source-only in
           the mkdeb command.

       mkdsc [module/module-version] [-k kernel/arch] [--binaries-only]
             [--source-only]

           This  action  allows  you  to  create a debian source package for a
           specified module / version.  It will create a .tar.gz, and a  .dsc.
           All  options  supported  by  mkdeb  are  supported by it.  The main
           difference   in   it's   usage   is   that   it   will   look    in
           /etc/dkms/template-dkms-mkdsc   as   the  basis  for  the  package.
           Alternatively,     if     DKMS     finds     a     file      called
           /usr/src/<module>-<module-version>/<module>-dkms-mkdsc  it will use
           that folder instead. If you do not want your debian source  package
           to  contain any prebuilt binaries, be sure to specify --source-only
           in the mkdsc command.

       mkkmp [module/module-version] [--spec specfile]

           This action allows you to create an Kernel  Module  Package  source
           RPM  for  a  specified  module  /  version.  It uses the .spec file
           specified by --spec=specfile else $module-kmp.spec as the basis for
           the  RPM.   The generated source RPM may then be built using SuSE's
           build.rpm  or  Fedora/RHEL's   mock   chroot   environments.    See
           http://kerneldrivers.org/ for more details on KMPs.

       status [module/module-version] [-k kernel/arch]

           Returns  the current status of modules, versions and kernels within
           the tree as  well  as  whether  they  have  been  added,  built  or
           installed.   Status  can  be  shown  for  just  a certain module, a
           certain    kernel,    a    module/version    combination    or    a
           module/version/kernel combination.

       autoinstall

           Attempt  to  install  the  latest revision of all modules that have
           been installed for other kernel revisions.  dkms_autoinstaller is a
           stub that uses this action to perform its work.

OPTIONS

       -m <module>/<module-version>
              The  name  of  the module and module version you wnat to operate
              on. The -m part of this option is optional, and can  be  omitted
              in virtually all circumstances.

       -v <module-version>
              The  version of the module to execute the specified action upon.
              This option only has to be specified if you  pass  a  -m  option
              without a <module-version> component of its own.

       -k <kernel-version>/<arch>
              The kernel and arch to perform the action upon.  You can specify
              multiple kernel  version/arch  pairs  on  the  command  line  by
              repeating  the  -k  argument with a different kernel version and
              arch.  However, not all actions support multiple kernel versions
              (it will error out in this case).  The arch part can be omitted,
              and DKMS will assume you want it to be the arch of the currently
              running system.

       -a, --arch
              The  system  architecture  to  perform  the  action upon.  It is
              optional if you pass it  as  part  of  the  -k  option.  If  not
              specified,  it  assumes the arch of the currently running system
              (`uname -m`).  You can specify multiple arch parameters  on  the
              same  command line by repeating the -a argument with a different
              arch name.  When multiple  architectures  are  specified,  there
              must be a 1:1 relationship between -k arguments to -a arguments.
              DKMS will then assume the first  -a  argument  aligns  with  the
              first -k kernel and so on for the second, third, etc.

              For  example,  if  you were to specify: -k kernel1 -k kernel2 -a
              i386 -k kernel3 -a i686 -a x86_64, DKMS would process  this  as:
              kernel1-i386, kernel2-i686, kernel3-x86_64.

       -q, --quiet
              Quiet.

       -V, --version
              Prints the currently installed version of dkms and exits.

       -c <dkms.conf-location>
              The  location of the dkms.conf file.  This is needed for the add
              action and if not specified, it is  assumed  to  be  located  in
              /usr/src/<module>-<module-version>/.    See   below   for   more
              information on the format of dkms.conf.

       -d, --distro
              The distribution being used.  This is only currently needed  for
              mkdriverdisk.   The  supported  distros  are  redhat,  suse  and
              UnitedLinux.  See the sections on  mkdriverdisk  and  mkkmp  for
              more information.

       -r, --release
              The  release  being  used.   This  is  only  currently  used for
              mkdriverdisk and is only used for suse  or  UnitedLinux  distros
              (eg.  -r  9.1).   It  is  used  in  the  internal  makeup of the
              driverdisk.

       --size The size of the driver disk image to be  created.   By  default,
              this  value  is set at 1440.  Any different size should be given
              as an integer value only, should be divisible by 20  and  should
              represent the number of kilobytes of the image size you desire.

       --config <kernel-.config-location>
              During  a  build  this  option  is  used to specify an alternate
              location for the kernel .config file which was used  to  compile
              that  kernel.  Normally, dkms uses the Red Hat standard location
              and         config         filenames         located          in
              /usr/src/linux-<kernel>/configs/.   If the config for the kernel
              that you are building a module for is not located here  or  does
              not  have  the  expected name in this location, you will need to
              tell dkms where the necessary .config can be found so that  your
              kernel can be properly prepared for the module build.

       --archive <tarball-location>
              This  option  is  used  during a ldtarball action to specify the
              location of the tarball you wish to load into  your  DKMS  tree.
              You  only  have  to specify the --archive part of this option if
              <tarball-location> does not already exist as a file.

       --templatekernel <kernel-version>
              This option is required for the action: match.  Match will  look
              at  the  templatekernel  specified  and  install all of the same
              module/version combinations on the other kernel.

       --force
              This option can be used in conjunction with ldtarball  to  force
              copying over of extant files.

       --binaries-only
              This  option  can be used in conjunction with mktarball in order
              to create a DKMS tarball which does not contain the  source  for
              the  module within it.  This can be helpful in reducing the size
              of the tarball if you know that the system  which  this  tarball
              will  be loaded upon already has the source installed.  In order
              to load a tarball made as binaries-only you must have the module
              source  in  that  systems  DKMS  tree.  If you do not, DKMS will
              refuse to load a binaries-only tarball.

       --source-only
              This option can be used in conjunction with mktarball  or  mkrpm
              or  mkdeb  in  order  to  create  a  DKMS tarball which does not
              contain any prebuilt kernel module binaries within it.  This  is
              helpful  if  you  simply  want  to easily tar up your source but
              don't want anything prebuilt within it.  Likewise,  if  you  are
              using  mkrpm  but  do  not  want  the RPM you create to have any
              prebuilt modules within it, passing this option  will  keep  its
              internal DKMS tarball from containing any prebuilt modules.

       --all  This  option  can  be used to automatically specify all relevant
              kernels/arches for a module/module-version.  This is useful  for
              things like remove , mktarball , etc.  This saves the trouble of
              having to actually specify -k kernel1 -a  arch1  -k  kernel2  -a
              arch2 for every kernel you have built your module for.

       --no-prepare-kernel
              This  option  keeps DKMS from first preparing your kernel before
              building a module for it.  Generally, this option should not  be
              used so as to ensure that modules are compiled correctly.

       --no-clean-kernel
              This  option  keeps  DKMS  from cleaning your kernel source tree
              after a build.

       --kernelsourcedir <kernel-source-directory-location>
              Using this option you can specify the location  of  your  kernel
              source  directory.  Most likely you will not need to set this if
              your      kernel      source       is       accessible       via
              /lib/modules/$kernel_version/build.

       --directive <"cli-directive=cli-value">
              Using  this  option,  you can specify additional directives from
              the command line.  The --directive option can be  used  multiple
              times  on  the  same command-line to specify multiple additional
              command line directives.

       --rpm_safe_upgrade
              This flag should be used when packaging DKMS enabled modules  in
              RPMs.   It  should  be  specified during both the add and remove
              actions in the RPM spec to  ensure  that  DKMS  and  RPM  behave
              correctly  in  all  scenarios  when  upgrading  between  various
              versions  of  a  dkms  enabled  module  RPM  package.   See  the
              sample.spec  file  for  an  example  or read more in the section
              below on Creating RPMs Which Utilize DKMS.

       --spec specfile
              This option is used by the mkkmp action  to  specify  which  RPM
              spec  file  to  use  when  generating the KMP.  specfile will be
              sought in the module source directory.

       --dkmstree path/to/place
              Provides a destination tree for building and installing  modules
              to.  Useful in cases that you don't want to contaminate a system
              when using solely for building.

       --sourcetree path/to/place
              Provides a location to build a DKMS package  from.   Useful  for
              systems  that you may not have root access, but would still like
              to be able to build DKMS packages.

       --installtree path/to/place
              Provides a location to place modules when a dkms install command
              is issued.

       --legacy-postinst=[0|1]
              Includes  a legacy postinstall script so that a DEB or RPM built
              by DKMS can be used on  versions  prior  than  DKMS  2.1.   This
              option currently defaults to 1.

       --dkmsframework path/to/file
              A  supplemental  configuration  file  to  the  system-wide  dkms
              framework, typically located in  /etc/dkms/framework.conf.   All
              option  that  are  normally  provided  on  a command line can be
              provided in this file.

ORIGINAL MODULES

       During the first install of a module for a <kernelversion>,  dkms  will
       search  /lib/modules/<kernelversion>  for  a pre-existing module of the
       same name. If one is found,  it  will  automatically  be  saved  as  an
       "original_module"  so  that  if the newer module is later removed, dkms
       will put the original  module  back  in  its  place.   Currently,  DKMS
       searches  for  these  original  modules  with first preference going to
       modules located in  /lib/modules/<kernelversion>/updates/  followed  by
       $DEST_MODULE_LOCATION  (as  specified in dkms.conf ).  If one cannot be
       found in either location, a find will be used to locate  one  for  that
       kernel.   If none are found, then during a later uninstall, your kernel
       will not have that module replaced.

       If more than one is found, then the first one  located  (by  preference
       indicated  above)  will  be considered the "original_module".  As well,
       all copies of the same-named module will be removed  from  your  kernel
       tree                  and                  placed                  into
       /var/lib/dkms/<module>/original_module/$kernelver/collisions  so   that
       they  can  be  *manually* accessible later. DKMS will never actually do
       anything with the modules found underneath the  /collisions  directory,
       and they will be stored there until you manually delete them.

DKMS.CONF

       When  performing  an  add  ,  a proper dkms.conf file must be found.  A
       properly formatted conf file is essential for communicating to dkms how
       and where the module should be installed.  While not all the directives
       are required,  providing  as  many  as  possible  helps  to  limit  any
       ambiguity.   Note  that  the dkms.conf is really only a shell-script of
       variable definitions which are then sourced in by the  dkms  executable
       (of  the  format,  DIRECTIVE="directive text goes here").  As well, the
       directives are case-sensitive and should be given in ALL CAPS.

       It is important to understand that many  of  the  DKMS  directives  are
       arrays  whose index values are tied together.  These array associations
       can be considered families, and there are currently four such  families
       of  directive  arrays.   MAKE[#]  and MAKE_MATCH[#] make up one family.
       PATCH[#] and PATCH_MATCH[#] make up the second family.  The third   and
       largest       family       consists       of      BUILT_MODULE_NAME[#],
       BUILT_MODULE_LOCATION[#], DEST_MODULE_NAME[#], DEST_MODULE_LOCATION[#],
       MODULES_CONF_ALIAS_TYPE[#],                  MODULES_CONF_OBSOLETES[#],
       MODULES_CONF_OBSOLETE_ONLY[#] and STRIP[#].  The fourth family is  made
       up  of  only MODULES_CONF[#].  When indexing these arrays when creating
       your dkms.conf, each family should start at index value 0.

       MAKE[#]=
              The MAKE directive array tells DKMS which make command should be
              used  for  building your module. The default make command should
              be put into MAKE[0].  Other entries in the MAKE array will  only
              be  used  if their corresponding entry in MAKE_MATCH[#] matches,
              as a regular expression  (using  egrep),  the  kernel  that  the
              module  is  being built for.  Note that if no value is placed in
              MAKE_MATCH[#] for any MAKE[#]  where  #  >  0,  then  that  MAKE
              directive  is  ignored.   MAKE_MATCH[0] is optional and if it is
              populated, it will be used to determine  if  MAKE[0]  should  be
              used   to  build  the  module  for  that  kernel.   If  multiple
              MAKE_MATCH directives match against the kernel being built  for,
              the  last matching MAKE[#] will be used to build your module. If
              no MAKE directive is specified or if no MAKE_MATCH  matches  the
              kernel  being built for, DKMS will attempt to use a generic MAKE
              command to build your module.

              KERNELRELEASE will be automatically appended to MAKE[#].  If you
              want  to suppress this behavior, you can quote the make command:
              'make'.

       MAKE_MATCH[#]=
              See the above entry on MAKE[#] directives.  This array should be
              populated  with  regular expressions which, when matched against
              the  kernel  being  built  for,  will  tell  DKMS  to  use   the
              corresponding  make  command  in  the MAKE[#] directive array to
              build your module.

       BUILT_MODULE_NAME[#]=
              This directive gives the name of the module  just  after  it  is
              built.   If  your  DKMS  module  package  contains more than one
              module to install, this is a required directive for all  of  the
              modules.   This  directive  should  explicitly  not  contain any
              trailing ".o" or ".ko".  Note that for each module within a dkms
              package,  the  numeric  value  of # must be the same for each of
              BUILT_MODULE_NAME, BUILT_MODULE_LOCATION,  DEST_MODULE_NAME  and
              DEST_MODULE_LOCATION  and  that  the numbering should start at 0
              (eg.                              BUILT_MODULE_NAME[0]="qla2200"
              BUILT_MODULE_NAME[1]="qla2300").

       BUILT_MODULE_LOCATION[#]=
              This  directive tells DKMS where to find your built module after
              it has been built.  This pathname should be  given  relative  to
              the  root  directory  of your source files (where your dkms.conf
              file can be  found).   If  unset,  DKMS  expects  to  find  your
              BUILT_MODULE_NAME[#] in the root directory of your source files.
              Note that for each module within a  dkms  package,  the  numeric
              value  of  #  must  be  the  same for each of BUILT_MODULE_NAME,
              BUILT_MODULE_LOCATION, DEST_MODULE_NAME and DEST_MODULE_LOCATION
              and    that    the    numbering   should   start   at   0   (eg.
              BUILT_MODULE_LOCATION[0]="some/dir/"
              BUILT_MODULE_LOCATION[1]="other/dir/").

       DEST_MODULE_NAME[#]=
              This  directive can be used to specify the name of the module as
              it should be  installed.   This  will  rename  the  module  from
              BUILT_MODULE_NAME[#]  to  DEST_MODULE_NAME[#].   This  directive
              should explicitly not contain any trailing ".o"  or  ".ko".   If
              unset,    it    is   assumed   to   be   the   same   value   as
              BUILT_MODULE_NAME[#].  Note that for each module within  a  dkms
              package,  the  numeric  value  of # must be the same for each of
              BUILT_MODULE_NAME, BUILT_MODULE_LOCATION,  DEST_MODULE_NAME  and
              DEST_MODULE_LOCATION  and  that  the numbering should start at 0
              (eg.                            DEST_MODULE_NAME[0]="qla2200_6x"
              DEST_MODULE_NAME[1]="qla2300_6x").

       DEST_MODULE_LOCATION[#]=
              This  directive  specifies the destination where a module should
              be installed to, once compiled.  It also  is  used  for  finding
              original_modules.  This is a required directive, except as noted
              below. This directive must start with the text  "/kernel"  which
              is  in  reference  to /lib/modules/<kernelversion>/kernel.  Note
              that for each module within a dkms package, the numeric value of
              #   must   be   the   same   for   each   of  BUILT_MODULE_NAME,
              BUILT_MODULE_LOCATION, DEST_MODULE_NAME and DEST_MODULE_LOCATION
              and    that    the    numbering   should   start   at   0   (eg.
              DEST_MODULE_LOCATION[0]="/kernel/drivers/something/"
              DEST_MODULE_LOCATION[1]="/kernel/drivers/other/").

              DEST_MODULE_LOCATION is ignored on Fedora Core 6 and higher, Red
              Hat Enterprise Linux 5 and higher, Novell SuSE Linux  Enterprise
              Server  10  and  higher,  Novell SuSE Linux 10.0 and higher, and
              Ubuntu. Instead, the proper distribution-specific  directory  is
              used.

       MODULES_CONF_ALIAS_TYPE[#]=
              This  directive  array  specifies  how  your  modules  should be
              aliased in /etc/modules.conf  when  your  module  is  installed.
              This  is  done  in  an intelligent fashion so if DKMS detects an
              already existing reference in modules.conf, it won't add  a  new
              line.  If it is not detected, it will add it to the modules.conf
              as  the  last  alias  number  for  that  alias  type   (eg.   if
              MODULES_CONF_ALIAS_TYPE="scsi_hostadapter",  no  alias currently
              exists for that module and the last  scsi_hostadapter  reference
              is  6,  then  your module will be added as "scsi_hostadapter7").
              Common values for this  directive  include:  scsi_hostadapter  ,
              sound-slot-  and  eth.  Note that the numeric value of # is tied
              to  the  index  of   BUILD_MODULE_NAME,   BUILT_MODULE_LOCATION,
              DEST_MODULE_NAME  and  DEST_MODULE_LOCATION.   The index is also
              tied to MODULES_CONF_OBSOLETES.

       MODULES_CONF_OBSOLETES[#]=
              This  directive  array  tells  DKMS  what   modules.conf   alias
              references  are  obsoleted by the module you are installing.  If
              your module obsoletes  more  than  one  module,  this  directive
              should  be  a  comma-delimited  list  of  those modules that are
              obsoleted            (eg.             for             megaraid2,
              MODULES_CONF_OBSOLETES[0]="megaraid,megaraid_2002").   When  you
              are installing your module, DKMS ensures  that  any  entries  in
              /etc/modules.conf  with  the  same  MODULES_CONF_ALIAS_TYPE  are
              changed over to the new module name.  When you are  uninstalling
              your module, depending on the modules in your /lib/modules tree,
              DKMS  will  take  different  actions.   If  you  kernel  has  an
              original_module,  then  modules.conf will not be touched and the
              non-obsolete reference will remain.  If the kernel does not have
              an original_module but does have one of the obsolete modules, it
              will replace those references with  the  first  obsolete  module
              name  in  the  comma-delimited  list that is also in that kernel
              (thus, your obsolete list should be  prioritized  from  left  to
              right).   If  no  original_module  or obsolete modules are found
              within the kernel, the alias entry is removed all-together. Note
              that   the   numeric  value  of  #  is  tied  to  the  index  of
              BUILD_MODULE_NAME, BUILT_MODULE_LOCATION,  DEST_MODULE_NAME  and
              DEST_MODULE_LOCATION.     The    index    is    also   tied   to
              MODULES_CONF_ALIAS_TYPE.

       MODULES_CONF_OBSOLETE_ONLY[#]=
              If set to yes , this directive will tell  DKMS  to  only  modify
              /etc/modules.conf if it finds within it an obsolete reference as
              specified      in      the      corresponding      value      of
              MODULES_CONF_OBSOLETES[#] array directive.

       STRIP[#]=
              By  default  strip  is  considered to be "yes".  If set to "no",
              DKMS will not run strip -g against your built module  to  remove
              debug symbols from it.

       PACKAGE_NAME=
              This  directive  is  used  to  give the name associated with the
              entire package of modules.  This is the same name that  is  used
              with  the  -m  option  when  building,  adding, etc. and may not
              necessarily be the same as the MODULE_NAME.  This directive must
              be present in every dkms.conf.

       PACKAGE_VERSION=
              This  directive  is used to give the version associated with the
              entire package of  modules  being  installed  within  that  dkms
              package.  This directive must be present in every dkms.conf.

       CLEAN= CLEAN  specifies  the  make clean command to be used to clean up
              both before and after building the  module.   If  unset,  it  is
              assumed to be "make clean".

       REMAKE_INITRD=
              This  directive  specifies  whether your initrd should be remade
              after the module is installed onto the kernel.  Any  text  after
              the first character is ignored and if the first character is not
              a "y" or a "Y", it is assumed that REMAKE_INITRD="no".

       UDEV_TRIGGER=
              This optional directive specifies, if the udev  daemon  will  be
              get  a  trigger  event  after  the  module is installed for your
              currently running kernel. Because this udev trigger  might  have
              some  unfriendly side effects on some Linux Systems, you can now
              disable this trigger, if your driver does not  need  it  anyway.
              UDEV_TRIGGER=yes  is  assumed  as  the  default,  although  this
              directive may not be given. This ensures backward  compatibility
              to  older  DKMS  releases. Any text after the first character is
              ignored and if the first character is not a "n" or a "N", it  is
              assumed that UDEV_TRIGGER="yes".

       MODULES_CONF[#]=
              This  directive  array  specifies what static configuration text
              lines need to be added into /etc/modules.conf for  your  module.
              See  the  section  on  MODULES.CONF CHANGES for more information
              regarding the implications of modifying /etc/modules.conf

       OBSOLETE_BY=
              This directive allows you  to  specify  a  kernel  version  that
              obsoletes  the  necessity for this particular DKMS module.  This
              can be specified as a particular upstream kernel or an ABI  bump
              of  a kernel.  For example, "2.6.24" would be an upstream kernel
              and "2.6.24-16" would represent an ABI bump for a kernel.   Both
              are valid in this area.

              Please avoid the use of OBSOLETE_BY wherever possible.  It's use
              indicates   a   lack   of   proper   module   versioning   using
              MODULE_VERSION() tags in the module source itself.  It is better
              to fix the MODULE_VERSION() tags  than  use  OBSOLETE_BY.   This
              also  introduces  a  implicit distribution/version dependency on
              the package, as the value of OBSOLETE_BY is meaningful  only  in
              the context of a single distribution/version.

              If you feel you must use it, please use as such in dkms.conf:

               ubuntu_804="Ubuntu
               8.04"
               if [ -x /usr/bin/lsb_release ]; then
                 if  [  "$(/usr/bin/lsb_release  -sir)"  == "${ubuntu_804}" ];
              then
                   OBSOLETE_BY="2.6.25"
                 fi
               fi

       PATCH[#]=
              Use the PATCH directive array to specify patches which should be
              applied  to  your source before a build occurs.  All patches are
              expected to be in -p1 format and are applied with the patch  -p1
              command.   Each  directive  should  specify  the filename of the
              patch to apply, and all patches must be located in  the  patches
              subdirectory      of      your      source      directory      (
              /usr/src/<module>-<module-version>/patches/  ).   If  any  patch
              fails  to apply, the build will be halted and the rejections can
              be inspected in  /var/lib/dkms/<module>/<module-version>/build/.
              If   a   PATCH   should   only  be  applied  conditionally,  the
              PATCH_MATCH[#] array should be used, and a corresponding regular
              expression  should  be placed in PATCH_MATCH[#] which will alert
              dkms to only use that PATCH[#] if the regular expression matches
              the kernel which the module is currently being built for.

       PATCH_MATCH[#]=
              See  the  above description for PATCH[#] directives. If you only
              want a patch applied in certain scenarios, the PATCH_MATCH array
              should  be utilized by giving a regular expression which matches
              the kernels you intend the corresponding PATCH[#] to be  applied
              to before building that module.

       AUTOINSTALL=
              If   this   directive   is   set   to   yes   then  the  service
              /etc/rc.d/init.d/dkms_autoinstaller will  automatically  try  to
              install  this  module  on  any  kernel  you  boot into.  See the
              section on dkms_autoinstaller for more information.

       BUILD_EXCLUSIVE_KERNEL=
              This  optional  directive  allows  you  to  specify  a   regular
              expression  which  defines  the  subset of kernels which DKMS is
              allowed to build your module for.  If the kernel being built for
              does  not  match against this regular expression, the dkms build
              will error out.  For example, if you set it as  ="^2.4.*",  your
              module would not be built for 2.6 kernels.

       BUILD_EXCLUSIVE_ARCH=
              This    optional   directive   functions   very   similarly   to
              BUILD_EXCLUSIVE_KERNEL except that it matches against the kernel
              architecture.   For  example,  if  you  set  it to ="i.86", your
              module would not be built for ia32e, x86_64, amd64, s390, etc.

       POST_ADD=
              The name of the script to be run after an add is performed.  The
              path  should  be  given  relative  to the root directory of your
              source.

       POST_BUILD=
              The name of the script to be run after a build is performed. The
              path  should  be  given  relative  to the root directory of your
              source.

       POST_INSTALL=
              The name of the script to be run after an install is  performed.
              The  path should be given relative to the root directory of your
              source.

       POST_REMOVE=
              The name of the script to be run after a  remove  is  performed.
              The  path should be given relative to the root directory of your
              source.

       PRE_BUILD=
              The name of the script to be run before a  build  is  performed.
              The  path should be given relative to the root directory of your
              source.

       PRE_INSTALL=
              The name of the script to be run before an install is performed.
              The  path should be given relative to the root directory of your
              source.  If the script exits with a non-zero value, the  install
              will  be  aborted.   This  is typically used to perform a custom
              version comparison.

       DKMS.CONF VARIABLES
              Within your dkms.conf file, you can use certain variables  which
              will be replaced at run-time with their values.

       $kernelver
              This  variable  can  be  used  within a directive definition and
              during use, the  actual  kernel  version  in  question  will  be
              substituted  in  its  place.   This is especially useful in MAKE
              commands when specifying which INCLUDE statements should be used
              when    compiling    your    module    (eg.    MAKE="make    all
              INCLUDEDIR=/lib/modules/${kernelver}/build/include").

       $dkms_tree
              See   the   section   on   /etc/dkms/framework.conf   for   more
              information.   This variable represents the location of the DKMS
              tree on the local system.  By default this  is  /var/lib/dkms  ,
              but  this value should not be hard-coded into a dkms.conf in the
              event that the local user has changed it on their system.

       $source_tree
              See   the   section   on   /etc/dkms/framework.conf   for   more
              information.   This  variable represents the location where DKMS
              keeps source on the local system.  By default this is /usr/src ,
              but  this value should not be hard-coded into a dkms.conf in the
              event that the local user has changed it on their system.

       $kernel_source_dir
              This variable holds the value of the  location  of  your  kernel
              source      directory.       Usually,      this      will     be
              /lib/modules/$kernelver/build , unless otherwise specified  with
              the --kernelsourcedir option.

DKMS.CONF OVERRIDES

       You  can override the module-provided dkms.conf files. Every time after
       a  dkms.conf file is read, dkms will look for and  read  the  following
       files in order:

       /etc/dkms/<module>.conf
       /etc/dkms/<module>-<module-version>.conf
       /etc/dkms/<module>-<module-version>-<kernel>.conf
       /etc/dkms/<module>-<module-version>-<kernel>-<arch>.conf

       You can use these files to override  settings  in  the  module-provided
       dkms.conf files.

/etc/dkms/framework.conf

       This  configuration  file  controls  how  the  overall  DKMS  framework
       handles.  It is sourced in every time the dkms command is run.   Mainly
       it  can  currently  be  used  to  set  different default values for the
       variables.  $dkms_tree , $source_tree and $install_tree  which  control
       where DKMS looks for its framework.  Note that these variables can also
       be manipulated on the command line with  --dkmstree,  --sourcetree  and
       --installtree options.

dkms_autoinstaller

       This  boot-time  service  automatically  installs  any module which has
       AUTOINSTALL="yes" set in its dkms.conf file.  The service  works  quite
       simply  and  if multiple versions of a module are in your system's DKMS
       tree,  it  will  not  do  anything  and  instead  explain  that  manual
       intervention is required.

MODULES.CONF / MODPROBE.CONF CHANGES

       Changes   that   your   module   will   make  to  /etc/modules.conf  or
       /etc/modprobe.conf     should      be      specified      with      the
       MODULES_CONF_ALIAS_TYPE[#]  ,  the  MODULES_CONF_OBSOLETES[#]  and  the
       MODULES_CONF[#] directive arrays.  These arrays  should  also  be  used
       even if your distro uses /etc/sysconfig/kernel to track kernel modules.

       When  the  first  module  is installed upon the first kernel within the
       user's system, these entries in MODULES_CONF[#] are automatically added
       to /etc/modules.conf and if REMAKE_INITRD is specified, then the user's
       initrd is then remade.  Subsequently, as your modules  are  then  later
       removed   from  the  user's  system,  until  the  final  module/version
       combination is removed from the final kernel version, those  references
       in  modules.conf will remain.  Once the last module/version combination
       is removed, those references are then removed.

       As modules/versions are removed and initrds are remade,  one  of  three
       things will happen if you have specified a MODULES_CONF_ALIAS_TYPE.  If
       no    original_module    exists    for    that    kernel,    and     no
       MODULES_CONF_OBSOLETES  modules  are  found  in  that  kernel  too, the
       modules.conf alias references will temporarily be removed so  that  the
       initrd  will  successfully remake.  Once the initrd is remade, however;
       those references are then  automatically  put  back  into  modules.conf
       (unless  you  are  removing the last instance of the module on the last
       kernel).  However, if  no  original_module  exists,  but  there  is  an
       OBSOLETE  module  found  within  that  kernel,  the  alias reference is
       temporarily shifted to point to the OBSOLETE module so that the  initrd
       can be remade.  After it is remade, it then automatically puts back the
       alias reference (unless you are  removing  the  last  instance  of  the
       module  on  the last kernel).  Lastly, if an original_module does exist
       for the kernel version,  then  modules.conf  is  not  touched  and  all
       references  persist  (even if you are removing the last instance of the
       module on the last kernel).

       Certain module installations might not only require  adding  references
       to  modules.conf  but also require removing conflicting references that
       might  exist  in  the  user's  system.   If  this  is  the  case,   the
       MODULES_CONF_OBSOLETES[#]  directive should be utilized to remove these
       references.  More information about this directive can be found in  the
       DKMS.CONF section of this man page.

       Note  that the end state of your modules.conf file very much depends on
       what kernel modules exist in the final  kernel  you  remove  your  DKMS
       module from.  This is an imperfect system caused by the fact that there
       is only one modules.conf file for every  kernel  on  your  system  even
       though  various  kernels  use  different  modules.  In a perfect world,
       there would be one  modules.conf  file  for  every  kernel  (just  like
       System.map).

CREATING RPMS WHICH UTILIZE DKMS

       See the sample.spec file packaged with DKMS as an example for what your
       RPM spec file might look like.  Creating RPMs which utilize dkms  is  a
       fairly  straight-forward  process.   The  RPM  need only to install the
       source into /usr/src/<module>-<module-version>/ and  then  employ  dkms
       itself  to  do  all  the work of installation.  As such, the RPM should
       first untar the source into this directory.  From here, within the  RPM
       .spec  file,  a  dkms  add  should  be  called  (remember  to  use  the
       --rpm_safe_upgrade flag during  the  add)  followed  by  a  dkms  build
       followed  by  a  dkms  install.   Your  dkms.conf file should be placed
       within the /usr/src/<module>-<module-version>/ directory.

       Under the removal parts of the .spec file, all that needs to be  called
       is   a:   dkms   remove   -m   <module>   -v   <module-version>   --all
       --rpm_safe_upgrade.  Use of the --rpm_safe_upgrade flag  is  imperative
       for  making  sure DKMS and RPM play nicely together in all scenarios of
       using the -Uvh flag with RPM to upgrade dkms enabled packages.  It will
       only function if used during both the add and remove actions within the
       same RPM spec file. Its use makes  sure  that  when  upgrading  between
       different  releases  of an RPM for the same <module-version>, DKMS does
       not  do  anything  dumb  (eg.  it  ensures  a   smooth   upgrade   from
       megaraid-2.09-5.noarch.rpm to megaraid-2.09-6.noarch.rpm).

       It  should  be  noted  that a binary RPM which contains source is not a
       traditional practice.  However, given the benefits of dkms it hopefully
       will  become  so.   As  the  RPM  created  which  utilizes  dkms is not
       architecture specific, BuildArch: noarch should  be  specified  in  the
       .spec  file  to  indicate  that  the package can work regardless of the
       system architecture.  Also note that DKMS RPM upgrades (-U option) will
       automatically work because of the structure of the dkms tree.

       Lastly,   as  a  matter  of  convention,  you  should  name  your  RPM:
       <package>-<version>-<rpm-version>dkms.noarch.rpm.   The  word  dkms  as
       part  of  the  rpm-version signifies that the RPM works within the DKMS
       framework.

AUTHOR

       Gary Lerhaupt

WEBPAGE

       http://linux.dell.com/dkms

WHITE-PAPERS

       http://linux.dell.com/dkms/dkms-ols2004.pdf

       http://www.dell.com/downloads/global/power/1q04-ler.pdf

       http://www.linuxjournal.com/article.php?sid=6896

MAILING-LIST

       dkms-devel@dell.com
       http://lists.us.dell.com/mailman/listinfo/dkms-devel

REFERENCES

       Kernel Module Packages http://kerneldrivers.org

       Novell Kernel Module Packages http://www.suse.de/~agruen/KMPM

       Fedora               Kernel               Module               Packages
       http://fedoraproject.org/wiki/Extras/KernelModuleProposal