mirror of
https://github.com/SCST-project/scst.git
synced 2026-08-22 07:06:22 +00:00
docs: Refresh build and installation guides
The top-level guides still describe retired source, QLogic, service and kernel-support workflows. Following them can select the wrong driver, cross-compile only part of the tree, or misstate module-signing policy. Commit7aade0a109("Makefile: Make the qla2x00t-32gbit driver the default QLogic FC driver") made the newer tree the default. Commit0d3c9018af("debian, scstadmin: Add systemd scst.service") added the installed systemd unit. Point source users at GitHub and kernel support at nightly/conf/nightly.conf. Separate kernel and user-space cross builds, follow the current service recipes, and make module acceptance depend on the target kernel and platform policy.
This commit is contained in:
Gleb Chesnokov
+14
-2
@@ -12,12 +12,19 @@ If the following packages have not yet been installed, install these now:
|
||||
libelf-dev, libelf-devel or elfutils-libelf-devel
|
||||
libperl-dev or perl-devel
|
||||
make
|
||||
openssl (if CONFIG_MODULE_SIG is enabled in the target kernel)
|
||||
perl
|
||||
perl-Data-Dumper
|
||||
perl-ExtUtils-MakeMaker (not needed on Debian systems)
|
||||
rpm-build (only on RPM-based systems)
|
||||
tar
|
||||
|
||||
## Supported kernel versions
|
||||
|
||||
The maintained list of supported upstream and distribution kernels is the
|
||||
`ABT_KERNELS` list in `nightly/conf/nightly.conf`. The GitHub Actions
|
||||
regression matrix is a subset and is not the complete support list.
|
||||
|
||||
## Building SCST
|
||||
|
||||
The next step is to build and install SCST. How to do that depends on whether
|
||||
@@ -75,8 +82,13 @@ following information is present in /etc/scst.conf:
|
||||
For more information about scst.conf, see also
|
||||
scstadmin/scstadmin.sysfs/man5/scst.conf.5.
|
||||
|
||||
Loading the SCST kernel modules and applying the /etc/scst.conf configuration
|
||||
file is possible as follows:
|
||||
On systems that use systemd, load the SCST kernel modules and apply the
|
||||
/etc/scst.conf configuration as follows:
|
||||
|
||||
systemctl restart scst
|
||||
|
||||
The installed systemd unit delegates these operations to the SCST init script.
|
||||
On systems without systemd, use the init script directly:
|
||||
|
||||
/etc/init.d/scst restart
|
||||
|
||||
|
||||
+1
-1
@@ -10,7 +10,7 @@ follows with clang:
|
||||
cd $HOME/software/linux-kernel
|
||||
make CC=clang modules_prepare
|
||||
|
||||
5. Build SCST using any of the supported build methods. An example:
|
||||
4. Build SCST using any of the supported build methods. An example:
|
||||
|
||||
export KDIR=$HOME/software/linux-kernel
|
||||
export PASS_CC_TO_MAKE=1
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
Cross-compilation is the process of compiling code for one architecture (often
|
||||
called the target) on a different system, usually called the host.
|
||||
Cross-compilation of SCST is possible as follows:
|
||||
Cross-compilation of the SCST kernel modules is possible as follows:
|
||||
1. Download the Linux kernel source code and also the SCST source code.
|
||||
2. Install the appropriate cross-compiler, e.g. as follows:
|
||||
|
||||
@@ -17,8 +17,16 @@ Cross-compilation of SCST is possible as follows:
|
||||
cd $HOME/software/linux-kernel
|
||||
make
|
||||
|
||||
5. Cross-compile SCST using any of the supported build methods. An example:
|
||||
5. Cross-compile the SCST core modules with the same toolchain. For example:
|
||||
|
||||
export KDIR=$HOME/software/linux-kernel
|
||||
export PASS_CC_TO_MAKE=1
|
||||
export CC=${CROSS_COMPILE}gcc
|
||||
cd scst.git
|
||||
make rpm
|
||||
make scst
|
||||
|
||||
`ARCH` and `CROSS_COMPILE` configure the kernel build. They do not configure
|
||||
the user-space build: programs under usr/ use `CC` directly and scstadmin uses
|
||||
Perl MakeMaker. Cross-compiling the entire repository or building packages
|
||||
therefore also requires a target-aware user-space toolchain and packaging
|
||||
environment. `make rpm` by itself is not a generic cross-compilation method.
|
||||
|
||||
@@ -14,8 +14,8 @@ project includes:
|
||||
1. The SCST core in the scst/ subdirectory.
|
||||
2. A tool for loading, saving and modifying the SCST configuration in
|
||||
directory scstadmin/.
|
||||
3. Several SCSI target drivers in the directories iscsi-scst/, qla2x00t/,
|
||||
srpt/, scst_local/ and fcst/.
|
||||
3. Several SCSI target drivers in the directories iscsi-scst/,
|
||||
qla2x00t-32gbit/, qla2x00t/, srpt/, scst_local/ and fcst/.
|
||||
4. User space programs in the usr/ subdirectory, e.g. fileio_tgt.
|
||||
5. Various documentation in the doc/ subdirectory.
|
||||
|
||||
@@ -26,8 +26,8 @@ file.
|
||||
|
||||
Two QLogic target drivers are included in the SCST project.
|
||||
|
||||
The default driver is located in qla2x00t-32gbit directory and it supports up
|
||||
to 32 Gb/s FC. It is the newer one.
|
||||
The default driver is located in the qla2x00t-32gbit directory. It is the
|
||||
newer one.
|
||||
|
||||
May anyone wish to switch back to the older driver that only supported up to
|
||||
16 Gb/s adapters, it is located in qla2x00t directory. To make use of the
|
||||
|
||||
+30
-31
@@ -8,50 +8,49 @@ The purpose of kernel module signatures is to only allow those kernel modules
|
||||
to be loaded that have been signed with an approved key. A signed kernel
|
||||
module is a kernel module with a digital signature embedded into the module
|
||||
stating the owner of the signature created that kernel module. This is a
|
||||
security mechanism that was introduced in kernel v3.7. If this mechanism is
|
||||
enabled the signature of a kernel module is verified against the public keys
|
||||
embedded in the kernel and also against the UEFI public keys. This mechanism
|
||||
restricts kernel module loading such that only kernel modules signed with
|
||||
certain keys can be loaded.
|
||||
security mechanism that was introduced in kernel v3.7. Module signatures are
|
||||
verified against trusted public keys available to the running kernel. Whether
|
||||
unsigned modules are rejected depends on the kernel configuration, command
|
||||
line and platform security policy.
|
||||
|
||||
Module Signing and SCST
|
||||
-----------------------
|
||||
There are two options when using SCST in combination with a kernel that has
|
||||
signed kernel modules:
|
||||
On systems that use shim and the Machine Owner Key (MOK) mechanism, the
|
||||
preferred approach is to keep signature verification enabled and enroll the
|
||||
public certificate generated during the SCST build.
|
||||
|
||||
* Disable the signature verification mechanism by adding module.sig_enforce=0
|
||||
at the end of GRUB_CMDLINE_LINUX in /etc/default/grub, by updating grub.cfg
|
||||
and by rebooting. grub.cfg can be updated by running e.g. the following
|
||||
command:
|
||||
|
||||
update-bootloader || update-grub || grub2-mkconfig -o /boot/grub2/grub.cfg
|
||||
|
||||
* Enable the signature verification mechanism and load the public key that
|
||||
was generated during the SCST build process into the UEFI keyring.
|
||||
Permissive module loading is only available if the kernel and platform policy
|
||||
allow it. In particular, `module.sig_enforce=0` does not override a kernel
|
||||
built with `CONFIG_MODULE_SIG_FORCE`. Follow the distribution-specific Secure
|
||||
Boot and module-signing documentation before changing the boot configuration.
|
||||
|
||||
Signing SCST Kernel Modules
|
||||
---------------------------
|
||||
Build and install SCST as usual. During the build process a public/private
|
||||
key pair will be generated in the scst/src/certs directory:
|
||||
If `CONFIG_MODULE_SIG=y` is set in the target kernel configuration, the SCST
|
||||
build uses openssl to generate a public/private key pair in the scst/src/certs
|
||||
directory:
|
||||
|
||||
ls -l scst/src/certs/scst_module_key*
|
||||
-rw-------. 1 bart users 1325 Sep 28 16:42 scst/src/certs/scst_module_key.der
|
||||
-rw-------. 1 bart users 3272 Sep 28 16:42 scst/src/certs/scst_module_key.priv
|
||||
|
||||
Start the process of importing the public key into the UEFI key repository
|
||||
as follows:
|
||||
The `.der` file is the public certificate and the `.priv` file is the private
|
||||
key. Keep the private key secret and never pass it to mokutil. During
|
||||
installation, `scripts/sign-modules` signs modules with the target kernel's
|
||||
`scripts/sign-file`. If `sign-file` is unavailable, the script reports that
|
||||
the modules are not being signed and continues; check the installation output
|
||||
before relying on signature enforcement.
|
||||
|
||||
On systems that use shim and the Machine Owner Key (MOK) mechanism, start
|
||||
importing the public certificate as follows:
|
||||
|
||||
mokutil --import scst/src/certs/scst_module_key.der
|
||||
|
||||
The mokutil software will ask which password should be used for this key
|
||||
during the import process. Since this password will be short-lived, any
|
||||
simple password works. Next, verify with mokutil --list-new whether the
|
||||
import process has been started. If this is the case, reboot. The bootloader
|
||||
will start the EFI MOK manager. Use the menus on the screen to activate the
|
||||
SCST kernel module key. After booting has finished, verify whether loading
|
||||
and unloading of the main SCST kernel module works:
|
||||
|
||||
modprobe scst && modprobe -r scst
|
||||
The mokutil software asks for a temporary enrollment password. Next, verify
|
||||
with `mokutil --list-new` that the import is pending and reboot. The bootloader
|
||||
starts MokManager, where the certificate can be enrolled. Before loading SCST
|
||||
modules, use `modinfo -F signer <module.ko>` to inspect the embedded signer.
|
||||
This confirms that signer metadata is present; it does not prove that the
|
||||
running kernel trusts the certificate. Only test module loading on a host
|
||||
where changing SCST module and service state is safe.
|
||||
|
||||
See Also
|
||||
--------
|
||||
|
||||
Vendored
+1
-1
@@ -1,7 +1,7 @@
|
||||
SCST source code
|
||||
----------------
|
||||
|
||||
SCST source code is available at https://sourceforge.net/p/scst/svn/HEAD/tree/.
|
||||
SCST source code is available at https://github.com/SCST-project/scst.
|
||||
|
||||
|
||||
-- Bart Van Assche <bvanassche@acm.org> Fri, 12 Jan 2018 20:14:02 -0800
|
||||
|
||||
+2
-1
@@ -27,7 +27,8 @@ and supply the following two config files:
|
||||
local current directory ($PWD).
|
||||
ABT_JOBS: allows parallel builds -- it's passed as the argument to "make
|
||||
-j" when building SCST and the tests. The default is 1.
|
||||
ABT_KERNELS: kernel version numbers to test SCST against.
|
||||
ABT_KERNELS: kernel version numbers to test SCST against. The maintained
|
||||
project list is in conf/nightly.conf.
|
||||
ABT_TMPDIR: absolute path in which temporary files will be stored.
|
||||
|
||||
- conf/<tag>.sendmail: this should be a script that sends an email to the
|
||||
|
||||
Reference in New Issue
Block a user