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