generated from oracle/template-repo
-
Notifications
You must be signed in to change notification settings - Fork 18
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add corelens manual to sphinx documentation
Signed-off-by: Stephen Brennan <[email protected]>
- Loading branch information
Showing
5 changed files
with
111 additions
and
2 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| CORELENS(1) | ||
| =========== | ||
|
|
||
| .. raw:: html | ||
| :file: ../man/corelens.1.html |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -17,6 +17,7 @@ Contents | |
| code-quality.rst | ||
| testing.rst | ||
| api.rst | ||
| corelens.rst | ||
|
|
||
| .. toctree:: | ||
| :maxdepth: 1 | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,100 @@ | ||
| <h1>NAME</h1> | ||
| <p>corelens - extract diagnostic info from the running kernel or core dump</p> | ||
| <h1>SYNOPSIS</h1> | ||
| <p>Generate a corelens report:</p> | ||
| <blockquote> | ||
| <p><strong>corelens</strong> [-o OUT] <em>VMCORE</em> [-a | -A]</p> | ||
| </blockquote> | ||
| <p>Run specified modules:</p> | ||
| <blockquote> | ||
| <p><strong>corelens</strong> [-o OUT] <em>VMCORE</em> [-M MODULE [options] [-M MODULE ...]]</p> | ||
| </blockquote> | ||
| <p>Get help:</p> | ||
| <blockquote> | ||
| <p><strong>corelens -h</strong></p> | ||
| <p><strong>corelens -L</strong></p> | ||
| <p><strong>corelens -M</strong> <em>MODULE</em> <strong>-h</strong></p> | ||
| </blockquote> | ||
| <h1>DESCRIPTION</h1> | ||
| <p>Corelens is a tool which can extract diagnostic information from the Linux kernel image specified by <em>VMCORE</em>. To extract diagnostic information from the running kernel, "/proc/kcore" should be provided. Its functionality is grouped into <em>modules</em>, each one producing diagnostic information about a specific kernel subsystem.</p> | ||
| <p>Corelens may be run in two modes: generating a report, or running specified modules. When generating a report, corelens will run a collection of default modules, with default arguments. Alternatively, the user may run a list of specified modules. Each module must be specified on the command line with <strong>-M</strong> <em>MODULE</em>, and any subsequent argument (up to the next <strong>-M</strong>) is handled by <em>MODULE</em>.</p> | ||
| <p>By default, corelens produces output on stdout. However, with <strong>-o</strong>, output may be stored in a directory, where each module's output is contained in a separate file. This mode is useful when preparing a report to send to Oracle Linux Support.</p> | ||
| <h1>OPTIONS</h1> | ||
| <p><em>VMCORE</em></p> | ||
| <blockquote> | ||
| <p>The kernel image to run against. Specify "/proc/kcore" for the running kernel. This argument is required, unless using <strong>-h</strong> to get help, or <strong>-L</strong> to list corelens modules.</p> | ||
| </blockquote> | ||
| <p><strong>--output-directory</strong> <em>OUT</em>, <strong>-o</strong> <em>OUT</em></p> | ||
| <blockquote> | ||
| <p>Write each module's output to a correspondingly named file within the <em>OUT</em> directory. The directory <em>OUT</em> will be created if it does not exist.</p> | ||
| </blockquote> | ||
| <p><strong>Mode selection:</strong></p> | ||
| <blockquote> | ||
| <p>The following options are mutually exclusive.</p> | ||
| <p><strong>-a</strong></p> | ||
| <blockquote> | ||
| <p>When specified, this runs the default corelens report, which should be sufficient for most cases. All standard modules are selected to be run with their default arguments. Modules which are not applicable (e.g. because the subsystem is not loaded or active) are skipped.</p> | ||
| </blockquote> | ||
| <p><strong>-A</strong></p> | ||
| <blockquote> | ||
| <p>When specified, this runs the detailed corelens report. This selects all modules, including those which are not run by <strong>-a</strong>. These detailed modules may produce larger amounts of output, or require a longer runtime. The standard report provided by <strong>-a</strong> should be preferred.</p> | ||
| </blockquote> | ||
| <p><strong>-M</strong> <em>MODULE</em> [...]</p> | ||
| <blockquote> | ||
| <p>Specify a corelens module to run, providing optional arguments to the module itself. All command-line arguments following this one are provided to the module, up to the next <strong>-M</strong> option.</p> | ||
| <p>As a special case, when using <strong>-h</strong> to get help on a module's output, <em>VMCORE</em> is not required.</p> | ||
| </blockquote> | ||
| <p><strong>-L</strong></p> | ||
| <blockquote> | ||
| <p>List all modules and exit. <em>VMCORE</em> is not required.</p> | ||
| </blockquote> | ||
| <p>As a special case, when corelens is run without any of the above mode selection arguments, it runs the "sys" corelens module (as if the arguments provided were: <strong>-M sys</strong>).</p> | ||
| </blockquote> | ||
| <p><strong>Debuginfo Selection:</strong></p> | ||
| <blockquote> | ||
| <p>The following options disable the standard behavior for searching for debuginfo, and manually provide it. They are not required. They are mutually exclusive to each other.</p> | ||
| <p><strong>--ctf</strong> <em>CTF</em></p> | ||
| <blockquote> | ||
| <p>Corelens will manually load the CTF file <em>CTF</em>.</p> | ||
| </blockquote> | ||
| <p><strong>--debuginfo</strong> <em>DEBUGINFO</em>, <strong>-d</strong> <em>DEBUGINFO</em></p> | ||
| <blockquote> | ||
| <p>Corelens will search for DWARF debuginfo within the directory <em>DEBUGINFO</em>, which should contain a "vmlinux" file as well as ".ko.debug" files for each relevant kernel module.</p> | ||
| </blockquote> | ||
| </blockquote> | ||
| <h1>DEBUGINFO</h1> | ||
| <p>In order to produce diagnostic information, corelens requires some form of debugging information for <em>VMCORE</em>. There are two possibilities:</p> | ||
| <p><strong>DWARF</strong></p> | ||
| <blockquote> | ||
| <p>DWARF information is the most detailed option, but it requires that the <strong>debuginfo</strong> package corresponding to <em>VMCORE</em> (or the running kernel) is installed. When DWARF information is available, corelens can provide more detailed stack traces, and some modules only work when DWARF is available.</p> | ||
| </blockquote> | ||
| <p><strong>CTF</strong></p> | ||
| <blockquote> | ||
| <p>CTF (Compact Type Format) is a lightweight type format. For Oracle UEK kernels (<strong>kernel-uek</strong>), CTF is always available.</p> | ||
| </blockquote> | ||
| <p>Corelens automatically searches for debuginfo at startup. It prefers DWARF when available, and uses CTF as a second choice. The search may be overridden by using the options <strong>--ctf</strong> or <strong>--debuginfo</strong>.</p> | ||
| <h1>MODULES</h1> | ||
| <p>Corelens' functionality is divided into modules. Modules have a name and can accept command-line arguments. They are broken into three categories based on when they are run:</p> | ||
| <blockquote> | ||
| <p>1. Standard modules run whenever <strong>-a</strong> is specified</p> | ||
| </blockquote> | ||
| <blockquote> | ||
| <p>2. Detailed modules are run whenever <strong>-A</strong> is specified</p> | ||
| </blockquote> | ||
| <blockquote> | ||
| <p>3. Manual modules are only run when explicitly requested</p> | ||
| </blockquote> | ||
| <p>Some corelens modules will only run if a relevant kernel module is loaded. Others require DWARF debuginfo. Some modules may only run against core dumps (not /proc/kcore). Corelens will provide appropriate warnings or errors at runtime if these situations are encountered.</p> | ||
| <p>The full list of modules can be viewed by running <strong>corelens -L</strong>. To view more information about a specific module, including its command-line arguments, you can run <strong>corelens -M</strong> <em>MODULE</em> <strong>-h</strong>.</p> | ||
| <h1>EXAMPLES</h1> | ||
| <p>Run the "sys" module against the live kernel:</p> | ||
| <pre><code>corelens /proc/kcore -M sys</code></pre> | ||
| <p>Run a default report against a live kernel, and store the report in a directory. Then create an archive for later transmission to Oracle Linux Support:</p> | ||
| <pre><code>corelens /proc/kcore -a -o ./report | ||
| tar -cvzf report.tar.gz ./report</code></pre> | ||
| <p>List all modules:</p> | ||
| <pre><code>corelens -L</code></pre> | ||
| <p>Get help on the dentrycache module:</p> | ||
| <pre><code>corelens -M dentrycache -h</code></pre> | ||
| <h1>REPORTING BUGS</h1> | ||
| <p>Please contact Oracle Linux Support to report any bugs for corelens.</p> |