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 [/path/to/tarball.tar] [--force]
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]
154 This action allows you to create a debian binary package for a
156 specified module / version. It uses a template debian directory
157 found in /etc/dkms/template-dkms-mkdeb as the basis for the pack‐
158 age. Alternatively, if DKMS finds a file called /usr/src/<mod‐
159 ule>-<module-version>/<module>-dkms-mkdeb it will use that folder
160 instead. In general, a DKMS tarball is placed inside the contents
161 of this package, and the package itself calls various DKMS commands
162 to load this tarball, build and install modules on the end user's
163 system.
164 mkbmdeb [module/module-version] [-k kernel/arch]
166 Creates a Debian binary package containing just the binary modules
168 in the /lib/modules installation path. This package does not depend
169 on dkms and does not require a toolchain to be installed on the
170 target host. Useful if you want to have a package to install on
171 hosts identical to the build system without installing the full
172 toolchain on them. It uses a template debian directory found in
173 /etc/dkms/template-dkms-mkbmdeb as the basis for the package.
174 mkdsc [module/module-version] [-k kernel/arch]
176 This action allows you to create a debian source package for a
178 specified module / version. It will create a .tar.gz, and a .dsc.
179 All options supported by mkdeb are supported by it. The main dif‐
180 ference in it's usage is that it will look in /etc/dkms/tem‐
181 plate-dkms-mkdsc as the basis for the package. Alternatively, if
182 DKMS finds a file called /usr/src/<module>-<module-version>/<mod‐
183 ule>-dkms-mkdsc it will use that folder instead.
184 mkkmp [module/module-version] [--spec specfile]
186 This action allows you to create an Kernel Module Package source
188 RPM for a specified module / version. It uses the .spec file spec‐
189 ified by --spec=specfile else $module-kmp.spec as the basis for the
190 RPM. The generated source RPM may then be built using SuSE's
191 build.rpm or Fedora/RHEL's mock chroot environments. See
192 http://kerneldrivers.org/ for more details on KMPs.
193 status [module/module-version] [-k kernel/arch]
195 Returns the current status of modules, versions and kernels within
197 the tree as well as whether they have been added, built or
198 installed. Status can be shown for just a certain module, a cer‐
199 tain kernel, a module/version combination or a module/version/ker‐
200 nel combination.
201 autoinstall
203 Attempt to install the latest revision of all modules that have
205 been installed for other kernel revisions. dkms_autoinstaller is a
206 stub that uses this action to perform its work.
207
209 -m <module>/<module-version>
210 The name of the module and module version you want to operate
211 on. The -m part of this option is optional, and can be omitted
212 in virtually all circumstances.
213 -v <module-version>
215 The version of the module to execute the specified action upon.
216 This option only has to be specified if you pass a -m option
217 without a <module-version> component of its own.
218 -k <kernel-version>/<arch>
220 The kernel and arch to perform the action upon. You can specify
221 multiple kernel version/arch pairs on the command line by
222 repeating the -k argument with a different kernel version and
223 arch. However, not all actions support multiple kernel versions
224 (it will error out in this case). The arch part can be omitted,
225 and DKMS will assume you want it to be the arch of the currently
226 running system.
227 -a, --arch
229 The system architecture to perform the action upon. It is
230 optional if you pass it as part of the -k option. If not speci‐
231 fied, it assumes the arch of the currently running system
232 (`uname -m`). You can specify multiple arch parameters on the
233 same command line by repeating the -a argument with a different
234 arch name. When multiple architectures are specified, there
235 must be a 1:1 relationship between -k arguments to -a arguments.
236 DKMS will then assume the first -a argument aligns with the
237 first -k kernel and so on for the second, third, etc.
238 For example, if you were to specify: -k kernel1 -k kernel2 -a
240 i386 -k kernel3 -a i686 -a x86_64, DKMS would process this as:
241 kernel1-i386, kernel2-i686, kernel3-x86_64.
242 -q, --quiet
244 Quiet.
245 -V, --version
247 Prints the currently installed version of dkms and exits.
248 -c <dkms.conf-location>
250 The location of the dkms.conf file. This is needed for the add
251 action and if not specified, it is assumed to be located in
252 /usr/src/<module>-<module-version>/. See below for more infor‐
253 mation on the format of dkms.conf.
254 -d, --distro
256 The distribution being used. This is only currently needed for
257 mkdriverdisk. The supported distros are redhat, suse and Unit‐
258 edLinux. See the sections on mkdriverdisk and mkkmp for more
259 information.
260 -r, --release
262 The release being used. This is only currently used for
263 mkdriverdisk and is only used for suse or UnitedLinux distros
264 (eg. -r 9.1). It is used in the internal makeup of the
265 driverdisk.
266 --size The size of the driver disk image to be created. By default,
268 this value is set at 1440. Any different size should be given
269 as an integer value only, should be divisible by 20 and should
270 represent the number of kilobytes of the image size you desire.
271 --config <kernel-.config-location>
273 During a build this option is used to specify an alternate loca‐
274 tion for the kernel .config file which was used to compile that
275 kernel. Normally, dkms uses the Red Hat standard location and
276 config filenames located in /usr/src/linux-<kernel>/configs/.
277 If the config for the kernel that you are building a module for
278 is not located here or does not have the expected name in this
279 location, you will need to tell dkms where the necessary .config
280 can be found so that your kernel can be properly prepared for
281 the module build.
282 --archive <tarball-location>
284 This option is used during a ldtarball action to specify the
285 location of the tarball you wish to load into your DKMS tree.
286 You only have to specify the --archive part of this option if
287 <tarball-location> does not already exist as a file.
288 --templatekernel <kernel-version>
290 This option is required for the action: match. Match will look
291 at the templatekernel specified and install all of the same mod‐
292 ule/version combinations on the other kernel.
293 --force
295 This option can be used in conjunction with ldtarball to force
296 copying over of extant files.
297 --binaries-only
299 This option can be used in conjunction with mktarball in order
300 to create a DKMS tarball which does not contain the source for
301 the module within it. This can be helpful in reducing the size
302 of the tarball if you know that the system which this tarball
303 will be loaded upon already has the source installed. In order
304 to load a tarball made as binaries-only you must have the module
305 source in that systems DKMS tree. If you do not, DKMS will
306 refuse to load a binaries-only tarball.
307 --source-only
309 This option can be used in conjunction with mktarball or mkrpm
310 or mkdeb in order to create a DKMS tarball which does not con‐
311 tain any prebuilt kernel module binaries within it. This is
312 helpful if you simply want to easily tar up your source but
313 don't want anything prebuilt within it. Likewise, if you are
314 using mkrpm but do not want the RPM you create to have any pre‐
315 built modules within it, passing this option will keep its
316 internal DKMS tarball from containing any prebuilt modules.
317 --all This option can be used to automatically specify all relevant
319 kernels/arches for a module/module-version. This is useful for
320 things like remove , mktarball , etc. This saves the trouble of
321 having to actually specify -k kernel1 -a arch1 -k kernel2 -a
322 arch2 for every kernel you have built your module for.
323 --no-prepare-kernel
325 This option keeps DKMS from first preparing your kernel before
326 building a module for it. Generally, this option should not be
327 used so as to ensure that modules are compiled correctly.
328 --no-clean-kernel
330 This option keeps DKMS from cleaning your kernel source tree
331 after a build.
332 --no-depmod
334 This option prevents DKMS from running the depmod command during
335 install and uninstall which will avoid (re)calculating module
336 dependencies and thereby save time.
337 --kernelsourcedir <kernel-source-directory-location>
339 Using this option you can specify the location of your kernel
340 source directory. Most likely you will not need to set this if
341 your kernel source is accessible via /lib/modules/$kernel_ver‐
342 sion/build.
343 --directive <"cli-directive=cli-value">
345 Using this option, you can specify additional directives from
346 the command line. The --directive option can be used multiple
347 times on the same command-line to specify multiple additional
348 command line directives.
349 --rpm_safe_upgrade
351 This flag should be used when packaging DKMS enabled modules in
352 RPMs. It should be specified during both the add and remove
353 actions in the RPM spec to ensure that DKMS and RPM behave cor‐
354 rectly in all scenarios when upgrading between various versions
355 of a dkms enabled module RPM package. See the sample.spec file
356 for an example or read more in the section below on Creating
357 RPMs Which Utilize DKMS.
358 --spec specfile
360 This option is used by the mkkmp action to specify which RPM
361 spec file to use when generating the KMP. specfile will be
362 sought in the module source directory.
363 --dkmstree path/to/place
365 Provides a destination tree for building and installing modules
366 to. Useful in cases that you don't want to contaminate a system
367 when using solely for building.
368 --sourcetree path/to/place
370 Provides a location to build a DKMS package from. Useful for
371 systems that you may not have root access, but would still like
372 to be able to build DKMS packages.
373 --installtree path/to/place
375 Provides a location to place modules when a dkms install command
376 is issued.
377 --legacy-postinst=[0|1]
379 Includes a legacy postinstall script so that a DEB or RPM built
380 by DKMS can be used on versions prior than DKMS 2.1. This
381 option currently defaults to 1.
382 --dkmsframework path/to/file
384 A supplemental configuration file to the system-wide dkms frame‐
385 work, typically located in /etc/dkms/framework.conf. All option
386 that are normally provided on a command line can be provided in
387 this file.
388 -j number
390 Run no more than number jobs in parallel; see the -j option of
391 make(1). Defaults to the number of CPUs in the system, detected
392 by nproc(1). Specify 0 to impose no limit on the number of par‐
393 allel jobs.
394
396 During the first install of a module for a <kernelversion>, dkms will
397 search /lib/modules/<kernelversion> for a pre-existing module of the
398 same name. If one is found, it will automatically be saved as an "orig‐
399 inal_module" so that if the newer module is later removed, dkms will
400 put the original module back in its place. Currently, DKMS searches
401 for these original modules with first preference going to modules
402 located in /lib/modules/<kernelversion>/updates/ followed by $DEST_MOD‐
403 ULE_LOCATION (as specified in dkms.conf ). If one cannot be found in
404 either location, a find will be used to locate one for that kernel. If
405 none are found, then during a later uninstall, your kernel will not
406 have that module replaced.
407 If more than one is found, then the first one located (by preference
409 indicated above) will be considered the "original_module". As well,
410 all copies of the same-named module will be removed from your kernel
411 tree and placed into /var/lib/dkms/<module>/original_module/$ker‐
412 nelver/collisions so that they can be *manually* accessible later. DKMS
413 will never actually do anything with the modules found underneath the
414 /collisions directory, and they will be stored there until you manually
415 delete them.
416
418 When performing an add , a proper dkms.conf file must be found. A
419 properly formatted conf file is essential for communicating to dkms how
420 and where the module should be installed. While not all the directives
421 are required, providing as many as possible helps to limit any ambigu‐
422 ity. Note that the dkms.conf is really only a shell-script of variable
423 definitions which are then sourced in by the dkms executable (of the
424 format, DIRECTIVE="directive text goes here"). As well, the directives
425 are case-sensitive and should be given in ALL CAPS.
426 It is important to understand that many of the DKMS directives are
428 arrays whose index values are tied together. These array associations
429 can be considered families, and there are currently four such families
430 of directive arrays. MAKE[#] and MAKE_MATCH[#] make up one family.
431 PATCH[#] and PATCH_MATCH[#] make up the second family. The third and
432 largest family consists of BUILT_MODULE_NAME[#], BUILT_MODULE_LOCA‐
433 TION[#], DEST_MODULE_NAME[#], DEST_MODULE_LOCATION[#], MOD‐
434 ULES_CONF_ALIAS_TYPE[#], MODULES_CONF_OBSOLETES[#], MODULES_CONF_OBSO‐
435 LETE_ONLY[#] and STRIP[#]. The fourth family is made up of only MOD‐
436 ULES_CONF[#]. When indexing these arrays when creating your dkms.conf,
437 each family should start at index value 0.
438 MAKE[#]=
440 The MAKE directive array tells DKMS which make command should be
441 used for building your module. The default make command should
442 be put into MAKE[0]. Other entries in the MAKE array will only
443 be used if their corresponding entry in MAKE_MATCH[#] matches,
444 as a regular expression (using egrep), the kernel that the mod‐
445 ule is being built for. Note that if no value is placed in
446 MAKE_MATCH[#] for any MAKE[#] where # > 0, then that MAKE direc‐
447 tive is ignored. MAKE_MATCH[0] is optional and if it is popu‐
448 lated, it will be used to determine if MAKE[0] should be used to
449 build the module for that kernel. If multiple MAKE_MATCH direc‐
450 tives match against the kernel being built for, the last match‐
451 ing MAKE[#] will be used to build your module. If no MAKE direc‐
452 tive is specified or if no MAKE_MATCH matches the kernel being
453 built for, DKMS will attempt to use a generic MAKE command to
454 build your module.
455 KERNELRELEASE will be automatically appended to MAKE[#]. If you
457 want to suppress this behavior, you can quote the make command:
458 'make'.
459 MAKE_MATCH[#]=
461 See the above entry on MAKE[#] directives. This array should be
462 populated with regular expressions which, when matched against
463 the kernel being built for, will tell DKMS to use the corre‐
464 sponding make command in the MAKE[#] directive array to build
465 your module.
466 BUILT_MODULE_NAME[#]=
468 This directive gives the name of the module just after it is
469 built. If your DKMS module package contains more than one mod‐
470 ule to install, this is a required directive for all of the mod‐
471 ules. This directive should explicitly not contain any trailing
472 ".o" or ".ko". Note that for each module within a dkms package,
473 the numeric value of # must be the same for each of BUILT_MOD‐
474 ULE_NAME, BUILT_MODULE_LOCATION, DEST_MODULE_NAME and DEST_MOD‐
475 ULE_LOCATION and that the numbering should start at 0 (eg.
476 BUILT_MODULE_NAME[0]="qla2200" BUILT_MODULE_NAME[1]="qla2300").
477 BUILT_MODULE_LOCATION[#]=
479 This directive tells DKMS where to find your built module after
480 it has been built. This pathname should be given relative to
481 the root directory of your source files (where your dkms.conf
482 file can be found). If unset, DKMS expects to find your
483 BUILT_MODULE_NAME[#] in the root directory of your source files.
484 Note that for each module within a dkms package, the numeric
485 value of # must be the same for each of BUILT_MODULE_NAME,
486 BUILT_MODULE_LOCATION, DEST_MODULE_NAME and DEST_MODULE_LOCATION
487 and that the numbering should start at 0 (eg. BUILT_MODULE_LOCA‐
488 TION[0]="some/dir/" BUILT_MODULE_LOCATION[1]="other/dir/").
489 DEST_MODULE_NAME[#]=
491 This directive can be used to specify the name of the module as
492 it should be installed. This will rename the module from
493 BUILT_MODULE_NAME[#] to DEST_MODULE_NAME[#]. This directive
494 should explicitly not contain any trailing ".o" or ".ko". If
495 unset, it is assumed to be the same value as BUILT_MOD‐
496 ULE_NAME[#]. Note that for each module within a dkms package,
497 the numeric value of # must be the same for each of BUILT_MOD‐
498 ULE_NAME, BUILT_MODULE_LOCATION, DEST_MODULE_NAME and DEST_MOD‐
499 ULE_LOCATION and that the numbering should start at 0 (eg.
500 DEST_MODULE_NAME[0]="qla2200_6x" DEST_MOD‐
501 ULE_NAME[1]="qla2300_6x").
502 DEST_MODULE_LOCATION[#]=
504 This directive specifies the destination where a module should
505 be installed to, once compiled. It also is used for finding
506 original_modules. This is a required directive, except as noted
507 below. This directive must start with the text "/kernel" which
508 is in reference to /lib/modules/<kernelversion>/kernel. Note
509 that for each module within a dkms package, the numeric value of
510 # must be the same for each of BUILT_MODULE_NAME, BUILT_MOD‐
511 ULE_LOCATION, DEST_MODULE_NAME and DEST_MODULE_LOCATION and that
512 the numbering should start at 0 (eg. DEST_MODULE_LOCA‐
513 TION[0]="/kernel/drivers/something/" DEST_MODULE_LOCA‐
514 TION[1]="/kernel/drivers/other/").
515 DEST_MODULE_LOCATION is ignored on Fedora and Red Hat Enterprise
517 Linux, Novell SuSE Linux Enterprise Server 10 and higher, Novell
518 SuSE Linux 10.0 and higher, and Ubuntu. Instead, the proper dis‐
519 tribution-specific directory is used.
520 MODULES_CONF_ALIAS_TYPE[#]=
522 This directive array specifies how your modules should be
523 aliased in /etc/modules.conf when your module is installed.
524 This is done in an intelligent fashion so if DKMS detects an
525 already existing reference in modules.conf, it won't add a new
526 line. If it is not detected, it will add it to the modules.conf
527 as the last alias number for that alias type (eg. if MOD‐
528 ULES_CONF_ALIAS_TYPE="scsi_hostadapter", no alias currently
529 exists for that module and the last scsi_hostadapter reference
530 is 6, then your module will be added as "scsi_hostadapter7").
531 Common values for this directive include: scsi_hostadapter ,
532 sound-slot- and eth. Note that the numeric value of # is tied
533 to the index of BUILT_MODULE_NAME, BUILT_MODULE_LOCATION,
534 DEST_MODULE_NAME and DEST_MODULE_LOCATION. The index is also
535 tied to MODULES_CONF_OBSOLETES.
536 MODULES_CONF_OBSOLETES[#]=
538 This directive array tells DKMS what modules.conf alias refer‐
539 ences are obsoleted by the module you are installing. If your
540 module obsoletes more than one module, this directive should be
541 a comma-delimited list of those modules that are obsoleted (eg.
542 for megaraid2, MODULES_CONF_OBSO‐
543 LETES[0]="megaraid,megaraid_2002"). When you are installing your
544 module, DKMS ensures that any entries in /etc/modules.conf with
545 the same MODULES_CONF_ALIAS_TYPE are changed over to the new
546 module name. When you are uninstalling your module, depending
547 on the modules in your /lib/modules tree, DKMS will take differ‐
548 ent actions. If you kernel has an original_module, then mod‐
549 ules.conf will not be touched and the non-obsolete reference
550 will remain. If the kernel does not have an original_module but
551 does have one of the obsolete modules, it will replace those
552 references with the first obsolete module name in the
553 comma-delimited list that is also in that kernel (thus, your
554 obsolete list should be prioritized from left to right). If no
555 original_module or obsolete modules are found within the kernel,
556 the alias entry is removed all-together. Note that the numeric
557 value of # is tied to the index of BUILT_MODULE_NAME, BUILT_MOD‐
558 ULE_LOCATION, DEST_MODULE_NAME and DEST_MODULE_LOCATION. The
559 index is also tied to MODULES_CONF_ALIAS_TYPE.
560 MODULES_CONF_OBSOLETE_ONLY[#]=
562 If set to yes , this directive will tell DKMS to only modify
563 /etc/modules.conf if it finds within it an obsolete reference as
564 specified in the corresponding value of MODULES_CONF_OBSO‐
565 LETES[#] array directive.
566 STRIP[#]=
568 By default strip is considered to be "yes". If set to "no",
569 DKMS will not run strip -g against your built module to remove
570 debug symbols from it. STRIP[0] is used as the default for any
571 unset entries in the STRIP array.
572 PACKAGE_NAME=
574 This directive is used to give the name associated with the
575 entire package of modules. This is the same name that is used
576 with the -m option when building, adding, etc. and may not nec‐
577 essarily be the same as the MODULE_NAME. This directive must be
578 present in every dkms.conf.
579 PACKAGE_VERSION=
581 This directive is used to give the version associated with the
582 entire package of modules being installed within that dkms pack‐
583 age. This directive must be present in every dkms.conf.
584 CLEAN= CLEAN specifies the make clean command to be used to clean up
586 both before and after building the module. If unset, it is
587 assumed to be "make clean".
588 REMAKE_INITRD=
590 This directive specifies whether your initrd should be remade
591 after the module is installed onto the kernel. Any text after
592 the first character is ignored and if the first character is not
593 a "y" or a "Y", it is assumed that REMAKE_INITRD="no".
594 MODULES_CONF[#]=
596 This directive array specifies what static configuration text
597 lines need to be added into /etc/modules.conf for your module.
598 See the section on MODULES.CONF CHANGES for more information
599 regarding the implications of modifying /etc/modules.conf
600 OBSOLETE_BY=
602 This directive allows you to specify a kernel version that obso‐
603 letes the necessity for this particular DKMS module. This can
604 be specified as a particular upstream kernel or an ABI bump of a
605 kernel. For example, "2.6.24" would be an upstream kernel and
606 "2.6.24-16" would represent an ABI bump for a kernel. Both are
607 valid in this area.
608 Please avoid the use of OBSOLETE_BY wherever possible. It's use
610 indicates a lack of proper module versioning using MODULE_VER‐
611 SION() tags in the module source itself. It is better to fix
612 the MODULE_VERSION() tags than use OBSOLETE_BY. This also
613 introduces a implicit distribution/version dependency on the
614 package, as the value of OBSOLETE_BY is meaningful only in the
615 context of a single distribution/version.
616 If you feel you must use it, please use as such in dkms.conf:
618 ubuntu_804="Ubuntu
620 8.04"
621 if [ -x /usr/bin/lsb_release ]; then
622 if [ "$(/usr/bin/lsb_release -sir)" == "${ubuntu_804}" ];
623 then
624 OBSOLETE_BY="2.6.25"
625 fi
626 fi
627 PATCH[#]=
630 Use the PATCH directive array to specify patches which should be
631 applied to your source before a build occurs. All patches are
632 expected to be in -p1 format and are applied with the patch -p1
633 command. Each directive should specify the filename of the
634 patch to apply, and all patches must be located in the patches
635 subdirectory of your source directory ( /usr/src/<module>-<mod‐
636 ule-version>/patches/ ). If any patch fails to apply, the build
637 will be halted and the rejections can be inspected in
638 /var/lib/dkms/<module>/<module-version>/build/. If a PATCH
639 should only be applied conditionally, the PATCH_MATCH[#] array
640 should be used, and a corresponding regular expression should be
641 placed in PATCH_MATCH[#] which will alert dkms to only use that
642 PATCH[#] if the regular expression matches the kernel which the
643 module is currently being built for.
644 PATCH_MATCH[#]=
646 See the above description for PATCH[#] directives. If you only
647 want a patch applied in certain scenarios, the PATCH_MATCH array
648 should be utilized by giving a regular expression which matches
649 the kernels you intend the corresponding PATCH[#] to be applied
650 to before building that module.
651 AUTOINSTALL=
653 If this directive is set to yes then the service
654 /etc/rc.d/init.d/dkms_autoinstaller will automatically try to
655 install this module on any kernel you boot into. See the sec‐
656 tion on dkms_autoinstaller for more information.
657 BUILD_DEPENDS[#]=
659 This optional directive is an array that allows you to specify
660 other modules as dependencies for your module. Each array ele‐
661 ment should be the PACKAGE_NAME of another module that is man‐
662 aged by dkms. Do not specify a version or architecture in the
663 dependency. Note that this directive is only advisory; missing
664 or broken dependencies cause non-fatal warnings.
665 BUILD_EXCLUSIVE_KERNEL=
667 This optional directive allows you to specify a regular expres‐
668 sion which defines the subset of kernels which DKMS is allowed
669 to build your module for. If the kernel being built for does
670 not match against this regular expression, the dkms build will
671 error out. For example, if you set it as ="^2.4.*", your module
672 would not be built for 2.6 kernels.
673 BUILD_EXCLUSIVE_ARCH=
675 This optional directive functions very similarly to BUILD_EXCLU‐
676 SIVE_KERNEL except that it matches against the kernel architec‐
677 ture. For example, if you set it to ="i.86", your module would
678 not be built for ia32e, x86_64, amd64, s390, etc.
679 POST_ADD=
681 The name of the script to be run after an add is performed. The
682 path should be given relative to the root directory of your
683 source.
684 POST_BUILD=
686 The name of the script to be run after a build is performed. The
687 path should be given relative to the root directory of your
688 source.
689 POST_INSTALL=
691 The name of the script to be run after an install is performed.
692 The path should be given relative to the root directory of your
693 source.
694 POST_REMOVE=
696 The name of the script to be run after a remove is performed.
697 The path should be given relative to the root directory of your
698 source.
699 PRE_BUILD=
701 The name of the script to be run before a build is performed.
702 The path should be given relative to the root directory of your
703 source.
704 PRE_INSTALL=
706 The name of the script to be run before an install is performed.
707 The path should be given relative to the root directory of your
708 source. If the script exits with a non-zero value, the install
709 will be aborted. This is typically used to perform a custom
710 version comparison.
711 SIGN_TOOL=
713 The module signing tool to be run at a build. Two arguments
714 will be passed to the signing tool. The first argument is the
715 target kernel version, the second is the module file path. If
716 the tool exits with a non-zero value, the build will be aborted.
717 DKMS.CONF VARIABLES
720 Within your dkms.conf file, you can use certain variables which
721 will be replaced at run-time with their values.
722 $kernelver
724 This variable can be used within a directive definition and dur‐
725 ing use, the actual kernel version in question will be substi‐
726 tuted in its place. This is especially useful in MAKE commands
727 when specifying which INCLUDE statements should be used when
728 compiling your module (eg. MAKE="make all INCLUDEDIR=/lib/mod‐
729 ules/${kernelver}/build/include").
730 $dkms_tree
732 See the section on /etc/dkms/framework.conf for more informa‐
733 tion. This variable represents the location of the DKMS tree on
734 the local system. By default this is /var/lib/dkms , but this
735 value should not be hard-coded into a dkms.conf in the event
736 that the local user has changed it on their system.
737 $source_tree
739 See the section on /etc/dkms/framework.conf for more informa‐
740 tion. This variable represents the location where DKMS keeps
741 source on the local system. By default this is /usr/src , but
742 this value should not be hard-coded into a dkms.conf in the
743 event that the local user has changed it on their system.
744 $kernel_source_dir
746 This variable holds the value of the location of your kernel
747 source directory. Usually, this will be /lib/modules/$ker‐
748 nelver/build , unless otherwise specified with the --kernel‐
749 sourcedir option.
750
752 You can override the module-provided dkms.conf files. Every time after
753 a dkms.conf file is read, dkms will look for and read the following
754 files in order:
755 /etc/dkms/<module>.conf
757 /etc/dkms/<module>-<module-version>.conf
758 /etc/dkms/<module>-<module-version>-<kernel>.conf
759 /etc/dkms/<module>-<module-version>-<kernel>-<arch>.conf
760 You can use these files to override settings in the module-provided
762 dkms.conf files.
763
765 This configuration file controls how the overall DKMS framework han‐
766 dles. It is sourced in every time the dkms command is run. Mainly it
767 can currently be used to set different default values for the vari‐
768 ables. $dkms_tree , $source_tree and $install_tree which control where
769 DKMS looks for its framework. The $symlink_modules variable controls
770 whether binary modules are copied to /lib/modules or if only symlinks
771 are created there. Note that these variables can also be manipulated on
772 the command line with --dkmstree, --sourcetree, --installtree and
773 --symlink-modules options.
774 The $autoinstall_all_kernels variable is used by the common postinst
776 for DKMS modules. It controls if the build should be done for all
777 installed kernels or only for the current and latest installed kernel.
778 It has no command line equivalent.
779
781 This boot-time service automatically installs any module which has
782 AUTOINSTALL="yes" set in its dkms.conf file. The service works quite
783 simply and if multiple versions of a module are in your system's DKMS
784 tree, it will not do anything and instead explain that manual interven‐
785 tion is required.
786
788 Changes that your module will make to /etc/modules.conf or /etc/mod‐
789 probe.conf should be specified with the MODULES_CONF_ALIAS_TYPE[#] ,
790 the MODULES_CONF_OBSOLETES[#] and the MODULES_CONF[#] directive arrays.
791 These arrays should also be used even if your distro uses /etc/syscon‐
792 fig/kernel to track kernel modules.
793 When the first module is installed upon the first kernel within the
795 user's system, these entries in MODULES_CONF[#] are automatically added
796 to /etc/modules.conf and if REMAKE_INITRD is specified, then the user's
797 initrd is then remade. Subsequently, as your modules are then later
798 removed from the user's system, until the final module/version combina‐
799 tion is removed from the final kernel version, those references in mod‐
800 ules.conf will remain. Once the last module/version combination is
801 removed, those references are then removed.
802 As modules/versions are removed and initrds are remade, one of three
804 things will happen if you have specified a MODULES_CONF_ALIAS_TYPE. If
805 no original_module exists for that kernel, and no MODULES_CONF_OBSO‐
806 LETES modules are found in that kernel too, the modules.conf alias ref‐
807 erences will temporarily be removed so that the initrd will success‐
808 fully remake. Once the initrd is remade, however; those references are
809 then automatically put back into modules.conf (unless you are removing
810 the last instance of the module on the last kernel). However, if no
811 original_module exists, but there is an OBSOLETE module found within
812 that kernel, the alias reference is temporarily shifted to point to the
813 OBSOLETE module so that the initrd can be remade. After it is remade,
814 it then automatically puts back the alias reference (unless you are
815 removing the last instance of the module on the last kernel). Lastly,
816 if an original_module does exist for the kernel version, then mod‐
817 ules.conf is not touched and all references persist (even if you are
818 removing the last instance of the module on the last kernel).
819 Certain module installations might not only require adding references
821 to modules.conf but also require removing conflicting references that
822 might exist in the user's system. If this is the case, the MOD‐
823 ULES_CONF_OBSOLETES[#] directive should be utilized to remove these
824 references. More information about this directive can be found in the
825 DKMS.CONF section of this man page.
826 Note that the end state of your modules.conf file very much depends on
828 what kernel modules exist in the final kernel you remove your DKMS mod‐
829 ule from. This is an imperfect system caused by the fact that there is
830 only one modules.conf file for every kernel on your system even though
831 various kernels use different modules. In a perfect world, there would
832 be one modules.conf file for every kernel (just like System.map).
833
835 See the sample.spec file packaged with DKMS as an example for what your
836 RPM spec file might look like. Creating RPMs which utilize dkms is a
837 fairly straight-forward process. The RPM need only to install the
838 source into /usr/src/<module>-<module-version>/ and then employ dkms
839 itself to do all the work of installation. As such, the RPM should
840 first untar the source into this directory. From here, within the RPM
841 .spec file, a dkms add should be called (remember to use the
842 --rpm_safe_upgrade flag during the add) followed by a dkms build fol‐
843 lowed by a dkms install. Your dkms.conf file should be placed within
844 the /usr/src/<module>-<module-version>/ directory.
845 Under the removal parts of the .spec file, all that needs to be called
847 is a: dkms remove -m <module> -v <module-version> --all
848 --rpm_safe_upgrade. Use of the --rpm_safe_upgrade flag is imperative
849 for making sure DKMS and RPM play nicely together in all scenarios of
850 using the -Uvh flag with RPM to upgrade dkms enabled packages. It will
851 only function if used during both the add and remove actions within the
852 same RPM spec file. Its use makes sure that when upgrading between dif‐
853 ferent releases of an RPM for the same <module-version>, DKMS does not
854 do anything dumb (eg. it ensures a smooth upgrade from
855 megaraid-2.09-5.noarch.rpm to megaraid-2.09-6.noarch.rpm).
856 It should be noted that a binary RPM which contains source is not a
858 traditional practice. However, given the benefits of dkms it hopefully
859 will become so. As the RPM created which utilizes dkms is not archi‐
860 tecture specific, BuildArch: noarch should be specified in the .spec
861 file to indicate that the package can work regardless of the system
862 architecture. Also note that DKMS RPM upgrades (-U option) will auto‐
863 matically work because of the structure of the dkms tree.
864 Lastly, as a matter of convention, you should name your RPM: <pack‐
866 age>-<version>-<rpm-version>dkms.noarch.rpm. The word dkms as part of
867 the rpm-version signifies that the RPM works within the DKMS framework.
868
870 Gary Lerhaupt
871
873 https://github.com/dell/dkms
874
876 http://www.dell.com/downloads/global/power/1q04-ler.pdf
877 http://www.linuxjournal.com/article.php?sid=6896
879
881 dkms-devel@dell.com http://lists.us.dell.com/mail‐
882 man/listinfo/dkms-devel
883
885 Kernel Module Packages http://kerneldrivers.org
886 Novell Kernel Module Packages http://www.suse.de/~agruen/KMPM
888 Fedora Kernel Module Packages http://fedoraproject.org/wiki/Extras/Ker‐
890 nelModuleProposal
891RELEASE_STRING-RELEASE_VERSION RELEASE_DATE DKMS(8)