dkms
Dynamic Kernel Module Support
Synopsis
dkms
[action] [options]
[module/module-version] [/path/to/source-tree]
[/path/to/tarball.tar]
[/path/to/driver.rpm]
add an example, a script, a trick and tips
examples
source
dkms add acpi_call/1.0.0 acpi_call-dkms
dkms build acpi_call/1.0.0
dkms install acpi_call/1.0.0
source
sudo dkms install vboxhost/4.2.12
sudo modprobe vboxdrv
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.
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.
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.
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.
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 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.
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.
mailing list
dkms-devel[:at:]dell[:dot:]com
http://lists.us.dell.com/mailman/listinfo/dkms-devel
modules conf
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).
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.
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
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
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.
etc
author
Gary
Lerhaupt