NAME¶

ksc - report symbols used by kernel modules

SYNOPSIS¶

ksc -k FILE ... [OPTIONS]

ksc -k FILE ... -s [OPTIONS]

ksc -s -p KSC_RESULT [OPTIONS]

ksc -S -p KSC_RESULT [OPTIONS]

DESCRIPTION¶

ksc produces and submits reports of symbols used by kernel object FILEs (specified by -k). Resulting report is always saved to ~/ksc-result.txt.

For more on report generation, see -k.

For more on report submission for stabilization, see -s.

For more on report submission for notification, see -S.

ENVIRONMENT¶

It is highly recommended that ksc is used on the latest minor version of RHEL, and to make sure, prior to ksc usage, to update kernel-devel-provided Module.symvers. This can be accomplished, for example, by issuing:

yum update kernel-devel

It is also possible to use the -y (--symvers) option to explicitly state the location of Module.symvers file to make sure that accurate and up-to-date kABI data be provided to ksc.

OPTIONS¶

You may freely mix different option styles.

-h, --help

Show help message and exitfor notification.

-c CONFIG, --config=CONFIG

Read config options from CONFIG file. If not supplied, ksc will use ~/ksc.conf. If not found, /etc/ksc.conf will be used instead.

-j KSC_RESULT, --justification-from=KSC_RESULT

Read symbol justifications from KSC_RESULT file and use them in the new report. It is important to note that placeholder justifications and reference justifications are ignored by this option and re-generated every time.

This option may be specified multiple times. KSC_RESULT file order is determined by the order of arguments passed to ksc. If there are two conflicting non-placeholder/non-reference justifications for a kernel module A.ko symbol S in multiple report files at the same time, it will be carried over from the last one specified on the command line.

Symbol justifications can be carried over within the same kernel module only. Justifications do not propagate through references (i.e., if you justify usage of S for A.ko, B.ko references justification in A.ko, and you run ksc without A.ko, justification is not carried over and you will be asked to specify).

-k FILE, --ko=FILE

Collect used symbols in kernel object FILE.
Multiple -k arguments may be supplied, in which case different FILEs are placed in distinct sections of the ~/ksc-result.txt file.

All kernel object FILEs must be build against the same architecture.

If multiple FILEs are supplied, ksc report won't include symbols exported by any one of the FILEs. This allows for bulk collection of symbols of a functionally dependent set of kernel modules without having to filter symbols coming from other modules.

-K FILE, --ko-dependency=FILE

Omit any symbols exported by FILE from the report. Use this option if other modules (which are part of the report) depend on symbols exported by FILE, but FILE itself is not to be reported at this time.

-n RELEASE, --name=RELEASE

RHEL RELEASE against which the bug is to be filed, e.g '6.5'.

-C, --centos-stream

Target Centos Stream rather than a specific minor release.

-p PREVIOUS, --previous=PREVIOUS

Specified PREVIOUS file is marked for submission to Red Hat Bugzilla.
To submit, you need to use -s or -S.

-r RELEASE, --release=RELEASE

RHEL RELEASE used for symbol comparison with stablelists, e.g. '6.5'.

-y SYMVERS, --symvers=SYMVERS

Path to Module.symvers SYMVERS file used to check symbol presence in the the kernel. If not specified, current kernel version is used to determine the path and Module.symvers of the currently running kernel is used.

You are notified whenever symbol is not present in the Module.symvers file.

-s, --submit, -S, --subscribe

Submit the report to the Red Hat Bugzilla (https://bugzilla.redhat.com). Credentials used in submission need to be set a config file (see FILES section below). If API key is not set, ksc will prompt for Bugzilla password.

This option needs to be supplemented with -k or -p.

If used with -k, report gets generated, opened in an editor for you to make changes, saved in ~/ksc-result.txt, and submitted. You may interrupt submission by pressing ^C.

To submit for stabilization, please use -s. Using -s implies -S. To submit for notification only, please use -S.

-v, --version

Prints ksc version.

FILES¶

~/ksc-result.txt

Report produced by ksc.

~/ksc.conf (/etc/ksc.conf)

Local (global) ksc config file. Global config file is used only when local config file does not exist. Syntax is as follows:

[global]
user=user@example.com
partner=none
partnergroup=none
[bugzilla]
enable=1
server=https://bugzilla.redhat.com/xmlrpc.cgi
api_key=API_KEY
[mailing_list]
enable=1
smtp=smtp.example.com
to=kabi-requests@redhat.com

Please replace the values above by your credentials.

Mandatory fields for any submission method: user, partner, partnergroup.
Mandatory fields for Bugzilla submission method: server, api_key.
Mandatory fields for mailing list submission method: to, smtp.

By default, Bugzilla (mailing list) submission method is auto-enabled (auto-disabled) and must be opted out (in).

Note that server must be a valid XML RPC Bugzilla link, user and to fields must be valid e-mail addresses.

At least one submission method must be configured to be able to submit ksc reports.

In case you don't have or don't wish to file the bug under a specific partner/partnergroup, please set these fields to none (see example above).

EXAMPLES¶

ksc -k a.ko

Process a.ko file using system-provided stablelist and Module.symvers files. Reports symbols used by a.ko that are not in stablelist, requesting justification for their use.

ksc -k a.ko -y /tmp/Module.symvers

Process a.ko file using system-provided stablelist and user-provided Module.symvers (/tmp/Module.symvers) files. Reports symbols used by a.ko that are not in stablelist, requesting justification for their use.

ksc -k a.ko -k b.ko

Process a.ko and b.ko files using system-provided stablelist and Module.symvers files. Reports symbols used by both a.ko and b.ko that are not in stablelist, requesting justification for their use. Only one justification per symbol is required. Any mention of an already justified symbol come with an automatically generated references.

ksc -k a.ko -k b.ko -K c.ko -K d.ko

Process a.ko and b.ko files using system-provided stablelist and Module.symvers files. Reports symbols used by both a.ko and b.ko that are not in stablelist and not exported by either c.ko or d.ko, requesting justification for their use. Only one justification per symbol is required. Any mention of an already justified symbol come with an automatically generated references.

ksc -k a.ko -k b.ko -j previous-report.txt

Process a.ko and b.ko files using system-provided stablelist and Module.symvers files. Reports symbols used by both a.ko and b.ko that are not in stablelist, requesting justification for their use. Only one justification per symbol is required. Any mention of an already justified symbol come with an automatically generated references. Justifications already present in previous-report.txt are carried over to the newly generated one.

ksc -s -p report-to-submit.txt

Submit a report to bugzilla.