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