forked from dell/dkms
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathdkms.8
1145 lines (1121 loc) · 42.4 KB
/
dkms.8
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
.\" -*- nroff -*-
.\"
.\" .SY, .YS, .OP macros from /usr/share/groff/1.21/tmac/an-ext.tmac
.\"
.\" Declare start of command synopsis. Sets up hanging indentation.
.de SY
. ie !\\n(mS \{\
. nh
. nr mS 1
. nr mA \\n(.j
. ad l
. nr mI \\n(.i
. \}
. el \{\
. br
. ns
. \}
.
. HP \w'\fB\\$1\fP\ 'u
. B "\\$1"
..
.
.
.\" End of command synopsis. Restores adjustment.
.de YS
. in \\n(mIu
. ad \\n(mA
. hy \\n(HY
. nr mS 0
..
.
.
.\" Declare optional option.
.de OP
. ie \\n(.$-1 \
. RI "[\fB\\$1\fP" "\ \\$2" "]"
. el \
. RB "[" "\\$1" "]"
..
.TH DKMS 8 RELEASE_DATE RELEASE_STRING-RELEASE_VERSION
.SH NAME
dkms \- Dynamic Kernel Module Support
.SH SYNOPSIS
.SY dkms
.OP action
.OP options
.OP module/module-version
.OP /path/to/source-tree
.OP /path/to/tarball.tar
.OP /path/to/driver.rpm
.YS
.SH DESCRIPTION
.B dkms
is a framework which allows kernel modules to be dynamically built
for each kernel on your system in a simplified and organized fashion.
.SH ACTIONS
.SY add
.OP module/module\-version
.OP /path/to/source\-tree
.OP /path/to/tarball.tar
.YS
.IP "" 4
Adds a module/module\-version combination to the tree for builds and installs.
If module/module\-version, \-m module/module\-version, or \-m module\ \-v version are passed as options, this command
requires source in
.I /usr/src/<module>\-<module\-version>/
as well as a properly
formatted
.I dkms.conf
file. If
.I /path/to/source\-tree
is passed as an option, and source-tree contains a
.I dkms.conf
file, it will copy
.I /path/to/source\-tree
to
.I /usr/src/module\-module\-version.
If
.I /path/to/tarball.tar
is passed, this command behaves like the
.B ldtarball
command.
.SY remove
.OP module/module\-version
.OP -k kernel/arch
.OP \-\-all
.YS
.IP "" 4
Removes a module/version or module/version/kernel/arch combination from the
tree. If the module is currently installed, it first uninstalls it
and if applicable, will replace it with its original_module. Use the
.B \-\-all
option in order to remove all instances for every kernel at once.
.SY build
.OP module/module\-version
.OP -k kernel/arch
.YS
.IP "" 4
Builds the specified module/version combo for the specified kernel/arch. If
the
.I \-k
option is not specified it builds for the currently running kernel and arch.. All builds
occur in the directory
.I /var/lib/dkms/<module>/<module\-version>/build/.
If the module/module\-version combo has not been added, dkms will try to add it, and in that
case
.B build
can take the same arguments that
.B add
can.
.SY unbuild
.OP module/module\-version
.OP -k kernel/arch
.OP \-\-all
.YS
.IP "" 4
Undoes the build for a module/version or module/version/kernel/arch combination from the
tree. If the module is currently installed, it first uninstalls it
and if applicable, will replace it with its original_module. Finally all binary
kernel modules are removed. Use the
.B \-\-all
option in order to remove all instances for every kernel at once.
.SY install
.OP module/module\-version
.OP -k kernel/arch
.OP /path/to/driver.rpm
.YS
.IP "" 4
Installs a built module/version combo onto the kernel it was built for. If
the kernel option is not specified it assumes the currently running kernel.
If the module has not been built, dkms will try to build it.
If the module has not been added, dkms will try to add it. In both cases, the
.B install
command can then take the same arguments as the
.B build
or
.B add
commands.
If you pass a .rpm file, dkms will try to install that file with
.B rpm -Uvh
, and it will perform an
.B autoinstall
action to be sure that everything is built for your kernel if the RPM installed successfully.
.SY uninstall
.OP module/module\-version
.OP -k kernel/arch
.OP \-\-all
.YS
.IP "" 4
Uninstalls an installed module/module\-version combo from the kernel/arch passed in the -k option, or the
current kernel if the -k option was not passed. Use the
.B \-\-all
option in order to uninstall all instances for every kernel at once.
After uninstall completion, the driver will be left in the built state.
To completely remove a driver, the remove action should be utilized.
.SY match
.OP --templatekernel kernel/arch
.OP -k kernel/arch
.YS
.IP "" 4
Match installs modules onto the specified kernel by looking at the
configuration of the specified
.B templatekernel.
Every module that is installed on the
.B templatekernel
within
.B dkms
is then installed on that specified kernel.
.SY mkdriverdisk
.OP -d distro
.OP -r release
.OP --media mediatype
.OP -k kernel/arch
.OP module/version
.YS
.IP "" 4
Creates a floppy driver disk image for use when updated drivers are needed
to install an OS. Currently, the supported distributions are redhat, suse
and UnitedLinux. For Red Hat driver disks, necessary driver disk files are
looked for in the redhat_driver_disk
subdirectory of your module source directory. You
must specify the distro while using this action. Driver disks can be made
for single kernels or can be made to support multiple kernels. To create
a driver disk image with modules for multiple kernels, just specify multiple
\-k parameters on the command line (\-k kernel1/arch1 \-k kernel2/arch2).
Red Hat introduced DDv3 starting with RHEL6. To create Red Hat DDv3, specify
.B \-d redhat3
and specify the specfile to use with
.I \-\-spec=specfile.
If no specfile is specified, DKMS will use
.I /etc/dkms/template\-dkms\-redhat\-kmod.spec
For suse/UnitedLinux driver disks, /usr/share/YaST2/modules/Vendor.ycp
will also be copied to the driver disk; no other files are needed.
However, for these distros, you must specify a \-r release. For
SuSE 9.1, it would be \-d suse \-r 9.1. For SLES9, it would be \-d suse \-r sles9.
By default the disk image it creates is 1440 (k) in size. This can be
overridden by specifying a different
.B \-\-size ####
which should should be given as a number in kilobytes divisible by 20.
You may have more content than will fit on a floppy. Therefore, DKMS
can now generate image files of different types.
.B \-\-media floppy (default)
to generate a floppy disk image, or
.B \-\-media iso
to generate a CD-ROM ISO file, or
.B \-\-media tar
to generate a tar file.
You may copy the floppy or ISO image file to a USB key to be used with
OS installer.
.SY mktarball
.OP module/module\-version
.OP -k kernel/arch
.OP --archive /path/to/tarball.tar
.OP --source-only
.OP --binaries-only
.YS
.IP "" 4
Creates a tarball archive for the specified module/version of all files
in the DKMS tree for that module/version combination. This includes
the source and any built modules for kernels in the tree (as specified).
Otherwise, you can specify
a singular kernel to archive only, or multiple kernels to archive
(\-k kernel1/arch1 \-k kernel2/arch2). Optionally, you can use
.B \-\-archive
to specify the file that you would like to save this
tarball to. You can also specify
.B \-\-binaries\-only
if you want the resultant tarball not to include the module source. Likewise,
.B \-\-source-only
can be used to specify that no prebuilt binaries should be included in the tarball.
In general,
.B mktarball
is great for systems management purposes as you can build your driver
on just one system and then use
.B ldtarball
on all of your other systems to get the same built modules loaded
without having to wait for anything to compile.
.SY ldtarball
.OP /path/to/tarball.tar
.OP --force
.YS
.IP "" 4
This takes a tarball made from the
.B mktarball
command and loads it into your DKMS tree. This will leave any
newly added modules in the built state and
.B dkms install
should then be called to install any of them. If files already
exist where
.B ldtarball
is attempting to place them, it will warn and not copy over them. The
.B \-\-force
option should be used to override this.
.SY mkrpm
.OP module/module\-version
.OP -k kernel/arch
.OP --source-only
.OP --binaries-only
.YS
.IP "" 4
This action allows you to create an RPM package for a specified module / version.
It uses a template .spec file found in
.I /etc/dkms/template\-dkms\-mkrpm.spec
as the basis for the RPM. Alternatively, if DKMS finds a file called
.I /usr/src/<module>\-<module\-version>/<module>\-dkms\-mkrpm.spec
it will use that .spec file instead. In general, a DKMS tarball is placed inside
the contents of this RPM, and the RPM itself calls various DKMS commands to
load this tarball, build and install modules on the end user's system. If you do
not want your RPM to contain any prebuilt binaries, be sure to specify
.B \-\-source\-only
in the mkrpm command.
.SY mkdeb
.OP module/module\-version
.OP -k kernel/arch
.YS
.IP "" 4
This action allows you to create a debian binary package for a specified module / version.
It uses a template debian directory found in
.I /etc/dkms/template\-dkms\-mkdeb
as the basis for the package. Alternatively, if DKMS finds a file called
.I /usr/src/<module>\-<module\-version>/<module>\-dkms\-mkdeb
it will use that folder instead. In general, a DKMS tarball is placed inside the
contents of this package, and the package itself calls various DKMS commands to
load this tarball, build and install modules on the end user's system.
.SY mkbmdeb
.OP module/module\-version
.OP -k kernel/arch
.YS
.IP "" 4
Creates a Debian binary package containing just the binary modules in the /lib/modules
installation path. This package does not depend on dkms and does not require a toolchain
to be installed on the target host. Useful if you want to have a package to install on
hosts identical to the build system without installing the full toolchain on them.
It uses a template debian directory found in
.I /etc/dkms/template\-dkms\-mkbmdeb
as the basis for the package.
.SY mkdsc
.OP module/module\-version
.OP -k kernel/arch
.YS
.IP "" 4
This action allows you to create a debian source package for a specified module / version.
It will create a .tar.gz, and a .dsc. All options supported by
.B mkdeb
are supported by it. The main difference in it's usage is that it will look in
.I /etc/dkms/template\-dkms\-mkdsc
as the basis for the package. Alternatively, if DKMS finds a file called
.I /usr/src/<module>\-<module\-version>/<module>\-dkms\-mkdsc
it will use that folder instead.
.SY mkkmp
.OP module/module\-version
.OP --spec specfile
.YS
.IP "" 4
This action allows you to create an Kernel Module Package source RPM for a specified module / version.
It uses the .spec file specified by
.I \-\-spec=specfile
else
.I $module\-kmp.spec
as the basis for the RPM. The generated source RPM may then be built using SuSE's build.rpm or
Fedora/RHEL's mock chroot environments. See http://kerneldrivers.org/ for
more details on KMPs.
.SY status
.OP module/module\-version
.OP -k kernel/arch
.YS
.IP "" 4
Returns the current status of modules, versions and kernels within
the tree as well as whether they have been added, built or installed.
Status can be shown for just a certain module, a certain kernel,
a module/version combination or a module/version/kernel combination.
.SY autoinstall
.YS
.IP "" 4
Attempt to install the latest revision of all modules that have been installed for other kernel revisions.
dkms_autoinstaller is a stub that uses this action to perform its work.
.SH OPTIONS
.TP
.B \-m <module>/<module\-version>
The name of the module and module version you want to operate on. The
.B \-m
part of this option is optional, and can be omitted in virtually all circumstances.
.TP
.B \-v <module\-version>
The version of the module to execute the specified action upon. This option only has to be specified
if you pass a
.B \-m
option without a <module\-version> component of its own.
.TP
.B \-k <kernel\-version>/<arch>
The kernel and arch to perform the action upon. You can specify multiple kernel version/arch pairs
on the command line by repeating the \-k argument with a different kernel version and arch.
However, not all actions support multiple kernel versions (it will error out
in this case).
The arch part can be omitted, and DKMS will assume you want it to be the arch of the currently running
system.
.TP
.B \-a, \-\-arch
The system architecture to perform the action upon. It is optional if you pass it as part of the
.B \-k
option. If not specified, it assumes
the arch of the currently running system (`uname \-m`). You can specify multiple
arch parameters on the same command line by repeating the \-a argument with a
different arch name. When multiple architectures are specified, there must
be a 1:1 relationship between \-k arguments to \-a arguments. DKMS will then
assume the first \-a argument aligns with the first \-k kernel and so on for the
second, third, etc.
For example, if you were to specify: \-k kernel1 \-k kernel2 \-a i386 \-k kernel3 \-a i686 \-a x86_64,
DKMS would process this as: kernel1-i386, kernel2-i686, kernel3-x86_64.
.TP
.B \-q, \-\-quiet
Quiet.
.TP
.B \-V, \-\-version
Prints the currently installed version of dkms and exits.
.TP
.B \-c <dkms.conf\-location>
The location of the
.I dkms.conf
file. This is needed for the add action and if not specified,
it is assumed to be located in
.I /usr/src/<module>\-<module\-version>/.
See below for more information on the format of
.I dkms.conf.
.TP
.B \-d, \-\-distro
The distribution being used. This is only currently needed for
.B mkdriverdisk.
The supported distros are
.B redhat,
.B suse
and
.B UnitedLinux.
See the sections on
.B mkdriverdisk
and
.B mkkmp
for more information.
.TP
.B \-r, \-\-release
The release being used. This is only currently used for
.B mkdriverdisk
and is only used for suse or UnitedLinux distros (eg. \-r 9.1). It is
used in the internal makeup of the driverdisk.
.TP
.B \-\-size
The size of the driver disk image to be created. By default, this value is set
at 1440. Any different size should be given as an integer value only, should
be divisible by 20 and should represent the number of kilobytes of the image
size you desire.
.TP
.B \-\-config <kernel\-.config\-location>
During a
.B build
this option is used to specify an alternate location for the kernel .config
file which was used to compile that kernel. Normally,
.B dkms
uses the Red Hat standard location and config filenames located in
.I /usr/src/linux\-<kernel>/configs/.
If the config for the kernel that you
are building a module for is not located here or does not have the expected
name in this location, you will need to tell
.B dkms
where the necessary .config can be found so that your kernel can be properly
prepared for the module build.
.TP
.B \-\-archive <tarball\-location>
This option is used during a
.B ldtarball
action to specify the location of the tarball you wish to load into
your DKMS tree. You only have to specify the
.B --archive
part of this option if <tarball\-location> does not already exist as a file.
.TP
.B \-\-templatekernel <kernel\-version>
This option is required for the action:
.B match.
Match will look at the
templatekernel specified and install all of the same module/version
combinations on the other kernel.
.TP
.B \-\-force
This option can be used in conjunction with
.B ldtarball
to force copying over of extant files.
.TP
.B \-\-binaries\-only
This option can be used in conjunction with
.B mktarball
in order to create a DKMS tarball which does not contain the source for the
module within it. This can be helpful in reducing the size of the tarball
if you know that the system which this tarball will be loaded upon already
has the source installed. In order to load a tarball made as binaries-only
.B you must
have the module source in that systems DKMS tree. If you do not, DKMS
.B will refuse
to load a binaries-only tarball.
.TP
.B \-\-source\-only
This option can be used in conjunction with
.B mktarball
or
.B mkrpm
or
.B mkdeb
in order to create a DKMS tarball which does not contain any prebuilt
kernel module binaries within it. This is helpful if you simply want
to easily tar up your source but don't want anything prebuilt within
it. Likewise, if you are using
.B mkrpm
but do not want the RPM you create to have any prebuilt modules within it,
passing this option will keep its internal DKMS tarball from containing any
prebuilt modules.
.TP
.B \-\-all
This option can be used to automatically specify all relevant kernels/arches
for a module/module-version. This is useful for things like
.B remove
,
.B mktarball
, etc. This saves the trouble of having to actually specify \-k kernel1 \-a
arch1 \-k kernel2 \-a arch2 for every kernel you have built your module for.
.TP
.B \-\-no\-prepare\-kernel
This option keeps DKMS from first preparing your kernel before building
a module for it. Generally, this option should not be used so as to
ensure that modules are compiled correctly.
.TP
.B \-\-no\-clean\-kernel
This option keeps DKMS from cleaning your kernel source tree after a
build.
.TP
.B \-\-no\-depmod
This option prevents DKMS from running the depmod command during
.B install
and
.B uninstall
which will avoid (re)calculating module dependencies and thereby save time.
.TP
.B \-\-kernelsourcedir <kernel\-source\-directory\-location>
Using this option you can specify the location of your kernel source
directory. Most likely you will not need to set this if your kernel
source is accessible via
.I /lib/modules/$kernel_version/build.
.TP
.B \-\-directive <"cli\-directive=cli\-value">
Using this option, you can specify additional directives from the command
line. The
.B \-\-directive
option can be used multiple times on the same command-line to specify
multiple additional command line directives.
.TP
.B \-\-rpm_safe_upgrade
This flag should be used when packaging DKMS enabled modules in RPMs. It should
be specified during both the
.B add
and
.B remove
actions in the RPM spec to ensure that DKMS and RPM behave correctly in all
scenarios when upgrading between various versions of a dkms enabled module
RPM package. See the sample.spec file for an example or read more in the section
below on Creating RPMs Which Utilize DKMS.
.TP
.B \-\-spec specfile
This option is used by the
.B mkkmp
action to specify which RPM spec file to use when generating the KMP.
.I specfile
will be sought in the module source directory.
.TP
.B \-\-dkmstree path/to/place
Provides a destination tree for building and installing modules to. Useful in
cases that you don't want to contaminate a system when using solely for building.
.TP
.B \-\-sourcetree path/to/place
Provides a location to build a DKMS package from. Useful for systems that you may
not have root access, but would still like to be able to build DKMS packages.
.TP
.B \-\-installtree path/to/place
Provides a location to place modules when a
.I dkms install
command is issued.
.TP
.B \-\-legacy\-postinst=[0|1]
Includes a legacy postinstall script so that a DEB or RPM built by DKMS can be used on versions
prior than DKMS 2.1. This option currently defaults to 1.
.TP
.B \-\-dkmsframework path/to/file
A supplemental configuration file to the system-wide dkms framework, typically located
in /etc/dkms/framework.conf. All option that are normally provided on a command line
can be provided in this file.
.TP
.B \-j number
Run no more than
.I number
jobs in parallel; see the -j option of
.I make(1).
Defaults to the number of CPUs in the system, detected by
.I nproc(1).
Specify 0 to impose no limit on the number of parallel jobs.
.SH ORIGINAL MODULES
During the first install of a module for a <kernelversion>,
.B dkms
will search
.I /lib/modules/<kernelversion>
for a pre-existing module of the same name. If one is found, it will automatically
be saved as an "original_module" so that if the newer module is later removed,
.B dkms
will put the original module back in its place. Currently, DKMS searches
for these original modules with first preference going to modules located in
.I /lib/modules/<kernelversion>/updates/
followed by
.B $DEST_MODULE_LOCATION
(as specified in
.I dkms.conf
). If one cannot be found in either location, a find will be used to locate one for
that kernel.
If none are found, then during a later uninstall, your kernel will not have that module
replaced.
If more than one is found, then the first one located (by preference indicated
above) will be considered the "original_module". As well, all copies of the same-named
module will be removed from your kernel tree and placed into
.I /var/lib/dkms/<module>/original_module/$kernelver/collisions
so that they can be *manually* accessible later. DKMS will never actually do anything
with the modules found underneath the /collisions directory, and they will be stored there
until you manually delete them.
.SH DKMS.CONF
When performing an
.B add
, a proper
.I dkms.conf
file must be found. A properly formatted conf file is essential
for communicating to
.B dkms
how and where the module should be installed. While not all the directives
are required, providing as many as possible helps to limit any ambiguity. Note
that the
.I dkms.conf
is really only a shell\-script of variable definitions which are then sourced in
by the
.B dkms
executable (of the format, DIRECTIVE="directive text goes here"). As well, the
directives are case\-sensitive and should be given in
.B ALL CAPS.
It is important to understand that many of the DKMS directives are arrays whose index
values are tied together. These array associations can be considered families, and there
are currently four such families of directive arrays. MAKE[#] and MAKE_MATCH[#] make up
one family. PATCH[#] and PATCH_MATCH[#] make up the second family. The third and
largest family consists of BUILT_MODULE_NAME[#], BUILT_MODULE_LOCATION[#], DEST_MODULE_NAME[#],
DEST_MODULE_LOCATION[#], MODULES_CONF_ALIAS_TYPE[#], MODULES_CONF_OBSOLETES[#],
MODULES_CONF_OBSOLETE_ONLY[#] and STRIP[#]. The fourth
family is made up of only MODULES_CONF[#]. When indexing these arrays when creating your
dkms.conf, each family should start at index value 0.
.TP
.B MAKE[#]=
The MAKE directive array tells DKMS which make command should be used for building your module. The default make command
should be put into
.B MAKE[0].
Other entries in the MAKE array will only be used if their corresponding entry in
.B MAKE_MATCH[#]
matches, as a regular expression (using egrep), the kernel that the module is being built for.
Note that if no value is placed in
.B MAKE_MATCH[#]
for any
.B MAKE[#]
where # > 0, then that
.B MAKE
directive is ignored.
.B MAKE_MATCH[0]
is optional and if it is populated, it will be used to determine
if MAKE[0] should be used to build the module for that kernel. If multiple
.B MAKE_MATCH
directives match against the kernel being built for, the last matching
.B MAKE[#]
will be used to build your module. If no MAKE directive is specified or if no
MAKE_MATCH matches the kernel being built for, DKMS
will attempt to use a generic MAKE command to build your module.
KERNELRELEASE will be automatically appended to MAKE[#]. If you want to
suppress this behavior, you can quote the make command: 'make'.
.TP
.B MAKE_MATCH[#]=
See the above entry on
.B MAKE[#]
directives. This array should be populated with regular expressions which, when matched
against the kernel being built for, will tell
.B DKMS
to use the corresponding make command in the
.B MAKE[#]
directive array to build your module.
.TP
.B BUILT_MODULE_NAME[#]=
This directive gives the name of the module just after it is built. If your DKMS module
package contains more than one module to install, this is a
.B required
directive for all of the modules. This directive should explicitly not contain any
trailing ".o" or ".ko".
Note that for each module within a dkms package, the numeric value of
.B #
must be the same for each of BUILT_MODULE_NAME, BUILT_MODULE_LOCATION, DEST_MODULE_NAME and
DEST_MODULE_LOCATION and that the numbering should start at 0 (eg. BUILT_MODULE_NAME[0]="qla2200"
BUILT_MODULE_NAME[1]="qla2300").
.TP
.B BUILT_MODULE_LOCATION[#]=
This directive tells DKMS where to find your built module after it has been built. This
pathname should be given relative to the root directory of your source files (where your
dkms.conf file can be found). If unset, DKMS expects to find your
.B BUILT_MODULE_NAME[#]
in the root directory of your source files.
Note that for each module within a dkms package, the numeric value of
.B #
must be the same for each of BUILT_MODULE_NAME, BUILT_MODULE_LOCATION, DEST_MODULE_NAME and
DEST_MODULE_LOCATION and that the numbering should start at 0 (eg. BUILT_MODULE_LOCATION[0]="some/dir/"
BUILT_MODULE_LOCATION[1]="other/dir/").
.TP
.B DEST_MODULE_NAME[#]=
This directive can be used to specify the name of the module as it should be installed. This
will rename the module from
.B BUILT_MODULE_NAME[#]
to
.B DEST_MODULE_NAME[#].
This directive should explicitly not contain any trailing ".o" or ".ko". If unset, it is
assumed to be the same value as
.B BUILT_MODULE_NAME[#].
Note that for each module within a dkms package, the numeric value of
.B #
must be the same for each of BUILT_MODULE_NAME, BUILT_MODULE_LOCATION, DEST_MODULE_NAME and
DEST_MODULE_LOCATION and that the numbering should start at 0 (eg. DEST_MODULE_NAME[0]="qla2200_6x"
DEST_MODULE_NAME[1]="qla2300_6x").
.TP
.B DEST_MODULE_LOCATION[#]=
This directive specifies the destination where a module should be installed to, once compiled. It also
is used for finding original_modules. This is a
.B required
directive, except as noted below. This directive must start with the text "/kernel" which is in reference to
/lib/modules/<kernelversion>/kernel.
Note that for each module within a dkms package, the numeric value of
.B #
must be the same for each of BUILT_MODULE_NAME, BUILT_MODULE_LOCATION, DEST_MODULE_NAME and
DEST_MODULE_LOCATION and that the numbering should start at 0 (eg. DEST_MODULE_LOCATION[0]="/kernel/drivers/something/"
DEST_MODULE_LOCATION[1]="/kernel/drivers/other/").
DEST_MODULE_LOCATION is ignored on Fedora and Red Hat Enterprise Linux, Novell SuSE Linux Enterprise Server 10
and higher, Novell SuSE Linux 10.0 and higher, and Ubuntu. Instead, the proper distribution-specific directory is used.
.TP
.B MODULES_CONF_ALIAS_TYPE[#]=
This directive array specifies how your modules should be aliased in
.I /etc/modules.conf
when your module is installed. This is done in an intelligent fashion so if DKMS
detects an already existing reference in modules.conf, it won't add a new line. If
it is not detected, it will add it to the modules.conf as the last alias number for
that alias type (eg. if MODULES_CONF_ALIAS_TYPE="scsi_hostadapter", no alias
currently exists for that module and the last scsi_hostadapter reference is 6, then
your module will be added as "scsi_hostadapter7"). Common values for this directive
include:
.B scsi_hostadapter
,
.B sound\-slot\-
and
.B eth.
Note that the numeric value of
.B #
is tied to the index of BUILT_MODULE_NAME, BUILT_MODULE_LOCATION, DEST_MODULE_NAME
and DEST_MODULE_LOCATION. The index is also tied to MODULES_CONF_OBSOLETES.
.TP
.B MODULES_CONF_OBSOLETES[#]=
This directive array tells DKMS what modules.conf alias references are obsoleted by the
module you are installing. If your module obsoletes more than one module, this directive
should be a comma\-delimited list of those modules that are obsoleted (eg. for megaraid2,
MODULES_CONF_OBSOLETES[0]="megaraid,megaraid_2002"). When you are installing your module,
DKMS ensures that any entries in
.I /etc/modules.conf
with the same
.B MODULES_CONF_ALIAS_TYPE
are changed over to the new module name. When you are uninstalling
your module, depending on the modules in your
.I /lib/modules
tree, DKMS will take different actions.
If you kernel has an original_module, then modules.conf will not be touched and the non\-obsolete
reference will remain. If the kernel does not have an original_module but does have one
of the obsolete modules, it will replace those references with the first obsolete module name in
the comma\-delimited list that is also in that kernel (thus, your obsolete list should be prioritized
from left to right). If no original_module or obsolete modules are found within the kernel, the alias
entry is removed all\-together. Note that the numeric value of
.B #
is tied to the index of BUILT_MODULE_NAME, BUILT_MODULE_LOCATION, DEST_MODULE_NAME
and DEST_MODULE_LOCATION. The index is also tied to MODULES_CONF_ALIAS_TYPE.
.TP
.B MODULES_CONF_OBSOLETE_ONLY[#]=
If set to
.B yes
, this directive will tell DKMS to only modify
.I /etc/modules.conf
if it finds within it an obsolete reference as specified in the corresponding value of
.B MODULES_CONF_OBSOLETES[#]
array directive.
.TP
.B STRIP[#]=
By default strip is considered to be "yes". If set to "no", DKMS will not
run strip \-g against your built module to remove debug symbols from it.
STRIP[0] is used as the default for any unset entries in the STRIP array.
.TP
.B PACKAGE_NAME=
This directive is used to give the name associated with the entire package of modules. This is the same
name that is used with the
.B \-m
option when building, adding, etc. and may not necessarily be the same as the MODULE_NAME. This
directive must be present in every dkms.conf.
.TP
.B PACKAGE_VERSION=
This directive is used to give the version associated with the entire package of modules being installed within that dkms
package. This directive must be present in every dkms.conf.
.TP
.B CLEAN=
CLEAN specifies the make clean command to be used to clean up both before and after building the
module. If unset, it is assumed to be "make clean".
.TP
.B REMAKE_INITRD=
This directive specifies whether your initrd should be remade after the module is installed
onto the kernel. Any text after the first character is ignored and if the first character
is not a "y" or a "Y", it is assumed that REMAKE_INITRD="no".
.TP
.B MODULES_CONF[#]=
This directive array specifies what static configuration text
lines need to be added into
.I /etc/modules.conf
for your module. See the section on MODULES.CONF CHANGES for more information regarding the
implications of modifying
.I /etc/modules.conf
.TP
.B OBSOLETE_BY=
This directive allows you to specify a kernel version that obsoletes the necessity for this
particular DKMS module. This can be specified as a particular upstream kernel or an ABI
bump of a kernel. For example, "2.6.24" would be an upstream kernel and "2.6.24\-16" would
represent an ABI bump for a kernel. Both are valid in this area.
Please avoid the use of
.B OBSOLETE_BY
wherever possible. It's use indicates a lack of proper module
versioning using
.B MODULE_VERSION()
tags in the module source itself. It is better to fix the
.B MODULE_VERSION()
tags than use
.B OBSOLETE_BY.
This also introduces a implicit distribution/version dependency on the
package, as the value of
.B OBSOLETE_BY
is meaningful only in the context of a single distribution/version.
If you feel you must use it, please use as such in dkms.conf:
ubuntu_804="Ubuntu
8.04"
if [ \-x /usr/bin/lsb_release ]; then
if [ "$(/usr/bin/lsb_release \-sir)" == "${ubuntu_804}" ]; then
OBSOLETE_BY="2.6.25"
fi
fi
.TP
.B PATCH[#]=
Use the PATCH directive array to specify patches which should be applied to your source before a build occurs.
All patches are expected to be in \-p1 format and are applied with the patch \-p1 command.
Each directive should specify the filename of the patch to apply, and all patches must
be located in the patches subdirectory of your source directory (
.I /usr/src/<module>\-<module\-version>/patches/
). If any patch fails to apply, the build will be halted and the rejections can be
inspected in
.I /var/lib/dkms/<module>/<module\-version>/build/.
If a PATCH should only be applied conditionally, the
.B PATCH_MATCH[#]
array should be used, and a corresponding regular expression should be placed in
.B PATCH_MATCH[#]
which will alert dkms to only use that
.B PATCH[#]
if the regular expression matches the kernel which the module is currently being built for.
.TP
.B PATCH_MATCH[#]=
See the above description for
.B PATCH[#]
directives. If you only want a patch applied in certain scenarios, the
.B PATCH_MATCH
array should be utilized by giving a regular expression which matches
the kernels you intend the corresponding
.B PATCH[#]
to be applied to before building that module.
.TP
.B AUTOINSTALL=
If this directive is set to
.B yes
then the service
.I /etc/rc.d/init.d/dkms_autoinstaller
will automatically try to install this module on any kernel you boot into. See the section
on
.B dkms_autoinstaller
for more information.
.TP
.B BUILD_DEPENDS[#]=
This optional directive is an array that allows you to specify other modules as
dependencies for your module. Each array element should be the
.B PACKAGE_NAME
of another module that is managed by dkms. Do not specify a version or
architecture in the dependency. Note that this directive is only advisory;
missing or broken dependencies cause non-fatal warnings.
.TP
.B BUILD_EXCLUSIVE_KERNEL=
This optional directive allows you to specify a regular expression which defines
the subset of kernels which DKMS is allowed to build your module for. If the kernel
being built for does not match against this regular expression, the dkms build
will error out. For example, if you set it as ="^2\.4.*", your module would not be
built for 2.6 kernels.
.TP
.B BUILD_EXCLUSIVE_ARCH=
This optional directive functions very similarly to
.B BUILD_EXCLUSIVE_KERNEL
except that it matches against the kernel architecture. For example, if you set
it to ="i.86", your module would not be built for ia32e, x86_64, amd64, s390, etc.
.TP
.B POST_ADD=
The name of the script to be run after an
.B add
is performed. The path should be given relative to the root directory of your source.
.TP
.B POST_BUILD=
The name of the script to be run after a
.B build
is performed. The path should be given relative to the root directory of your source.
.TP
.B POST_INSTALL=
The name of the script to be run after an
.B install
is performed. The path should be given relative to the root directory of your source.
.TP
.B POST_REMOVE=
The name of the script to be run after a
.B remove
is performed. The path should be given relative to the root directory of your source.
.TP
.B PRE_BUILD=
The name of the script to be run before a
.B build
is performed. The path should be given relative to the root directory of your source.
.TP
.B PRE_INSTALL=
The name of the script to be run before an
.B install
is performed. The path should be given relative to the root directory
of your source. If the script exits with a non\-zero value, the
install will be aborted. This is typically used to perform a custom
version comparison.
.TP
.SH DKMS.CONF VARIABLES
Within your
.I dkms.conf
file, you can use certain variables which will be replaced at run\-time with their
values.
.TP
.B $kernelver
This variable can be used within a directive definition and during use, the actual kernel
version in question will be substituted in its place. This is especially useful in MAKE
commands when specifying which INCLUDE statements should be used when compiling your
module (eg. MAKE="make all INCLUDEDIR=/lib/modules/${kernelver}/build/include").
.TP
.B $dkms_tree
See the section on /etc/dkms/framework.conf for more information. This variable represents
the location of the DKMS tree on the local system. By default this is
.I /var/lib/dkms
, but this value should not be hard\-coded into a dkms.conf in the event that the local user
has changed it on their system.
.TP
.B $source_tree
See the section on /etc/dkms/framework.conf for more information. This variable represents
the location where DKMS keeps source on the local system. By default this is
.I /usr/src
, but this value should not be hard\-coded into a dkms.conf in the event that the local user
has changed it on their system.
.TP
.B $kernel_source_dir
This variable holds the value of the location of your kernel source directory. Usually, this
will be
.I /lib/modules/$kernelver/build
, unless otherwise specified with the
.B \-\-kernelsourcedir
option.
.SH DKMS.CONF OVERRIDES
You can override the module-provided
.I dkms.conf
files. Every time after a dkms.conf file is read, dkms will look for and read the following files in order:
.PP
.I /etc/dkms/<module>.conf
.br
.I /etc/dkms/<module>\-<module\-version>.conf
.br
.I /etc/dkms/<module>\-<module\-version>\-<kernel>.conf
.br
.I /etc/dkms/<module>\-<module\-version>\-<kernel>\-<arch>.conf
.PP
You can use these files to override settings in the module-provided dkms.conf files.
.SH /etc/dkms/framework.conf
This configuration file controls how the overall DKMS framework handles. It is sourced
in every time the dkms command is run. Mainly it can currently be used to set different
default values for the variables.
.TP
.B $dkms_tree, $source_tree, $install_tree
control where DKMS looks for its framework.
.TP
.B $symlink_modules
controls whether binary modules are copied to /lib/modules or if only symlinks are created there. Note that these variables can also
be manipulated on the command line with \-\-dkmstree, \-\-sourcetree, \-\-installtree
and \-\-symlink-modules options.
.TP
.B $sign_tool
Script to be run at build for signing modules.
Two arguments will be passed to the script. The first argument is the
.B target kernel version
, the second is the
.B module file path.
If the script exits with a non\-zero value, the build will be aborted.
.TP
.B $autoinstall_all_kernels
used by the common postinst for DKMS modules. It controls if the build should be done for all installed kernels or only for the current and latest installed kernel. It has no command
line equivalent.
.SH dkms_autoinstaller
This boot\-time service automatically installs any module which has
.B AUTOINSTALL="yes"
set in its
.B dkms.conf
file. The service works quite simply and if multiple versions of a module are in
your system's DKMS tree, it will not do anything and instead explain that manual
intervention is required.
.SH MODULES.CONF / MODPROBE.CONF CHANGES