ksc(1)

📦
version 1.12 · 2 versions
, in centos-stream 10, centos-stream 9

💅 ksc(1) — like, the user-commands manual, but make it make sense

okay bestie, welcome to ksc(1) from the User Commands section — this is the page that tells you how to report symbols used by kernel modules. yes. kernel modules. we're doing this. 🧚✨

✨ 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]

Like, four whole shapes this command can take. Pick your fighter. 💅

🦋 DESCRIPTION 🦋

ksc produces and submits reports of symbols used by kernel object *FILE*s (you point at those with -k). The resulting report is always saved to ~/ksc-result.txt — that part is not optional, it just happens. 🫶

  • Wanna know more about how reports get generated? Go look at -k.
  • Wanna know more about submitting a report for stabilization? That's -s, bestie.
  • Wanna know more about submitting a report for notification? That's -S.

🌈 ENVIRONMENT 🌈

okay so this is important — it is highly recommended that you run ksc on the latest minor version of RHEL. and like, to actually make sure of that, before you even touch ksc you should update the kernel-devel-provided Module.symvers. You can do that, for example, by issuing:

yum update kernel-devel

You can also use the -y (--symvers) option to explicitly state where the Module.symvers file lives, so that you're certain accurate and up-to-date kABI data is being handed to ksc. no cap, this saves you so much pain later. 😭

✨ OPTIONS ✨

You may freely mix different option styles. (iconic of it, honestly.)

  • -h, --help — Show help message and exit. (the original page garbles this line into "exitfor notification" — that's a little typo gremlin living in the manpage, the meaning is just "show help and exit" 💀)
  • -c CONFIG, --config=CONFIG — Read config options from the CONFIG file. If you don't supply one, ksc will use ~/ksc.conf. If that isn't found, /etc/ksc.conf gets used instead. 🎀
  • -j KSC_RESULT, --justification-from=KSC_RESULT — Read symbol justifications from the KSC_RESULT file and use them in the new report. Important, bestie: placeholder justifications and reference justifications are ignored by this option and get re-generated every single time.

This option may be specified multiple times. The 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 — like, if you justify usage of S for A.ko, B.ko references the justification in A.ko, and then you run ksc without A.ko, the justification is not carried over and you will be asked to specify it. 🙈

  • -k FILE, --ko=FILE — Collect used symbols in kernel object FILE. You can supply multiple -k arguments, and in that case the different *FILE*s get placed in distinct sections of the ~/ksc-result.txt file. 🦋

All kernel object *FILE*s must be built against the same architecture.

If you supply multiple *FILE*s, the ksc report won't include symbols exported by any one of the *FILE*s. This lets you bulk-collect symbols of a functionally dependent set of kernel modules without having to filter out symbols coming from other modules. slay.

  • -K FILE, --ko-dependency=FILE — Omit any symbols exported by FILE from the report. Use this one 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 — The 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 — The specified PREVIOUS file is marked for submission to Red Hat Bugzilla. To actually submit, you need to use -s or -S. 👑
  • -r RELEASE, --release=RELEASE — The RHEL RELEASE used for symbol comparison with stablelists, e.g. '6.5'.
  • -y SYMVERS, --symvers=SYMVERS — Path to the Module.symvers SYMVERS file used to check symbol presence in the kernel. If you don't specify it, the current kernel version is used to determine the path, and Module.symvers of the currently running kernel gets used.

You get notified whenever a 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). The credentials used in submission need to be set in a config file (peep the FILES section below). If an API key is not set, ksc will prompt you for the Bugzilla password.

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

If used with -k, the report gets generated, opened in an editor so you can make changes, saved in ~/ksc-result.txt, and submitted. You may interrupt submission by pressing Ctrl+C. 😌

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

  • -v, --version — Prints ksc version. ⭐

🎀 FILES 🎀

  • ~/ksc-result.txt — Report produced by ksc. 🌸
  • ~/ksc.conf (/etc/ksc.conf) — Local (global) ksc config file. The global config file is used only when the local config file does not exist. The 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 with your own credentials. 🫶

Mandatory fields for any submission method: user, partner, partnergroup.

Mandatory fields for the Bugzilla submission method: server, api_key.

Mandatory fields for the mailing list submission method: to, smtp.

By default, the 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, and the user and to fields must be valid e-mail addresses.

At least one submission method must be configured before you're 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 the example above). easy. 💜

🔥 EXAMPLES 🔥

  • ksc -k a.ko — Process a.ko using system-provided stablelist and Module.symvers files. Reports symbols used by a.ko that are not in the stablelist, requesting justification for their use. ✨
  • ksc -k a.ko -y /tmp/Module.symvers — Process a.ko using system-provided stablelist and user-provided Module.symvers (/tmp/Module.symvers) files. Reports symbols used by a.ko that are not in the stablelist, requesting justification for their use.
  • ksc -k a.ko -k b.ko — Process a.ko and b.ko using system-provided stablelist and Module.symvers files. Reports symbols used by both a.ko and b.ko that are not in the stablelist, requesting justification for their use. Only one justification per symbol is required. Any mention of an already justified symbol comes with automatically generated references.
  • ksc -k a.ko -k b.ko -K c.ko -K d.ko — Process a.ko and b.ko using system-provided stablelist and Module.symvers files. Reports symbols used by both a.ko and b.ko that are not in the 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 comes with automatically generated references. 👑
  • ksc -k a.ko -k b.ko -j previous-report.txt — Process a.ko and b.ko using system-provided stablelist and Module.symvers files. Reports symbols used by both a.ko and b.ko that are not in the stablelist, requesting justification for their use. Only one justification per symbol is required. Any mention of an already justified symbol comes with 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. go off. 🚀
fr fr, don't forget: ~/ksc-result.txt is always where the report lands, and you need at least one submission method configured before -s/-S will do anything for you. 🫶

that's the whole page, bestie 💅 this was ksc — Version 1.12, dated Jan 2023, and yes the manual name at the top is ksc in section 1 (User Commands). mwah 🎀✨🦋

📦 where this page comes from