diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 199 |
1 files changed, 199 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..763bd2d --- /dev/null +++ b/README.md @@ -0,0 +1,199 @@ +Dynamic Kernel Module System (DKMS) +== +This intention of this README is to explain how DKMS can be used in conjunction +with tarballs which contain a dkms.conf file within them. + +The DKMS project (and any updates) can be found at: https://github.com/dell/dkms + +Installation +-- + +Installation is performed from the source directory with one of the following +commands: + +``` +make install +make install-debian +make install-redhat +``` + +Distribution specific installations (RPM, DEB, etc.) are not contained in this +source repository. + + +Installation via DKMS Tarballs +-- + +DKMS can install directly from the following: + +1. Generic module source tarballs which contain a dkms.conf file +2. Specially created DKMS tarballs with module source, pre-built module + binaries and a dkms.conf file +3. Specially created DKMS tarballs with pre-built module binaries and a + dkms.conf file +4. Manual placement of module source and dkms.conf file into + `/usr/src/<module>-<moduleversion>/` directory + +In order to load any tarball into the DKMS tree, you must use the following +command: + +``` +# dkms ldtarball /path/to/dkms_enabled.tar.gz +``` + +This command will first inspect the tarball to ensure that it contains a +dkms.conf configuration file for that module. If it cannot find this file +anywhere within the archive, then the ldtarball will fail. + +From here, it will place the source in the tarball into +`/usr/src/<module>-<moduleversion>/`. If source already exists in the directory, +it will not overwrite it unless the --force option is specified. If the tarball +is of type "c" above and does not contain source, it will only continue to load +the tarball if existing module source is found in +`/usr/src/<module>-<moduleversion>/` or if the --force option is specified. + +Continuing on, if the tarball is of type "b" or "c" it will then load any +pre-built binaries found within the tarball into the dkms tree, but will stop +short of installing them. Thus, all pre-built binaries will then be of in the +*built* state when checked from the `dkms status` command. You can then use the +`dkms install` command to install any of these binaries. + +To create a tarball of type "1" above, you need only to take module source and a +dkms.conf file for that module and create a tarball from them. Tarballs of +type *2* or type *3* are created with the `dkms mktarball` command. To create +a type *3* tarball, you must specify the flag `--binaries-only` with the +`mktarball`. + + + +Installation on Systems with no Module Source and/or Compiler +-- + +If you choose not to load module source on your system or if you choose not to +load a compiler such as gcc onto your system, DKMS can still be used to install +modules. It does this through use of DKMS binary only tarballs as explained in +this README under tarballs of type *c*. + +If your system does not have module source, loading the dkms tarball will fail +because of this. To avoid this, use the --force flag, as such: + +``` +# dkms ldtarball /path/to/dkms_enabled.tar.gz --force +``` + +This will load the pre-built binaries into the dkms tree, and create the +directory `/usr/src/<module>-<moduleversion>/` which will only contain the +module's dkms.conf configuration file. Once the tarball is loaded, you can then +use `dkms install` to install any of the pre-built modules. + +Of course, since module source will not be located in your dkms tree, you will +not be able to build any modules with DKMS for this package. + +Module signing +-- + +By default, DKMS generates a self signed certificate for signing modules at +build time and signs every module that it builds before it gets compressed in +the configured kernel compression mechanism of choice. + +This requires the `openssl` command to be present on the system. + +Private key and certificate are auto generated the first time DKMS is run and +placed in `/var/lib/dkms`. These certificate files can be pre-populated with +your own certificates of choice. + +The location as well can be changed by setting the appropriate variables in +`/etc/dkms/framework.conf`. For example, to allow usage of the system default +Ubuntu `update-secureboot-policy` set the configuration file as follows: +``` +mok_signing_key="/var/lib/shim-signed/mok/MOK.priv" +mok_certificate="/var/lib/shim-signed/mok/MOK.der" +``` +NOTE: If any of the files specified by `mok_signing_key` and +`mok_certificate` are non-existant, dkms will re-create both files. + +The paths specified in `mok_signing_key`, `mok_certificate` and `sign_file` can +use the variable `${kernelver}` to represent the target kernel version. +``` +sign_file="/lib/modules/${kernelver}/build/scripts/sign-file" +``` + +The variable `mok_signing_key` can also be a `pkcs11:...` string for a [PKCS#11 +engine](https://www.rfc-editor.org/rfc/rfc7512), as long as the `sign_file` +program supports it. + +Secure Boot +-- + +On an UEFI system with Secure Boot enabled, modules require signing (as +described in the above paragraph) before they can be loaded and the firmware of +the system must know the correct public certificate to verify the module +signature. + +For importing the MOK certificate make sure `mokutil` is installed. + +To check if Secure Boot is enabled: + +``` +# mokutil --sb-state +SecureBoot enabled +``` + +With the appropriate key material on the system, enroll the public key: + +``` +# mokutil --import /var/lib/dkms/mok.pub +``` + +You'll be prompted to create a password. Enter it twice, it can also be blank. + +Reboot the computer. At boot you'll see the MOK Manager EFI interface: + + + +Press any key to enter it, then select "Enroll MOK": + + + +Then select "Continue": + + + +And confirm with "Yes" when prompted: + + + +After this, enter the password you set up with `mokutil --import` in the +previous step: + + + +At this point you are done, select "OK" and the computer will reboot trusting +the key for your modules: + + + +After reboot, you can inspect the MOK certificates with the following command: + +``` +# mokutil --list-enrolled | grep DKMS + Subject: CN=DKMS module signing key +``` + +To check the signature on a built DKMS module that is installed on a system: + +``` +# modinfo dkms_test | grep ^signer +signer: DKMS module signing key +``` + +The module can now be loaded without issues. + +Further Documentation +-- + +Once DKMS is installed, you can reference its man page for further information +on different DKMS options and also to understand the formatting of a module's +dkms.conf configuration file. + +The DKMS project is located at: https://github.com/dell/dkms |