1DKMS(8) System Manager's Manual DKMS(8)
2
6 dkms - Dynamic Kernel Module Support
7
9 dkms [action] [options]
10
12 dkms is a framework which allows kernel modules to be dynamically built
13 for each kernel on your system in a simplified and organized fashion.
14
16 add Adds a module/version combination to the tree for builds and
17 installs. Requires source in /usr/src/<module>-<module-ver‐
18 sion>/ as well as a properly formatted dkms.conf file.
19 remove Removes a module/version or module/version/kernel combination
21 from the tree. If the modules is currently installed, it first
22 uninstalls it and if applicable, will replace it with its origi‐
23 nal_module. Use the --all option in order to remove all
24 instances for every kernel at once.
25 build Builds the specified module/version combo for the specified ker‐
27 nel. If no kernel is specified it builds for the currently run‐
28 ning kernel. All builds occur in the directory
29 /var/lib/dkms/<module>/<module-version>/build/.
30 install
32 Installs a built module/version combo onto the kernel it was
33 built for. If the kernel option is not specified it assumes the
34 currently running kernel.
35 uninstall
37 Uninstalls an installed module/version combo from the kernel it
38 was installed upon. After uninstall completion, the driver will
39 be left in the built state. To completely remove a driver, the
40 remove action should be utilized.
41 match Match installs modules onto the specified kernel by looking at
43 the configuration of the specified templatekernel. Every module
44 that is installed on the templatekernel within dkms is then
45 installed on that specified kernel.
46 mkdriverdisk
48 Creates a floppy driver disk image for use when updated drivers
49 are needed to install an OS. Currently, the supported distribu‐
50 tions are redhat, suse and UnitedLinux. For Red Hat driver
51 disks, necessary driver disk files are looked for in the red‐
52 hat_driver_disk subdirectory of your module source directory.
53 You must specify the distro while using this action. Driver
54 disks can be made for single kernels or can be made to support
55 multiple kernels. To create a driver disk image with modules
56 for multiple kernels, just specify multiple -k parameters on the
57 command line (-k kernel1 -k kernel2 -a arch1 -a arch2).
58 Red Hat began supporting multi-arched driver disks in RHEL3. To
60 force creation of a driver disk with arch information, specify
61 -d redhat2 or if you specify multiple architectures on the com‐
62 mand-line and use -d redhat , DKMS will create a version 2
63 driver disk. By specifying -d redhat1 , you can force a version
64 1 driver disk image.
65 Note that redhat1 driver disks actually supported multiple
67 architectures when the second arch was i386 and the kernel mod‐
68 ule was for the BOOT kernel. DKMS allows for this, and as such
69 you can create a redhat1 style driver disk if the only other
70 arch is i386 and the kernel name ends in BOOT.
71 See http://people.redhat.com/dledford for more information on
73 the Red Hat driver disk standards and which files are necessary
74 to make a driver disk.
75 Fedora Core 5 and higher, RHEL5 and higher require DKMS version
77 2.0.14 or higher to generate a proper driver disk image.
78 For suse/UnitedLinux driver disks, /usr/share/YaST2/modules/Ven‐
80 dor.ycp will also be copied to the driver disk; no other files
81 are needed. However, for these distros, you must specify a -r
82 release. For SuSE 9.1, it would be -d suse -r 9.1. For SLES9, it
83 would be -d suse -r sles9.
84 By default the disk image it creates is 1440 (k) in size. This
86 can be overridden by specifying a different --size #### which
87 should should be given as a number in kilobytes divisible by 20.
88 You may have more content than will fit on a floppy. Therefore,
90 DKMS can now generate image files of different types.
91 --media=floppy (default) to generate a floppy disk image, or
92 --media=iso to generate a CD-ROM ISO file, or --media=tar to
93 generate a tar file.
94 You may copy the floppy or ISO image file to a USB key to be
96 used with OS installer.
97 mktarball
101 Creates a tarball archive for the specified module/version of
102 all files in the DKMS tree for that module/version combination.
103 This includes the source and any built modules for kernels in
104 the tree (as specified). Otherwise, you can specify a singular
105 kernel to archive only, or multiple kernels to archive (-k ker‐
106 nel1 -k kernel2 -a arch1 -a arch2). Optionally, you can use
107 --archive to specify the name (with no preceding path) that you
108 would like this tarball to have. You can also specify --bina‐
109 ries-only if you want the resultant tarball not to include the
110 module source. Likewise, --source-only can be used to specify
111 that no prebuilt binaries should be included in the tarball. In
112 general, mktarball is great for systems management purposes as
113 you can build your driver on just one system and then use ldtar‐
114 ball on all of your other systems to get the same built modules
115 loaded without having to wait for anything to compile.
116 ldtarball
118 This takes a tarball made from the mktarball command and speci‐
119 fied with the --archive option and loads it into your DKMS tree.
120 This will leave any newly added modules in the built state and
121 dkms install should then be called to install any of them. If
122 files already exist where ldtarball is attempting to place them,
123 it will warn and not copy over them. The --force option should
124 be used to override this.
125 mkrpm This action allows you to create an RPM package for a specified
127 module / version. It uses a template .spec file found in
128 /etc/dkms/template-dkms-mkrpm.spec as the basis for the RPM.
129 Alternatively, if DKMS finds a file called /usr/src/<mod‐
130 ule>-<module-version>/<module>-dkms-mkrpm.spec it will use that
131 .spec file instead. In general, a DKMS tarball is placed inside
132 the contents of this RPM, and the RPM itself calls various DKMS
133 commands to load this tarball, build and install modules on the
134 end user's system. If you do not want your RPM to contain any
135 prebuilt binaries, be sure to specify --source-only in the mkrpm
136 command.
137 mkdeb This action allows you to create a debian binary package for a
139 specified module / version. It uses a template debian directory
140 found in /etc/dkms/template-dkms-mkdeb as the basis for the
141 package. Alternatively, if DKMS finds a file called
142 /usr/src/<module>-<module-version>/<module>-dkms-mkdeb it will
143 use that folder instead. In general, a DKMS tarball is placed
144 inside the contents of this package, and the package itself
145 calls various DKMS commands to load this tarball, build and
146 install modules on the end user's system. If you do not want
147 your debian package to contain any prebuilt binaries, be sure to
148 specify --source-only in the mkdeb command.
149 mkdsc This action allows you to create a debian source package for a
151 specified module / version. It will create a .tar.gz, and a
152 .dsc. All options supported by mkdeb are supported by it. The
153 main difference in it's usage is that it will look in
154 /etc/dkms/template-dkms-mkdsc as the basis for the package.
155 Alternatively, if DKMS finds a file called /usr/src/<mod‐
156 ule>-<module-version>/<module>-dkms-mkdsc it will use that
157 folder instead. If you do not want your debian source package to
158 contain any prebuilt binaries, be sure to specify --source-only
159 in the mkdsc command.
160 mkkmp This action allows you to create an Kernel Module Package source
162 RPM for a specified module / version. It uses the .spec file
163 specified by --spec=specfile else $module-kmp.spec as the basis
164 for the RPM. The generated source RPM may then be built using
165 SuSE's build.rpm or Fedora/RHEL's mock chroot environments. See
166 http://kerneldrivers.org/ for more details on KMPs.
167 status Returns the current status of modules, versions and kernels
169 within the tree as well as whether they have been added, built
170 or installed. Status can be shown for just a certain module, a
171 certain kernel, a module/version combination or a module/ver‐
172 sion/kernel combination.
173
175 -m <module>
176 The name of the module.
177 -v <module-version>
179 The version of the module to execute the specified action upon.
180 -k <kernel-version>
182 The kernel to perform the action upon. You can specify multiple
183 kernel versions on the command line by repeating the -k argument
184 with a different kernel name. However, not all actions support
185 multiple kernel versions (it will error out in this case).
186 -a, --arch
188 The system architecture to perform the action upon. If not
189 specified, it assumes the arch of the currently running system
190 (`uname -m`). You can specify multiple arch parameters on the
191 same command line by repeating the -a argument with a different
192 arch name. When multiple architectures are specified, there
193 must be a 1:1 relationship between -k arguments to -a arguments.
194 DKMS will then assume the first -a argument aligns with the
195 first -k kernel and so on for the second, third, etc.
196 For example, if you were to specify: -k kernel1 -k kernel2 -a
198 i386 -k kernel3 -a i686 -a x86_64, DKMS would process this as:
199 kernel1-i386, kernel2-i686, kernel3-x86_64.
200 -q, --quiet
202 Quiet.
203 -V, --version
205 Prints the currently installed version of dkms and exits.
206 -c <dkms.conf-location>
208 The location of the dkms.conf file. This is needed for the add
209 action and if not specified, it is assumed to be located in
210 /usr/src/<module>-<module-version>/. See below for more infor‐
211 mation on the format of dkms.conf.
212 -d, --distro
214 The distribution being used. This is only currently needed for
215 mkdriverdisk. The supported distros are redhat, suse and Unit‐
216 edLinux. See the sections on mkdriverdisk and mkkmp for more
217 information.
218 -r, --release
220 The release being used. This is only currently used for
221 mkdriverdisk and is only used for suse or UnitedLinux distros
222 (eg. -r 9.1). It is used in the internal makeup of the
223 driverdisk.
224 --size The size of the driver disk image to be created. By default,
226 this value is set at 1440. Any different size should be given
227 as an integer value only, should be divisible by 20 and should
228 represent the number of kilobytes of the image size you desire.
229 --config <kernel-.config-location>
231 During a build this option is used to specify an alternate loca‐
232 tion for the kernel .config file which was used to compile that
233 kernel. Normally, dkms uses the Red Hat standard location and
234 config filenames located in /usr/src/linux-<kernel>/configs/.
235 If the config for the kernel that you are building a module for
236 is not located here or does not have the expected name in this
237 location, you will need to tell dkms where the necessary .config
238 can be found so that your kernel can be properly prepared for
239 the module build.
240 --archive <tarball-location>
242 This option is used during a ldtarball action to specify the
243 location of the tarball you wish to load into your DKMS tree.
244 --templatekernel <kernel-version>
246 This option is required for the action: match. Match will look
247 at the templatekernel specified and install all of the same mod‐
248 ule/version combinations on the other kernel.
249 --force
251 This option can be used in conjunction with ldtarball to force
252 copying over of extant files.
253 --binaries-only
255 This option can be used in conjunction with mktarball in order
256 to create a DKMS tarball which does not contain the source for
257 the module within it. This can be helpful in reducing the size
258 of the tarball if you know that the system which this tarball
259 will be loaded upon already has the source installed. In order
260 to load a tarball made as binaries-only you must have the module
261 source in that systems DKMS tree. If you do not, DKMS will
262 refuse to load a binaries-only tarball.
263 --source-only
265 This option can be used in conjunction with mktarball or mkrpm
266 or mkdeb in order to create a DKMS tarball which does not con‐
267 tain any prebuilt kernel module binaries within it. This is
268 helpful if you simply want to easily tar up your source but
269 don't want anything prebuilt within it. Likewise, if you are
270 using mkrpm but do not want the RPM you create to have any pre‐
271 built modules within it, passing this option will keep its
272 internal DKMS tarball from containing any prebuilt modules.
273 --all This option can be used to automatically specify all relevant
275 kernels/arches for a module/module-version. This is useful for
276 things like remove , mktarball , etc. This saves the trouble of
277 having to actually specify -k kernel1 -a arch1 -k kernel2 -a
278 arch2 for every kernel you have built your module for.
279 --no-prepare-kernel
281 This option keeps DKMS from first preparing your kernel before
282 building a module for it. Generally, this option should not be
283 used so as to ensure that modules are compiled correctly.
284 --no-clean-kernel
286 This option keeps DKMS from cleaning your kernel source tree
287 after a build.
288 --kernelsourcedir <kernel-source-directory-location>
290 Using this option you can specify the location of your kernel
291 source directory. Most likely you will not need to set this if
292 your kernel source is accessible via /lib/modules/$kernel_ver‐
293 sion/build.
294 --directive <"cli-directive=cli-value">
296 Using this option, you can specify additional directives from
297 the command line. The --directive option can be used multiple
298 times on the same command-line to specify multiple additional
299 command line directives.
300 --rpm_safe_upgrade
302 This flag should be used when packaging DKMS enabled modules in
303 RPMs. It should be specified during both the add and remove
304 actions in the RPM spec to ensure that DKMS and RPM behave cor‐
305 rectly in all scenarios when upgrading between various versions
306 of a dkms enabled module RPM package. See the sample.spec file
307 for an example or read more in the section below on Creating
308 RPMs Which Utilize DKMS.
309 --spec specfile
311 This option is used by the mkkmp action to specify which RPM
312 spec file to use when generating the KMP. specfile will be
313 sought in the module source directory.
314 --dkmstree path/to/place
316 Provides a destination tree for building and installing modules
317 to. Useful in cases that you don't want to contaminate a system
318 when using solely for building.
319 --sourcetree path/to/place
321 Provides a location to build a DKMS package from. Useful for
322 systems that you may not have root access, but would still like
323 to be able to build DKMS packages.
324 --installtree path/to/place
326 Provides a location to place modules when a dkms install command
327 is issued.
328 --legacy-postinst=[0|1]
330 Includes a legacy postinstall script so that a DEB or RPM built
331 by DKMS can be used on versions prior than DKMS 2.1. This
332 option currently defaults to 1.
333 --dkmsframework path/to/file
335 A supplemental configuration file to the system-wide dkms frame‐
336 work, typically located in /etc/dkms/framework.conf. All option
337 that are normally provided on a command line can be provided in
338 this file.
339
341 During the first install of a module for a <kernelversion>, dkms will
342 search /lib/modules/<kernelversion> for a pre-existing module of the
343 same name. If one is found, it will automatically be saved as an "orig‐
344 inal_module" so that if the newer module is later removed, dkms will
345 put the original module back in its place. Currently, DKMS searches
346 for these original modules with first preference going to modules
347 located in /lib/modules/<kernelversion>/updates/ followed by $DEST_MOD‐
348 ULE_LOCATION (as specified in dkms.conf ). If one cannot be found in
349 either location, a find will be used to locate one for that kernel. If
350 none are found, then during a later uninstall, your kernel will not
351 have that module replaced.
352 If more than one is found, then the first one located (by preference
354 indicated above) will be considered the "original_module". As well,
355 all copies of the same-named module will be removed from your kernel
356 tree and placed into /var/lib/dkms/<module>/original_module/$ker‐
357 nelver/collisions so that they can be *manually* accessible later. DKMS
358 will never actually do anything with the modules found underneath the
359 /collisions directory, and they will be stored there until you manually
360 delete them.
361
363 When performing an add , a proper dkms.conf file must be found. A
364 properly formatted conf file is essential for communicating to dkms how
365 and where the module should be installed. While not all the directives
366 are required, providing as many as possible helps to limit any ambigu‐
367 ity. Note that the dkms.conf is really only a shell-script of variable
368 definitions which are then sourced in by the dkms executable (of the
369 format, DIRECTIVE="directive text goes here"). As well, the directives
370 are case-sensitive and should be given in ALL CAPS.
371 It is important to understand that many of the DKMS directives are
373 arrays whose index values are tied together. These array associations
374 can be considered families, and there are currently four such families
375 of directive arrays. MAKE[#] and MAKE_MATCH[#] make up one family.
376 PATCH[#] and PATCH_MATCH[#] make up the second family. The third and
377 largest family consists of BUILT_MODULE_NAME[#], BUILT_MODULE_LOCA‐
378 TION[#], DEST_MODULE_NAME[#], DEST_MODULE_LOCATION[#], MOD‐
379 ULES_CONF_ALIAS_TYPE[#], MODULES_CONF_OBSOLETES[#], MODULES_CONF_OBSO‐
380 LETE_ONLY[#] and STRIP[#]. The fourth family is made up of only MOD‐
381 ULES_CONF[#]. When indexing these arrays when creating your dkms.conf,
382 each family should start at index value 0.
383 MAKE[#]=
385 The MAKE directive array tells DKMS which make command should be
386 used for building your module. The default make command should
387 be put into MAKE[0]. Other entries in the MAKE array will only
388 be used if their corresponding entry in MAKE_MATCH[#] matches,
389 as a regular expression (using egrep), the kernel that the mod‐
390 ule is being built for. Note that if no value is placed in
391 MAKE_MATCH[#] for any MAKE[#] where # > 0, then that MAKE direc‐
392 tive is ignored. MAKE_MATCH[0] is optional and if it is popu‐
393 lated, it will be used to determine if MAKE[0] should be used to
394 build the module for that kernel. If multiple MAKE_MATCH direc‐
395 tives match against the kernel being built for, the last match‐
396 ing MAKE[#] will be used to build your module. If no MAKE direc‐
397 tive is specified or if no MAKE_MATCH matches the kernel being
398 built for, DKMS will attempt to use a generic MAKE command to
399 build your module.
400 MAKE_MATCH[#]=
402 See the above entry on MAKE[#] directives. This array should be
403 populated with regular expressions which, when matched against
404 the kernel being built for, will tell DKMS to use the corre‐
405 sponding make command in the MAKE[#] directive array to build
406 your module.
407 BUILT_MODULE_NAME[#]=
409 This directive gives the name of the module just after it is
410 built. If your DKMS module package contains more than one mod‐
411 ule to install, this is a required directive for all of the mod‐
412 ules. This directive should explicitly not contain any trailing
413 ".o" or ".ko". Note that for each module within a dkms package,
414 the numeric value of # must be the same for each of BUILT_MOD‐
415 ULE_NAME, BUILT_MODULE_LOCATION, DEST_MODULE_NAME and DEST_MOD‐
416 ULE_LOCATION and that the numbering should start at 0 (eg.
417 BUILT_MODULE_NAME[0]="qla2200" BUILT_MODULE_NAME[1]="qla2300").
418 BUILT_MODULE_LOCATION[#]=
420 This directive tells DKMS where to find your built module after
421 it has been built. This pathname should be given relative to
422 the root directory of your source files (where your dkms.conf
423 file can be found). If unset, DKMS expects to find your
424 BUILT_MODULE_NAME[#] in the root directory of your source files.
425 Note that for each module within a dkms package, the numeric
426 value of # must be the same for each of BUILT_MODULE_NAME,
427 BUILT_MODULE_LOCATION, DEST_MODULE_NAME and DEST_MODULE_LOCATION
428 and that the numbering should start at 0 (eg. BUILT_MODULE_LOCA‐
429 TION[0]="some/dir/" BUILT_MODULE_LOCATION[1]="other/dir/").
430 DEST_MODULE_NAME[#]=
432 This directive can be used to specify the name of the module as
433 it should be installed. This will rename the module from
434 BUILT_MODULE_NAME[#] to DEST_MODULE_NAME[#]. This directive
435 should explicitly not contain any trailing ".o" or ".ko". If
436 unset, it is assumed to be the same value as BUILT_MOD‐
437 ULE_NAME[#]. Note that for each module within a dkms package,
438 the numeric value of # must be the same for each of BUILT_MOD‐
439 ULE_NAME, BUILT_MODULE_LOCATION, DEST_MODULE_NAME and DEST_MOD‐
440 ULE_LOCATION and that the numbering should start at 0 (eg.
441 DEST_MODULE_NAME[0]="qla2200_6x" DEST_MOD‐
442 ULE_NAME[1]="qla2300_6x").
443 DEST_MODULE_LOCATION[#]=
445 This directive specifies the destination where a module should
446 be installed to, once compiled. It also is used for finding
447 original_modules. This is a required directive, except as noted
448 below. This directive must start with the text "/kernel" which
449 is in reference to /lib/modules/<kernelversion>/kernel. Note
450 that for each module within a dkms package, the numeric value of
451 # must be the same for each of BUILT_MODULE_NAME, BUILT_MOD‐
452 ULE_LOCATION, DEST_MODULE_NAME and DEST_MODULE_LOCATION and that
453 the numbering should start at 0 (eg. DEST_MODULE_LOCA‐
454 TION[0]="/kernel/drivers/something/" DEST_MODULE_LOCA‐
455 TION[1]="/kernel/drivers/other/").
456 DEST_MODULE_LOCATION is ignored on Fedora Core 6 and higher, Red
458 Hat Enterprise Linux 5 and higher, Novell SuSE Linux Enterprise
459 Server 10 and higher, Novell SuSE Linux 10.0 and higher, and
460 Ubuntu. Instead, the proper distribution-specific directory is
461 used.
462 MODULES_CONF_ALIAS_TYPE[#]=
464 This directive array specifies how your modules should be
465 aliased in /etc/modules.conf when your module is installed.
466 This is done in an intelligent fashion so if DKMS detects an
467 already existing reference in modules.conf, it won't add a new
468 line. If it is not detected, it will add it to the modules.conf
469 as the last alias number for that alias type (eg. if MOD‐
470 ULES_CONF_ALIAS_TYPE="scsi_hostadapter", no alias currently
471 exists for that module and the last scsi_hostadapter reference
472 is 6, then your module will be added as "scsi_hostadapter7").
473 Common values for this directive include: scsi_hostadapter ,
474 sound-slot- and eth. Note that the numeric value of # is tied
475 to the index of BUILD_MODULE_NAME, BUILT_MODULE_LOCATION,
476 DEST_MODULE_NAME and DEST_MODULE_LOCATION. The index is also
477 tied to MODULES_CONF_OBSOLETES.
478 MODULES_CONF_OBSOLETES[#]=
480 This directive array tells DKMS what modules.conf alias refer‐
481 ences are obsoleted by the module you are installing. If your
482 module obsoletes more than one module, this directive should be
483 a comma-delimited list of those modules that are obsoleted (eg.
484 for megaraid2, MODULES_CONF_OBSO‐
485 LETES[0]="megaraid,megaraid_2002"). When you are installing your
486 module, DKMS ensures that any entries in /etc/modules.conf with
487 the same MODULES_CONF_ALIAS_TYPE are changed over to the new
488 module name. When you are uninstalling your module, depending
489 on the modules in your /lib/modules tree, DKMS will take differ‐
490 ent actions. If you kernel has an original_module, then mod‐
491 ules.conf will not be touched and the non-obsolete reference
492 will remain. If the kernel does not have an original_module but
493 does have one of the obsolete modules, it will replace those
494 references with the first obsolete module name in the
495 comma-delimited list that is also in that kernel (thus, your
496 obsolete list should be prioritized from left to right). If no
497 original_module or obsolete modules are found within the kernel,
498 the alias entry is removed all-together. Note that the numeric
499 value of # is tied to the index of BUILD_MODULE_NAME, BUILT_MOD‐
500 ULE_LOCATION, DEST_MODULE_NAME and DEST_MODULE_LOCATION. The
501 index is also tied to MODULES_CONF_ALIAS_TYPE.
502 MODULES_CONF_OBSOLETE_ONLY[#]=
504 If set to yes , this directive will tell DKMS to only modify
505 /etc/modules.conf if it finds within it an obsolete reference as
506 specified in the corresponding value of MODULES_CONF_OBSO‐
507 LETES[#] array directive.
508 STRIP[#]=
510 By default strip is considered to be "yes". If set to "no",
511 DKMS will not run strip -g against your built module to remove
512 debug symbols from it.
513 PACKAGE_NAME=
515 This directive is used to give the name associated with the
516 entire package of modules. This is the same name that is used
517 with the -m option when building, adding, etc. and may not nec‐
518 essarily be the same as the MODULE_NAME. This directive must be
519 present in every dkms.conf.
520 PACKAGE_VERSION=
522 This directive is used to give the version associated with the
523 entire package of modules being installed within that dkms pack‐
524 age. This directive must be present in every dkms.conf.
525 CLEAN= CLEAN specifies the make clean command to be used to clean up
527 both before and after building the module. If unset, it is
528 assumed to be "make clean".
529 REMAKE_INITRD=
531 This directive specifies whether your initrd should be remade
532 after the module is installed onto the kernel. Any text after
533 the first character is ignored and if the first character is not
534 a "y" or a "Y", it is assumed that REMAKE_INITRD="no".
535 UDEV_TRIGGER=
537 This optional directive specifies, if the udev daemon will be
538 get a trigger event after the module is installed for your cur‐
539 rently running kernel. Because this udev trigger might have some
540 unfriendly side effects on some Linux Systems, you can now dis‐
541 able this trigger, if your driver does not need it anyway.
542 UDEV_TRIGGER=yes is assumed as the default, although this direc‐
543 tive may not be given. This ensures backward compatibility to
544 older DKMS releases. Any text after the first character is
545 ignored and if the first character is not a "n" or a "N", it is
546 assumed that UDEV_TRIGGER="yes".
547 MODULES_CONF[#]=
549 This directive array specifies what static configuration text
550 lines need to be added into /etc/modules.conf for your module.
551 See the section on MODULES.CONF CHANGES for more information
552 regarding the implications of modifying /etc/modules.conf
553 OBSOLETE_BY=
555 This directive allows you to specify a kernel version that obso‐
556 letes the necessity for this particular DKMS module. This can
557 be specified as a particular upstream kernel or an ABI bump of a
558 kernel. For example, "2.6.24" would be an upstream kernel and
559 "2.6.24-16" would represent an ABI bump for a kernel. Both are
560 valid in this area.
561 Please avoid the use of OBSOLETE_BY wherever possible. It's use
563 indicates a lack of proper module versioning using MODULE_VER‐
564 SION() tags in the module source itself. It is better to fix
565 the MODULE_VERSION() tags than use OBSOLETE_BY. This also
566 introduces a implicit distribution/version dependency on the
567 package, as the value of OBSOLETE_BY is meaningful only in the
568 context of a single distribution/version.
569 If you feel you must use it, please use as such in dkms.conf:
571 ubuntu_804="Ubuntu
573 8.04"
574 if [ -x /usr/bin/lsb_release ]; then
575 if [ "$(/usr/bin/lsb_release -sir)" == "${ubuntu_804}" ];
576 then
577 OBSOLETE_BY="2.6.25"
578 fi
579 fi
580 PATCH[#]=
583 Use the PATCH directive array to specify patches which should be
584 applied to your source before a build occurs. All patches are
585 expected to be in -p1 format and are applied with the patch -p1
586 command. Each directive should specify the filename of the
587 patch to apply, and all patches must be located in the patches
588 subdirectory of your source directory ( /usr/src/<module>-<mod‐
589 ule-version>/patches/ ). If any patch fails to apply, the build
590 will be halted and the rejections can be inspected in
591 /var/lib/dkms/<module>/<module-version>/build/. If a PATCH
592 should only be applied conditionally, the PATCH_MATCH[#] array
593 should be used, and a corresponding regular expression should be
594 placed in PATCH_MATCH[#] which will alert dkms to only use that
595 PATCH[#] if the regular expression matches the kernel which the
596 module is currently being built for.
597 PATCH_MATCH[#]=
599 See the above description for PATCH[#] directives. If you only
600 want a patch applied in certain scenarios, the PATCH_MATCH array
601 should be utilized by giving a regular expression which matches
602 the kernels you intend the corresponding PATCH[#] to be applied
603 to before building that module.
604 AUTOINSTALL=
606 If this directive is set to yes then the service
607 /etc/rc.d/init.d/dkms_autoinstaller will automatically try to
608 install this module on any kernel you boot into. See the sec‐
609 tion on dkms_autoinstaller for more information.
610 BUILD_EXCLUSIVE_KERNEL=
612 This optional directive allows you to specify a regular expres‐
613 sion which defines the subset of kernels which DKMS is allowed
614 to build your module for. If the kernel being built for does
615 not match against this regular expression, the dkms build will
616 error out. For example, if you set it as ="^2.4.*", your module
617 would not be built for 2.6 kernels.
618 BUILD_EXCLUSIVE_ARCH=
620 This optional directive functions very similarly to BUILD_EXCLU‐
621 SIVE_KERNEL except that it matches against the kernel architec‐
622 ture. For example, if you set it to ="i.86", your module would
623 not be built for ia32e, x86_64, amd64, s390, etc.
624 POST_ADD=
626 The name of the script to be run after an add is performed. The
627 path should be given relative to the root directory of your
628 source.
629 POST_BUILD=
631 The name of the script to be run after a build is performed. The
632 path should be given relative to the root directory of your
633 source.
634 POST_INSTALL=
636 The name of the script to be run after an install is performed.
637 The path should be given relative to the root directory of your
638 source.
639 POST_REMOVE=
641 The name of the script to be run after a remove is performed.
642 The path should be given relative to the root directory of your
643 source.
644 PRE_BUILD=
646 The name of the script to be run before a build is performed.
647 The path should be given relative to the root directory of your
648 source.
649 PRE_INSTALL=
651 The name of the script to be run before an install is performed.
652 The path should be given relative to the root directory of your
653 source. If the script exits with a non-zero value, the install
654 will be aborted. This is typically used to perform a custom
655 version comparison.
656 DKMS.CONF VARIABLES
659 Within your dkms.conf file, you can use certain variables which
660 will be replaced at run-time with their values.
661 $kernelver
663 This variable can be used within a directive definition and dur‐
664 ing use, the actual kernel version in question will be substi‐
665 tuted in its place. This is especially useful in MAKE commands
666 when specifying which INCLUDE statements should be used when
667 compiling your module (eg. MAKE="make all INCLUDEDIR=/lib/mod‐
668 ules/${kernelver}/build/include").
669 $dkms_tree
671 See the section on /etc/dkms/framework.conf for more informa‐
672 tion. This variable represents the location of the DKMS tree on
673 the local system. By default this is /var/lib/dkms , but this
674 value should not be hard-coded into a dkms.conf in the event
675 that the local user has changed it on their system.
676 $source_tree
678 See the section on /etc/dkms/framework.conf for more informa‐
679 tion. This variable represents the location where DKMS keeps
680 source on the local system. By default this is /usr/src , but
681 this value should not be hard-coded into a dkms.conf in the
682 event that the local user has changed it on their system.
683 $kernel_source_dir
685 This variable holds the value of the location of your kernel
686 source directory. Usually, this will be /lib/modules/$ker‐
687 nelver/build , unless otherwise specified with the --kernel‐
688 sourcedir option.
689
691 This configuration file controls how the overall DKMS framework han‐
692 dles. It is sourced in every time the dkms command is run. Mainly it
693 can currently be used to set different default values for the vari‐
694 ables. $dkms_tree , $source_tree and $install_tree which control where
695 DKMS looks for its framework. Note that these variables can also be
696 manipulated on the command line with --dkmstree, --sourcetree and
697 --installtree options.
698
700 This boot-time service automatically installs any module which has
701 AUTOINSTALL="yes" set in its dkms.conf file. The service works quite
702 simply and if multiple versions of a module are in your system's DKMS
703 tree, it will not do anything and instead explain that manual interven‐
704 tion is required.
705
707 Changes that your module will make to /etc/modules.conf or /etc/mod‐
708 probe.conf should be specified with the MODULES_CONF_ALIAS_TYPE[#] ,
709 the MODULES_CONF_OBSOLETES[#] and the MODULES_CONF[#] directive arrays.
710 These arrays should also be used even if your distro uses /etc/syscon‐
711 fig/kernel to track kernel modules.
712 When the first module is installed upon the first kernel within the
714 user's system, these entries in MODULES_CONF[#] are automatically added
715 to /etc/modules.conf and if REMAKE_INITRD is specified, then the user's
716 initrd is then remade. Subsequently, as your modules are then later
717 removed from the user's system, until the final module/version combina‐
718 tion is removed from the final kernel version, those references in mod‐
719 ules.conf will remain. Once the last module/version combination is
720 removed, those references are then removed.
721 As modules/versions are removed and initrds are remade, one of three
723 things will happen if you have specified a MODULES_CONF_ALIAS_TYPE. If
724 no original_module exists for that kernel, and no MODULES_CONF_OBSO‐
725 LETES modules are found in that kernel too, the modules.conf alias ref‐
726 erences will temporarily be removed so that the initrd will success‐
727 fully remake. Once the initrd is remade, however; those references are
728 then automatically put back into modules.conf (unless you are removing
729 the last instance of the module on the last kernel). However, if no
730 original_module exists, but there is an OBSOLETE module found within
731 that kernel, the alias reference is temporarily shifted to point to the
732 OBSOLETE module so that the initrd can be remade. After it is remade,
733 it then automatically puts back the alias reference (unless you are
734 removing the last instance of the module on the last kernel). Lastly,
735 if an original_module does exist for the kernel version, then mod‐
736 ules.conf is not touched and all references persist (even if you are
737 removing the last instance of the module on the last kernel).
738 Certain module installations might not only require adding references
740 to modules.conf but also require removing conflicting references that
741 might exist in the user's system. If this is the case, the MOD‐
742 ULES_CONF_OBSOLETES[#] directive should be utilized to remove these
743 references. More information about this directive can be found in the
744 DKMS.CONF section of this man page.
745 Note that the end state of your modules.conf file very much depends on
747 what kernel modules exist in the final kernel you remove your DKMS mod‐
748 ule from. This is an imperfect system caused by the fact that there is
749 only one modules.conf file for every kernel on your system even though
750 various kernels use different modules. In a perfect world, there would
751 be one modules.conf file for every kernel (just like System.map).
752
754 See the sample.spec file packaged with DKMS as an example for what your
755 RPM spec file might look like. Creating RPMs which utilize dkms is a
756 fairly straight-forward process. The RPM need only to install the
757 source into /usr/src/<module>-<module-version>/ and then employ dkms
758 itself to do all the work of installation. As such, the RPM should
759 first untar the source into this directory. From here, within the RPM
760 .spec file, a dkms add should be called (remember to use the
761 --rpm_safe_upgrade flag during the add) followed by a dkms build fol‐
762 lowed by a dkms install. Your dkms.conf file should be placed within
763 the /usr/src/<module>-<module-version>/ directory.
764 Under the removal parts of the .spec file, all that needs to be called
766 is a: dkms remove -m <module> -v <module-version> --all
767 --rpm_safe_upgrade. Use of the --rpm_safe_upgrade flag is imperative
768 for making sure DKMS and RPM play nicely together in all scenarios of
769 using the -Uvh flag with RPM to upgrade dkms enabled packages. It will
770 only function if used during both the add and remove actions within the
771 same RPM spec file. Its use makes sure that when upgrading between dif‐
772 ferent releases of an RPM for the same <module-version>, DKMS does not
773 do anything dumb (eg. it ensures a smooth upgrade from
774 megaraid-2.09-5.noarch.rpm to megaraid-2.09-6.noarch.rpm).
775 It should be noted that a binary RPM which contains source is not a
777 traditional practice. However, given the benefits of dkms it hopefully
778 will become so. As the RPM created which utilizes dkms is not archi‐
779 tecture specific, BuildArch: noarch should be specified in the .spec
780 file to indicate that the package can work regardless of the system
781 architecture. Also note that DKMS RPM upgrades (-U option) will auto‐
782 matically work because of the structure of the dkms tree.
783 Lastly, as a matter of convention, you should name your RPM: <pack‐
785 age>-<version>-<rpm-version>dkms.noarch.rpm. The word dkms as part of
786 the rpm-version signifies that the RPM works within the DKMS framework.
787
789 Gary Lerhaupt
790
792 http://linux.dell.com/dkms
793
795 http://linux.dell.com/dkms/dkms-ols2004.pdf
796 http://www.dell.com/downloads/global/power/1q04-ler.pdf
798 http://www.linuxjournal.com/article.php?sid=6896
800
802 dkms-devel@dell.com http://lists.us.dell.com/mail‐
803 man/listinfo/dkms-devel
804
806 Kernel Module Packages http://kerneldrivers.org
807 Novell Kernel Module Packages http://www.suse.de/~agruen/KMPM
809 Fedora Kernel Module Packages http://fedoraproject.org/wiki/Extras/Ker‐
811 nelModuleProposal
812Version 2.0.20 June 2008 DKMS(8)