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 /var/dkms/<mod‐
29 ule>/<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 package for a speci‐
139 fied 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 mkkmp This action allows you to create an Kernel Module Package source
151 RPM for a specified module / version. It uses the .spec file
152 specified by --spec=specfile else $module-kmp.spec as the basis
153 for the RPM. The generated source RPM may then be built using
154 SuSE's build.rpm or Fedora/RHEL's mock chroot environments. See
155 http://kerneldrivers.org/ for more details on KMPs.
156 status Returns the current status of modules, versions and kernels
158 within the tree as well as whether they have been added, built
159 or installed. Status can be shown for just a certain module, a
160 certain kernel, a module/version combination or a module/ver‐
161 sion/kernel combination.
162
164 -m <module>
165 The name of the module.
166 -v <module-version>
168 The version of the module to execute the specified action upon.
169 -k <kernel-version>
171 The kernel to perform the action upon. You can specify multiple
172 kernel versions on the command line by repeating the -k argument
173 with a different kernel name. However, not all actions support
174 multiple kernel versions (it will error out in this case).
175 -a, --arch
177 The system architecture to perform the action upon. If not
178 specified, it assumes the arch of the currently running system
179 (`uname -m`). You can specify multiple arch parameters on the
180 same command line by repeating the -a argument with a different
181 arch name. When multiple architectures are specified, there
182 must be a 1:1 relationship between -k arguments to -a arguments.
183 DKMS will then assume the first -a argument aligns with the
184 first -k kernel and so on for the second, third, etc.
185 For example, if you were to specify: -k kernel1 -k kernel2 -a
187 i386 -k kernel3 -a i686 -a x86_64, DKMS would process this as:
188 kernel1-i386, kernel2-i686, kernel3-x86_64.
189 -q, --quiet
191 Quiet.
192 -V, --version
194 Prints the currently installed version of dkms and exits.
195 -c <dkms.conf-location>
197 The location of the dkms.conf file. This is needed for the add
198 action and if not specified, it is assumed to be located in
199 /usr/src/<module>-<module-version>/. See below for more infor‐
200 mation on the format of dkms.conf.
201 -d, --distro
203 The distribution being used. This is only currently needed for
204 mkdriverdisk. The supported distros are redhat, suse and Unit‐
205 edLinux. See the sections on mkdriverdisk and mkkmp for more
206 information.
207 -r, --release
209 The release being used. This is only currently used for
210 mkdriverdisk and is only used for suse or UnitedLinux distros
211 (eg. -r 9.1). It is used in the internal makeup of the
212 driverdisk.
213 --size The size of the driver disk image to be created. By default,
215 this value is set at 1440. Any different size should be given
216 as an integer value only, should be divisible by 20 and should
217 represent the number of kilobytes of the image size you desire.
218 --config <kernel-.config-location>
220 During a build this option is used to specify an alternate loca‐
221 tion for the kernel .config file which was used to compile that
222 kernel. Normally, dkms uses the Red Hat standard location and
223 config filenames located in /usr/src/linux-<kernel>/configs/.
224 If the config for the kernel that you are building a module for
225 is not located here or does not have the expected name in this
226 location, you will need to tell dkms where the necessary .config
227 can be found so that your kernel can be properly prepared for
228 the module build.
229 --archive <tarball-location>
231 This option is used during a ldtarball action to specify the
232 location of the tarball you wish to load into your DKMS tree.
233 --templatekernel <kernel-version>
235 This option is required for the action: match. Match will look
236 at the templatekernel specified and install all of the same mod‐
237 ule/version combinations on the other kernel.
238 --force
240 This option can be used in conjunction with ldtarball to force
241 copying over of already existant files.
242 --binaries-only
244 This option can be used in conjunction with mktarball in order
245 to create a DKMS tarball which does not contain the source for
246 the module within it. This can be helpful in reducing the size
247 of the tarball if you know that the system which this tarball
248 will be loaded upon already has the source installed. In order
249 to load a tarball made as binaries-only you must have the module
250 source in that systems DKMS tree. If you do not, DKMS will
251 refuse to load a binaries-only tarball.
252 --source-only
254 This option can be used in conjunction with mktarball or mkrpm
255 or mkdeb in order to create a DKMS tarball which does not con‐
256 tain any prebuilt kernel module binaries within it. This is
257 helpful if you simply want to easily tar up your source but
258 don't want anything prebuilt within it. Likewise, if you are
259 using mkrpm but do not want the RPM you create to have any pre‐
260 built modules within it, passing this option will keep its
261 internal DKMS tarball from containing any prebuilt modules.
262 --all This option can be used to automatically specify all relevant
264 kernels/arches for a module/module-version. This is useful for
265 things like remove , mktarball , etc. This saves the trouble of
266 having to actually specify -k kernel1 -a arch1 -k kernel2 -a
267 arch2 for every kernel you have built your module for.
268 --no-prepare-kernel
270 This option keeps DKMS from first preparing your kernel before
271 building a module for it. Generally, this option should not be
272 used so as to ensure that modules are compiled correctly.
273 --no-clean-kernel
275 This option keeps DKMS from cleaning your kernel source tree
276 after a build.
277 --kernelsourcedir <kernel-source-directory-location>
279 Using this option you can specify the location of your kernel
280 source directory. Most likely you will not need to set this if
281 your kernel source is accessible via /lib/modules/$kernel_ver‐
282 sion/build.
283 --directive <"cli-directive=cli-value">
285 Using this option, you can specify additional directives from
286 the command line. The --directive option can be used multiple
287 times on the same command-line to specify multiple additional
288 command line directives.
289 --rpm_safe_upgrade
291 This flag should be used when packaging DKMS enabled modules in
292 RPMs. It should be specified during both the add and remove
293 actions in the RPM spec to ensure that DKMS and RPM behave cor‐
294 rectly in all scenarios when upgrading between various versions
295 of a dkms enabled module RPM package. See the sample.spec file
296 for an example or read more in the section below on Creating
297 RPMs Which Utilize DKMS.
298 --spec specfile
300 This option is used by the mkkmp action to specify which RPM
301 spec file to use when generating the KMP. specfile will be
302 sought in the module source directory.
303
305 During the first install of a module for a <kernelversion>, dkms will
306 search /lib/modules/<kernelversion> for a pre-existing module of the
307 same name. If one is found, it will automatically be saved as an "orig‐
308 inal_module" so that if the newer module is later removed, dkms will
309 put the original module back in its place. Currently, DKMS searches
310 for these original modules with first preference going to modules
311 located in /lib/modules/<kernelversion>/updates/ followed by $DEST_MOD‐
312 ULE_LOCATION (as specified in dkms.conf ). If one cannot be found in
313 either location, a find will be used to locate one for that kernel. If
314 none are found, then during a later uninstall, your kernel will not
315 have that module replaced.
316 If more than one is found, then the first one located (by preference
318 indicated above) will be considered the "original_module". As well,
319 all copies of the same-named module will be removed from your kernel
320 tree and placed into /var/dkms/<module>/original_module/$kernelver/col‐
321 lisions so that they can be *manually* accessible later. DKMS will
322 never actually do anything with the modules found underneath the /col‐
323 lisions directory, and they will be stored there until you manually
324 delete them.
325
327 When performing an add , a proper dkms.conf file must be found. A
328 properly formatted conf file is essential for communicating to dkms how
329 and where the module should be installed. While not all the directives
330 are required, providing as many as possible helps to limit any ambigu‐
331 ity. Note that the dkms.conf is really only a shell-script of variable
332 definitions which are then sourced in by the dkms executable (of the
333 format, DIRECTIVE="directive text goes here"). As well, the directives
334 are case-sensitive and should be given in ALL CAPS.
335 It is important to understand that many of the DKMS directives are
337 arrays whose index values are tied together. These array associations
338 can be considered families, and there are currently four such families
339 of directive arrays. MAKE[#] and MAKE_MATCH[#] make up one family.
340 PATCH[#] and PATCH_MATCH[#] make up the second family. The third and
341 largest family consists of BUILT_MODULE_NAME[#], BUILT_MODULE_LOCA‐
342 TION[#], DEST_MODULE_NAME[#], DEST_MODULE_LOCATION[#], MOD‐
343 ULES_CONF_ALIAS_TYPE[#], MODULES_CONF_OBSOLETES[#], MODULES_CONF_OBSO‐
344 LETE_ONLY[#] and STRIP[#]. The fourth family is made up of only MOD‐
345 ULES_CONF[#]. When indexing these arrays when creating your dkms.conf,
346 each family should start at index value 0.
347 MAKE[#]=
349 The MAKE directive array tells DKMS which make command should be
350 used for building your module. The default make command should
351 be put into MAKE[0]. Other entries in the MAKE array will only
352 be used if their corresponding entry in MAKE_MATCH[#] matches,
353 as a regular expression (using egrep), the kernel that the mod‐
354 ule is being built for. Note that if no value is placed in
355 MAKE_MATCH[#] for any MAKE[#] where # > 0, then that MAKE direc‐
356 tive is ignored. MAKE_MATCH[0] is optional and if it is popu‐
357 lated, it will be used to determine if MAKE[0] should be used to
358 build the module for that kernel. If multiple MAKE_MATCH direc‐
359 tives match against the kernel being built for, the last match‐
360 ing MAKE[#] will be used to build your module. If no MAKE direc‐
361 tive is specified or if no MAKE_MATCH matches the kernel being
362 built for, DKMS will attempt to use a generic MAKE command to
363 build your module.
364 MAKE_MATCH[#]=
366 See the above entry on MAKE[#] directives. This array should be
367 populated with regular expressions which, when matched against
368 the kernel being built for, will tell DKMS to use the corre‐
369 sponding make command in the MAKE[#] directive array to build
370 your module.
371 BUILT_MODULE_NAME[#]=
373 This directive gives the name of the module just after it is
374 built. If your DKMS module package contains more than one mod‐
375 ule to install, this is a required directive for all of the mod‐
376 ules. This directive should explicitly not contain any trailing
377 ".o" or ".ko". Note that for each module within a dkms package,
378 the numeric value of # must be the same for each of BUILT_MOD‐
379 ULE_NAME, BUILT_MODULE_LOCATION, DEST_MODULE_NAME and DEST_MOD‐
380 ULE_LOCATION and that the numbering should start at 0 (eg.
381 BUILT_MODULE_NAME[0]="qla2200" BUILT_MODULE_NAME[1]="qla2300").
382 BUILT_MODULE_LOCATION[#]=
384 This directive tells DKMS where to find your built module after
385 it has been built. This pathname should be given relative to
386 the root directory of your source files (where your dkms.conf
387 file can be found). If unset, DKMS expects to find your
388 BUILT_MODULE_NAME[#] in the root directory of your source files.
389 Note that for each module within a dkms package, the numeric
390 value of # must be the same for each of BUILT_MODULE_NAME,
391 BUILT_MODULE_LOCATION, DEST_MODULE_NAME and DEST_MODULE_LOCATION
392 and that the numbering should start at 0 (eg. BUILT_MODULE_LOCA‐
393 TION[0]="some/dir/" BUILT_MODULE_LOCATION[1]="other/dir/").
394 DEST_MODULE_NAME[#]=
396 This directive can be used to specify the name of the module as
397 it should be installed. This will rename the module from
398 BUILT_MODULE_NAME[#] to DEST_MODULE_NAME[#]. This directive
399 should explicitly not contain any trailing ".o" or ".ko". If
400 unset, it is assumed to be the same value as BUILT_MOD‐
401 ULE_NAME[#]. Note that for each module within a dkms package,
402 the numeric value of # must be the same for each of BUILT_MOD‐
403 ULE_NAME, BUILT_MODULE_LOCATION, DEST_MODULE_NAME and DEST_MOD‐
404 ULE_LOCATION and that the numbering should start at 0 (eg.
405 DEST_MODULE_NAME[0]="qla2200_6x" DEST_MOD‐
406 ULE_NAME[1]="qla2300_6x").
407 DEST_MODULE_LOCATION[#]=
409 This directive specifies the destination where a module should
410 be installed to, once compiled. It also is used for finding
411 original_modules. This is a required directive. This directive
412 must start with the text "/kernel" which is in reference to
413 /lib/modules/<kernelversion>/kernel. Note that for each module
414 within a dkms package, the numeric value of # must be the same
415 for each of BUILT_MODULE_NAME, BUILT_MODULE_LOCATION, DEST_MOD‐
416 ULE_NAME and DEST_MODULE_LOCATION and that the numbering should
417 start at 0 (eg. DEST_MODULE_LOCATION[0]="/kernel/drivers/some‐
418 thing/" DEST_MODULE_LOCATION[1]="/kernel/drivers/other/").
419 MODULES_CONF_ALIAS_TYPE[#]=
421 This directive array specifies how your modules should be
422 aliased in /etc/modules.conf when your module is installed.
423 This is done in an intelligent fashion so if DKMS detects an
424 already existing reference in modules.conf, it won't add a new
425 line. If it is not detected, it will add it to the modules.conf
426 as the last alias number for that alias type (eg. if MOD‐
427 ULES_CONF_ALIAS_TYPE="scsi_hostadapter", no alias currently
428 exists for that module and the last scsi_hostadapter reference
429 is 6, then your module will be added as "scsi_hostadapter7").
430 Common values for this directive include: scsi_hostadapter ,
431 sound-slot- and eth. Note that the numeric value of # is tied
432 to the index of BUILD_MODULE_NAME, BUILT_MODULE_LOCATION,
433 DEST_MODULE_NAME and DEST_MODULE_LOCATION. The index is also
434 tied to MODULES_CONF_OBSOLETES.
435 MODULES_CONF_OBSOLETES[#]=
437 This directive array tells DKMS what modules.conf alias refer‐
438 ences are obsoleted by the module you are installing. If your
439 module obsoletes more than one module, this directive should be
440 a comma-delimited list of those modules that are obsoleted (eg.
441 for megaraid2, MODULES_CONF_OBSO‐
442 LETES[0]="megaraid,megaraid_2002"). When you are installing your
443 module, DKMS ensures that any entries in /etc/modules.conf with
444 the same MODULES_CONF_ALIAS_TYPE are changed over to the new
445 module name. When you are uninstalling your module, depending
446 on the modules in your /lib/modules tree, DKMS will take differ‐
447 ent actions. If you kernel has an original_module, then mod‐
448 ules.conf will not be touched and the non-obsolete reference
449 will remain. If the kernel does not have an original_module but
450 does have one of the obsolete modules, it will replace those
451 references with the first obsolete module name in the comma-
452 delimited list that is also in that kernel (thus, your obsolete
453 list should be prioritized from left to right). If no origi‐
454 nal_module or obsolete modules are found within the kernel, the
455 alias entry is removed all-together. Note that the numeric value
456 of # is tied to the index of BUILD_MODULE_NAME, BUILT_MOD‐
457 ULE_LOCATION, DEST_MODULE_NAME and DEST_MODULE_LOCATION. The
458 index is also tied to MODULES_CONF_ALIAS_TYPE.
459 MODULES_CONF_OBSOLETE_ONLY[#]=
461 If set to yes , this directive will tell DKMS to only modify
462 /etc/modules.conf if it finds within it an obsolete reference as
463 specified in the corresponding value of MODULES_CONF_OBSO‐
464 LETES[#] array directive.
465 STRIP[#]=
467 By default strip is considered to be "yes". If set to "no",
468 DKMS will not run strip -g against your built module to remove
469 debug symbols from it.
470 PACKAGE_NAME=
472 This directive is used to give the name associated with the
473 entire package of modules. This is the same name that is used
474 with the -m option when building, adding, etc. and may not nec‐
475 essarily be the same as the MODULE_NAME. This directive must be
476 present in every dkms.conf.
477 PACKAGE_VERSION=
479 This directive is used to give the version associated with the
480 entire package of modules being installed within that dkms pack‐
481 age. This directive must be present in every dkms.conf.
482 CLEAN= CLEAN specifies the make clean command to be used to clean up
484 both before and after building the module. If unset, it is
485 assumed to be "make clean".
486 REMAKE_INITRD=
488 This directive specifies whether your initrd should be remade
489 after the module is installed onto the kernel. Any text after
490 the first character is ignored and if the first character is not
491 a "y" or a "Y", it is assumed that REMAKE_INITRD="no".
492 MODULES_CONF[#]=
494 This directive array specifies what static configuration text
495 lines need to be added into /etc/modules.conf for your module.
496 See the section on MODULES.CONF CHANGES for more information
497 regarding the implications of modifying /etc/modules.conf
498 PATCH[#]=
500 Use the PATCH directive array to specify patches which should be
501 applied to your source before a build occurs. All patches are
502 expected to be in -p1 format and are applied with the patch -p1
503 command. Each directive should specify the filename of the
504 patch to apply, and all patches must be located in the patches
505 subdirectory of your source directory ( /usr/src/<module>-<mod‐
506 ule-version>/patches/ ). If any patch fails to apply, the build
507 will be halted and the rejections can be inspected in
508 /var/dkms/<module>/<module-version>/build/. If a PATCH should
509 only be applied conditionally, the PATCH_MATCH[#] array should
510 be used, and a corresponding regular expression should be placed
511 in PATCH_MATCH[#] which will alert dkms to only use that
512 PATCH[#] if the regular expression matches the kernel which the
513 module is currently being built for.
514 PATCH_MATCH[#]=
516 See the above description for PATCH[#] directives. If you only
517 want a patch applied in certain scenarios, the PATCH_MATCH array
518 should be utilized by giving a regular expression which matches
519 the kernels you intend the corresponding PATCH[#] to be applied
520 to before building that module.
521 AUTOINSTALL=
523 If this directive is set to yes then the service
524 /etc/rc.d/init.d/dkms_autoinstaller will automatically try to
525 install this module on any kernel you boot into. See the sec‐
526 tion on dkms_autoinstaller for more information.
527 BUILD_EXCLUSIVE_KERNEL=
529 This optional directive allows you to specify a regular expres‐
530 sion which defines the subset of kernels which DKMS is allowed
531 to build your module for. If the kernel being built for does
532 not match against this regular expression, the dkms build will
533 error out. For example, if you set it as ="^2.4.*", your module
534 would not be built for 2.6 kernels.
535 BUILD_EXCLUSIVE_ARCH=
537 This optional directive functions very similarly to BUILD_EXCLU‐
538 SIVE_KERNEL except that it matches against the kernel architec‐
539 ture. For example, if you set it to ="i.86", your module would
540 not be built for ia32e, x86_64, amd64, s390, etc.
541 POST_ADD=
543 The name of the script to be run after an add is performed. The
544 path should be given relative to the root directory of your
545 source.
546 POST_BUILD=
548 The name of the script to be run after a build is performed. The
549 path should be given relative to the root directory of your
550 source.
551 POST_INSTALL=
553 The name of the script to be run after an install is performed.
554 The path should be given relative to the root directory of your
555 source.
556 POST_REMOVE=
558 The name of the script to be run after a remove is performed.
559 The path should be given relative to the root directory of your
560 source.
561 PRE_BUILD=
563 The name of the script to be run before a build is performed.
564 The path should be given relative to the root directory of your
565 source.
566 PRE_INSTALL=
568 The name of the script to be run before an install is performed.
569 The path should be given relative to the root directory of your
570 source. If the script exits with a non-zero value, the install
571 will be aborted. This is typically used to perform a custom
572 version comparison.
573 DKMS.CONF VARIABLES
576 Within your dkms.conf file, you can use certain variables which
577 will be replaced at run-time with their values.
578 $kernelver
580 This variable can be used within a directive definition and dur‐
581 ing use, the actual kernel version in question will be substi‐
582 tuted in its place. This is especially useful in MAKE commands
583 when specifying which INCLUDE statements should be used when
584 compiling your module (eg. MAKE="make all INCLUDEDIR=/lib/mod‐
585 ules/${kernelver}/build/include").
586 $dkms_tree
588 See the section on /etc/dkms/framework.conf for more informa‐
589 tion. This variable represents the location of the DKMS tree on
590 the local system. By default this is /var/dkms , but this value
591 should not be hard-coded into a dkms.conf in the event that the
592 local user has changed it on their system.
593 $source_tree
595 See the section on /etc/dkms/framework.conf for more informa‐
596 tion. This variable represents the location where DKMS keeps
597 source on the local system. By default this is /usr/src , but
598 this value should not be hard-coded into a dkms.conf in the
599 event that the local user has changed it on their system.
600 $kernel_source_dir
602 This variable holds the value of the location of your kernel
603 source directory. Usually, this will be /lib/modules/$ker‐
604 nelver/build , unless otherwise specified with the --kernel‐
605 sourcedir option.
606
608 This configuration file controls how the overall DKMS framework han‐
609 dles. It is sourced in everytime the dkms command is run. Mainly it
610 can currently be used to set different default values for the variables
611 $dkms_tree , $source_tree and $install_tree which control where DKMS
612 looks for its framework. Note that these variables can also be manipu‐
613 lated on the command line with the undocumented --dkmstree, --source‐
614 tree and --installtree options. Whoops, did I just document these?
615
617 This boot-time service automatically installs any module which has
618 AUTOINSTALL="yes" set in its dkms.conf file. The service works quite
619 simply and if multiple versions of a module are in your system's DKMS
620 tree, it will not do anything and instead explain that manual interven‐
621 tion is required.
622
624 Changes that your module will make to /etc/modules.conf or /etc/mod‐
625 probe.conf should be specified with the MODULES_CONF_ALIAS_TYPE[#] ,
626 the MODULES_CONF_OBSOLETES[#] and the MODULES_CONF[#] directive arrays.
627 These arrays should also be used even if your distro uses /etc/syscon‐
628 fig/kernel to track kernel modules.
629 When the first module is installed upon the first kernel within the
631 user's system, these entries in MODULES_CONF[#] are automatically added
632 to /etc/modules.conf and if REMAKE_INITRD is specified, then the user's
633 initrd is then remade. Subsequently, as your modules are then later
634 removed from the user's system, until the final module/version combina‐
635 tion is removed from the final kernel version, those references in mod‐
636 ules.conf will remain. Once the last module/version combination is
637 removed, those references are then removed.
638 As modules/versions are removed and initrds are remade, one of three
640 things will happen if you have specified a MODULES_CONF_ALIAS_TYPE. If
641 no original_module exists for that kernel, and no MODULES_CONF_OBSO‐
642 LETES modules are found in that kernel too, the modules.conf alias ref‐
643 erences will temporarily be removed so that the initrd will success‐
644 fully remake. Once the initrd is remade, however; those references are
645 then automatically put back into modules.conf (unless you are removing
646 the last instance of the module on the last kernel). However, if no
647 original_module exists, but there is an OBSOLETE module found within
648 that kernel, the alias reference is temporarily shifted to point to the
649 OBSOLETE module so that the initrd can be remade. After it is remade,
650 it then automatically puts back the alias reference (unless you are
651 removing the last instance of the module on the last kernel). Lastly,
652 if an original_module does exist for the kernel version, then mod‐
653 ules.conf is not touched and all references persist (even if you are
654 removing the last instance of the module on the last kernel).
655 Certain module installations might not only require adding references
657 to modules.conf but also require removing conflicting references that
658 might exist in the user's system. If this is the case, the MOD‐
659 ULES_CONF_OBSOLETES[#] directive should be utilized to remove these
660 references. More information about this directive can be found in the
661 DKMS.CONF section of this man page.
662 Note that the end state of your modules.conf file very much depends on
664 what kernel modules exist in the final kernel you remove your DKMS mod‐
665 ule from. This is an imperfect system caused by the fact that there is
666 only one modules.conf file for every kernel on your system even though
667 various kernels use different modules. In a perfect world, there would
668 be one modules.conf file for every kernel (just like System.map).
669
671 See the sample.spec file packaged with DKMS as an example for what your
672 RPM spec file might look like. Creating RPMs which utilize dkms is a
673 fairly straight-forward process. The RPM need only to install the
674 source into /usr/src/<module>-<module-version>/ and then employ dkms
675 itself to do all the work of installation. As such, the RPM should
676 first untar the source into this directory. From here, within the RPM
677 .spec file, a dkms add should be called (remember to use the
678 --rpm_safe_upgrade flag during the add) followed by a dkms build fol‐
679 lowed by a dkms install. Your dkms.conf file should be placed within
680 the /usr/src/<module>-<module-version>/ directory.
681 Under the removal parts of the .spec file, all that needs to be called
683 is a: dkms remove -m <module> -v <module-version> --all
684 --rpm_safe_upgrade.
685 Use of the --rpm_safe_upgrade flag is imperative for making sure DKMS
687 and RPM play nicely together in all scenarios of using the -Uvh flag
688 with RPM to upgrade dkms enabled packages. It will only function if
689 used during both the add and remove actions within the same RPM spec
690 file. Its use makes sure that when upgrading between different releases
691 of an RPM for the same <module-version>, DKMS does not do anything dumb
692 (eg. it ensures a smooth upgrade from megaraid-2.09-5.noarch.rpm to
693 megaraid-2.09-6.noarch.rpm).
694 It should be noted that a binary RPM which contains source is not a
696 traditional practice. However, given the benefits of dkms it hopefully
697 will become so. As the RPM created which utilizes dkms is not archi‐
698 tecture specific, BuildArch: noarch should be specified in the .spec
699 file to indicate that the package can work regardless of the system
700 architecture. Also note that DKMS RPM upgrades (-U option) will auto‐
701 matically work because of the structure of the dkms tree.
702 Lastly, as a matter of convention, you should name your RPM: <pack‐
704 age>-<version>-<rpm-version>dkms.noarch.rpm. The word dkms as part of
705 the rpm-version signifies that the RPM works within the DKMS framework.
706
708 Gary Lerhaupt
709
711 http://linux.dell.com/dkms
712
714 http://linux.dell.com/dkms/dkms-ols2004.pdf
715 http://www.dell.com/downloads/global/power/1q04-ler.pdf
717 http://www.linuxjournal.com/article.php?sid=6896
719
721 dkms-devel@dell.com http://lists.us.dell.com/mailman/listinfo/dkms-
722 devel
723
725 Kernel Module Packages http://kerneldrivers.org
726 Novell Kernel Module Packages http://www.suse.de/~agruen/KMPM
728 Fedora Kernel Module Packages http://fedoraproject.org/wiki/Extras/Ker‐
730 nelModuleProposal
731Version 2.0.14 Feb 2007 DKMS(8)