1DKMS(8)                     System Manager's Manual                    DKMS(8)
2
3
4

NAME

6       dkms - Dynamic Kernel Module Support
7

SYNOPSIS

9       dkms [action] [options] [module/module-version] [/path/to/source-tree]
10            [/path/to/tarball.tar] [/path/to/driver.rpm]
11

DESCRIPTION

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

ACTIONS

17       add [module/module-version] [/path/to/source-tree]
18           [/path/to/tarball.tar]
19
20           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
30       remove [module/module-version] [-k kernel/arch] [--all]
31
32           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
38       build [module/module-version] [-k kernel/arch]
39
40           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
47       install [module/module-version] [-k kernel/arch] [/path/to/driver.rpm]
48
49           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
59       uninstall [module/module-version] [-k kernel/arch]
60
61           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
67       match [--templatekernel kernel/arch] [-k kernel/arch]
68
69           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
74       mkdriverdisk [-d distro] [-r release] [--media mediatype]
75                    [-k kernel/arch] [module/version]
76
77           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
88           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
93           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
99           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
103           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
108           You may copy the floppy or ISO image file to a USB key to  be  used
109           with OS installer.
110
111       mktarball [module/module-version] [-k kernel/arch]
112                 [--archive /path/to/tarball.tar] [--source-only] [--binaries-
113                 only]
114
115           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
130       ldtarball
131
132           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
139       mkrpm [module/module-version] [-k kernel/arch] [--source-only]
140             [--binaries-only]
141
142           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
153       mkdeb [module/module-version] [-k kernel/arch] [--binaries-only]
154             [--source-only]
155
156           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
168       mkdsc [module/module-version] [-k kernel/arch] [--binaries-only]
169             [--source-only]
170
171           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
181       mkkmp [module/module-version] [--spec specfile]
182
183           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
190       status [module/module-version] [-k kernel/arch]
191
192           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
198       autoinstall
199
200           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

OPTIONS

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
210       -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
215       -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
224       -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
235              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
239       -q, --quiet
240              Quiet.
241
242       -V, --version
243              Prints the currently installed version of dkms and exits.
244
245       -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
251       -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
257       -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
263       --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
268       --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
279       --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
285       --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
290       --force
291              This  option  can be used in conjunction with ldtarball to force
292              copying over of extant files.
293
294       --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
304       --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
314       --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
320       --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
325       --no-clean-kernel
326              This option keeps DKMS from cleaning  your  kernel  source  tree
327              after a build.
328
329       --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
334       --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
340       --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
346       --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
355       --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
360       --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
365       --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
370       --installtree path/to/place
371              Provides a location to place modules when a dkms install command
372              is issued.
373
374       --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
379       --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
385       -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

ORIGINAL MODULES

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
404       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

DKMS.CONF

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
423       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
435       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
452              KERNELRELEASE will be automatically appended to MAKE[#].  If you
453              want  to suppress this behavior, you can quote the make command:
454              'make'.
455
456       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
463       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
474       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
486       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
499       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
512              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
517       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  BUILD_MODULE_NAME,  BUILT_MODULE_LOCATION,
530              DEST_MODULE_NAME and DEST_MODULE_LOCATION.  The  index  is  also
531              tied to MODULES_CONF_OBSOLETES.
532
533       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 BUILD_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
557       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
563       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
569       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
576       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
581       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
585       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
591       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
597       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
605              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
613              If you feel you must use it, please use as such in dkms.conf:
614
615               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
624
625       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
641       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
648       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
654       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
662       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
670       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
676       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
681       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
686       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
691       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
696       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
701       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
708
709       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
713       $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
721       $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
728       $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
735       $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

DKMS.CONF OVERRIDES

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
746       /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
751       You  can  use  these  files to override settings in the module-provided
752       dkms.conf files.
753

/etc/dkms/framework.conf

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
765       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

dkms_autoinstaller

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

MODULES.CONF / MODPROBE.CONF CHANGES

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
784       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
793       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
810       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
817       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

CREATING RPMS WHICH UTILIZE DKMS

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
836       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
847       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
855       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

AUTHOR

860       Gary Lerhaupt
861

WEBPAGE

863       https://github.com/dell/dkms
864

WHITE-PAPERS

866       http://www.dell.com/downloads/global/power/1q04-ler.pdf
867
868       http://www.linuxjournal.com/article.php?sid=6896
869

MAILING-LIST

871       dkms-devel@dell.com                      http://lists.us.dell.com/mail
872       man/listinfo/dkms-devel
873

REFERENCES

875       Kernel Module Packages http://kerneldrivers.org
876
877       Novell Kernel Module Packages http://www.suse.de/~agruen/KMPM
878
879       Fedora Kernel Module Packages http://fedoraproject.org/wiki/Extras/Ker
880       nelModuleProposal
881
882
883
884RELEASE_STRING-RELEASE_VERSION   RELEASE_DATE                          DKMS(8)
Impressum