public-mirrors/linux
1
0
Fork 0
mirror of git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git synced 2025-08-05 16:54:27 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
linux/Documentation/admin-guide/index.rst

199 lines
3.5 KiB
ReStructuredText
Raw Permalink Normal View History

docs: Correct formatting of title in admin-guide/index.rst Adjust the title of "The Linux kernel user's and administrator's guide" to adhere to the expected reStructuredText (rst) formatting, using double equal signs for the main header. Signed-off-by: Carlos Bilbao <carlos.bilbao@amd.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20240109155643.3489369-2-carlos.bilbao@amd.com
2024-01-09 09:56:42 -06:00
=================================================
docs: Clean up and organize the admin guide a bit The admin guide is a good start, but it's time to turn it into something better than an unordered blob of files. This is a first step in that direction. The TOC has been split up and annotated, the guides have been reordered, and minor tweaks have been applied to a few of them. One consequence of splitting up the TOC is that we don't really want to use :numbered: anymore, since the count resets every time and there doesn't seem to be a way to change that. Eventually we probably want to group the documents into sub-books, at which point we can go back to a single TOC, but it's probably early to do that. Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-10-26 16:14:52 -06:00
The Linux kernel user's and administrator's guide
=================================================
docs-rst: create an user's manual book Place README, REPORTING-BUGS, SecurityBugs and kernel-parameters on an user's manual book. As we'll be numbering the user's manual, remove the manual numbering from SecurityBugs. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-09-21 09:51:11 -03:00
docs: Clean up and organize the admin guide a bit The admin guide is a good start, but it's time to turn it into something better than an unordered blob of files. This is a first step in that direction. The TOC has been split up and annotated, the guides have been reordered, and minor tweaks have been applied to a few of them. One consequence of splitting up the TOC is that we don't really want to use :numbered: anymore, since the count resets every time and there doesn't seem to be a way to change that. Eventually we probably want to group the documents into sub-books, at which point we can go back to a single TOC, but it's probably early to do that. Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-10-26 16:14:52 -06:00
The following is a collection of user-oriented documents that have been
added to the kernel over time. There is, as yet, little overall order or
organization here — this material was not written to be a single, coherent
document! With luck things will improve quickly over time.
docs: admin-guide: add some subsection headings As part of the goal of bringing some order to this file, add subsection headings to help readers find what they are looking for. Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20241213182057.343527-3-corbet@lwn.net
2024-12-13 11:20:53 -07:00
General guides to kernel administration
---------------------------------------
docs: Clean up and organize the admin guide a bit The admin guide is a good start, but it's time to turn it into something better than an unordered blob of files. This is a first step in that direction. The TOC has been split up and annotated, the guides have been reordered, and minor tweaks have been applied to a few of them. One consequence of splitting up the TOC is that we don't really want to use :numbered: anymore, since the count resets every time and there doesn't seem to be a way to change that. Eventually we probably want to group the documents into sub-books, at which point we can go back to a single TOC, but it's probably early to do that. Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-10-26 16:14:52 -06:00
This initial section contains overall information, including the README
file describing the kernel as a whole, documentation on kernel parameters,
admin-guide: move tainted kernels info to a separate file The tainted kernels info is not directly related to the oops tracing. So, let's move it to a separate file. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-07 17:03:18 -02:00
etc.
docs-rst: create an user's manual book Place README, REPORTING-BUGS, SecurityBugs and kernel-parameters on an user's manual book. As we'll be numbering the user's manual, remove the manual numbering from SecurityBugs. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-09-21 09:51:11 -03:00
.. toctree::
docs: Clean up and organize the admin guide a bit The admin guide is a good start, but it's time to turn it into something better than an unordered blob of files. This is a first step in that direction. The TOC has been split up and annotated, the guides have been reordered, and minor tweaks have been applied to a few of them. One consequence of splitting up the TOC is that we don't really want to use :numbered: anymore, since the count resets every time and there doesn't seem to be a way to change that. Eventually we probably want to group the documents into sub-books, at which point we can go back to a single TOC, but it's probably early to do that. Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-10-26 16:14:52 -06:00
:maxdepth: 1
docs-rst: create an user's manual book Place README, REPORTING-BUGS, SecurityBugs and kernel-parameters on an user's manual book. As we'll be numbering the user's manual, remove the manual numbering from SecurityBugs. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-09-21 09:51:11 -03:00
README
docs: Clean up and organize the admin guide a bit The admin guide is a good start, but it's time to turn it into something better than an unordered blob of files. This is a first step in that direction. The TOC has been split up and annotated, the guides have been reordered, and minor tweaks have been applied to a few of them. One consequence of splitting up the TOC is that we don't really want to use :numbered: anymore, since the count resets every time and there doesn't seem to be a way to change that. Eventually we probably want to group the documents into sub-books, at which point we can go back to a single TOC, but it's probably early to do that. Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-10-26 16:14:52 -06:00
devices
docs: admin-guide: add a features list Add a feature list matrix at the admin-guide. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/f6c1e366fbc7ce1c9c94c7dc6c7852c6377cc0be.1606748711.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-11-30 16:36:34 +01:00
features
docs: add ABI documentation to the admin-guide book As we don't want a generic Sphinx extension to execute commands, change the one proposed to Markus to call the abi_book.pl script. Use a script to parse the Documentation/ABI directory and output it at the admin-guide. Acked-by: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/5651482b06500e69a1acdf92152f90a203e6521d.1604042072.git.mchehab+huawei@kernel.org Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
2020-10-30 08:40:36 +01:00
docs: admin-guide: bring some order to the "everything else" section The bulk of the admin guide had become a big pile of stuff haphazardly tossed together, mostly in the catch-all "everything else" section. Split that section into a few broad categories and sort the documents into them as appropriate. No documents have been added or removed, they are just reordered. Note that many of these documents are severely obsolete and should be considered for removal. Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20241213182057.343527-4-corbet@lwn.net
2024-12-13 11:20:54 -07:00
A big part of the kernel's administrative interface is the /proc and sysfs
virtual filesystems; these documents describe how to interact with tem
.. toctree::
:maxdepth: 1
sysfs-rules
sysctl/index
cputopology
abi
Security-related documentation:
Documentation: Add section about CPU vulnerabilities Add documentation for the L1TF vulnerability and the mitigation mechanisms: - Explain the problem and risks - Document the mitigation mechanisms - Document the command line controls - Document the sysfs files Signed-off-by: Thomas Gleixner <tglx@linutronix.de> Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Reviewed-by: Josh Poimboeuf <jpoimboe@redhat.com> Acked-by: Linus Torvalds <torvalds@linux-foundation.org> Link: https://lkml.kernel.org/r/20180713142323.287429944@linutronix.de
2018-07-13 16:23:26 +02:00
.. toctree::
:maxdepth: 1
Documentation: Move L1TF to separate directory Move L!TF to a separate directory so the MDS stuff can be added at the side. Otherwise the all hardware vulnerabilites have their own top level entry. Should have done that right away. Signed-off-by: Thomas Gleixner <tglx@linutronix.de> Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Reviewed-by: Jon Masters <jcm@redhat.com>
2019-02-19 11:10:49 +01:00
hw-vuln/index
docs: admin-guide: bring some order to the "everything else" section The bulk of the admin guide had become a big pile of stuff haphazardly tossed together, mostly in the catch-all "everything else" section. Split that section into a few broad categories and sort the documents into them as appropriate. No documents have been added or removed, they are just reordered. Note that many of these documents are severely obsolete and should be considered for removal. Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20241213182057.343527-4-corbet@lwn.net
2024-12-13 11:20:54 -07:00
LSM/index
perf-security
Booting the kernel
------------------
.. toctree::
:maxdepth: 1
bootconfig
kernel-parameters
efi-stub
initrd
Documentation: Add section about CPU vulnerabilities Add documentation for the L1TF vulnerability and the mitigation mechanisms: - Explain the problem and risks - Document the mitigation mechanisms - Document the command line controls - Document the sysfs files Signed-off-by: Thomas Gleixner <tglx@linutronix.de> Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Reviewed-by: Josh Poimboeuf <jpoimboe@redhat.com> Acked-by: Linus Torvalds <torvalds@linux-foundation.org> Link: https://lkml.kernel.org/r/20180713142323.287429944@linutronix.de
2018-07-13 16:23:26 +02:00
docs: admin-guide: add some subsection headings As part of the goal of bringing some order to this file, add subsection headings to help readers find what they are looking for. Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20241213182057.343527-3-corbet@lwn.net
2024-12-13 11:20:53 -07:00
Tracking down and identifying problems
--------------------------------------
docs: Clean up and organize the admin guide a bit The admin guide is a good start, but it's time to turn it into something better than an unordered blob of files. This is a first step in that direction. The TOC has been split up and annotated, the guides have been reordered, and minor tweaks have been applied to a few of them. One consequence of splitting up the TOC is that we don't really want to use :numbered: anymore, since the count resets every time and there doesn't seem to be a way to change that. Eventually we probably want to group the documents into sub-books, at which point we can go back to a single TOC, but it's probably early to do that. Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-10-26 16:14:52 -06:00
Here is a set of documents aimed at users who are trying to track down
problems and bugs in particular.
.. toctree::
:maxdepth: 1
admin-guide: move tainted kernels info to a separate file The tainted kernels info is not directly related to the oops tracing. So, let's move it to a separate file. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-07 17:03:18 -02:00
docs: Add a new text describing how to report bugs Add a mostly finished document describing how to report issues with the Linux kernel to its developers. It is designed to be a lot more straight forward and easier to follow than the current text about this (Documentation/admin-guide/reporting-bugs.rst); at the same time the new text should be more helpful for people unfamiliar with the topic, as it provides a lot more details, too. The main work on the text is done, but some polishing is still needed. The text also needs to be reviewed by more people and a few issues still might need some discussion. To make these tasks easier, it was decided ([1]) to add this document to the kernel sources in parallel to the existing text; the latter will be removed once this text is considered good enough(tm). This document is quite long and provides a lot of details, but was carefully crafted to make sure it's can also serve people that are in a hurry. That's mainly achieved by having a TDLR and a step-by-step guide, which should be good enough for quite a lot of people. Everybody that wants or need more explanations can find them in a reference section, which describes all the needed steps in detail. Thanks to this structure the text can work for kernel developers that just need to look something up, experienced FLOSS contributors that are unfamiliar with the kernel's bug reporting workflow, and users reporting something upstream for the first time. The text is thus a bit like the kernel itself, which works well for embedded machines, a typical desktop PC, cloud servers, and HPC. The document was written in the hope it will improve the quality of the bug reports, especially those that come from people unfamiliar with how Linux kernel development works. Sadly quite a few reports from this group are currently of poor quality and/or get submitted to the wrong place. Part of the problem is the old reporting-bugs document, as it makes its essence hard to grasp; it's and also inaccurate and slightly outdated in a few spots. Due to this quite a few valid reports are ignored in the end, which is annoying for those that compiled them and bad for the kernel's quality. The document near the top points out that it's still unfinished, but nevertheless ready for consumption. Those few areas in the text that might need some further discussion contain a note pointing this out. Besides lack of review from core developers there is only one major issue left: the section 'Decode failure message' is known to be outdated: it's waiting for someone familiar with the topic to write something up or give at least provide some hints and pointers what to write there. The new document is dual-licensed under GPL-2.0+ or CC-BY-4.0. The latter is way more liberal and makes it attractive to use this text as a base when writing about this topic on websites or in books. This hopefully increases the chances that such texts are accurate and stick to official way of doing things. [1] https://lkml.kernel.org/r/20201118172958.5b014a44@lwn.net Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info> CC: Thomas Gleixner <tglx@linutronix.de> CC: Greg Kroah-Hartman <gregkh@linuxfoundation.org> CC: Christoph Hellwig <hch@lst.de> Link: https://lore.kernel.org/r/e2db808f954744b79f10937a923d9c99bdca1fca.1607063223.git.linux@leemhuis.info Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-12-04 07:43:49 +01:00
reporting-issues
docs: add two documents about regression handling Create two documents explaining various aspects around regression handling and tracking; one is aimed at users, the other targets developers. The texts among others describes the first rule of Linux kernel development and what it means in practice. They also explain what a regression actually is and how to report one properly. Both texts additionally provide a brief introduction to the bot the kernel's regression tracker uses to facilitate the work, but mention the use is optional. To sum things up, provide a few quotes from Linus in the document for developers to show how serious we take regressions. Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info> Link: https://lore.kernel.org/r/34e56d3588f22d7e0b4d635ef9c9c3b33ca4ac04.1644994117.git.linux@leemhuis.info Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-02-16 07:51:33 +01:00
reporting-regressions
docs: describe how to quickly build a trimmed kernel Add a text explaining how to quickly build a kernel, as that's something users will often have to do when they want to report an issue or test proposed fixes. This is a huge and frightening task for quite a few users these days, as many rely on pre-compiled kernels and have never built their own. They find help on quite a few websites explaining the process in various ways, but those howtos often omit important details or make things too hard for the 'quickly build just for testing' case that 'localmodconfig' is really useful for. Hence give users something at hand to guide them, as that makes it easier for them to help with testing, debugging, and fixing the kernel. To keep the complexity at bay, the document explicitly focuses on how to compile the kernel on commodity distributions running on commodity hardware. People that deal with less common distributions or hardware will often know their way around already anyway. The text describes a few oddities of Arch and Debian that were found by the author and a few volunteers that tested the described procedure. There are likely more such quirks that need to be covered as well as a few things the author will have missed -- but one has to start somewhere. The document heavily uses anchors and links to them, which makes things slightly harder to read in the source form. But the intended target audience is way more likely to read rendered versions of this text on pages like docs.kernel.org anyway -- and there those anchors and links allow easy jumps to the reference section and back, which makes the document a lot easier to work with for the intended target audience. Aspects relevant for bisection were left out on purpose, as that is a related, but in the end different use case. The rough plan is to have a second document with a similar style to cover bisection. The idea is to reuse a few bits from this document and link quite often to entries in the reference section with the help of the anchors in this text. Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info> Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Link: https://lore.kernel.org/r/1a788a8e7ba8a2063df08668f565efa832016032.1678021408.git.linux@leemhuis.info Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2023-03-05 14:04:44 +01:00
quickly-build-trimmed-linux
docs: new text on bisecting which also covers bug validation Add a second document on bisecting regressions explaining the whole process from beginning to end -- while also describing how to validate if a problem is still present in mainline. This "two in one" approach is possible, as checking whenever a bug is in mainline is one of the first steps before performing a bisection anyway and thus needs to be described. Due to this approach the text also works quite nicely in conjunction with Documentation/admin-guide/reporting-issues.rst, as it covers all typical cases where users will need to build a kernel in exactly the same order. The text targets users that normally run kernels from their Linux distributor who might never have compiled their own kernel. This aim is why the first kernel built while following this guide is generated from the latest mainline codebase. This will rule out that the regression (a) was fixed already and (b) is caused by config change a vendor distributor performed; checking mainline will furthermore (c) determine if the issue is something that needs to be reported to the regular developers or the stable team (this is needed even when readers bisect within a stable series). Only then are readers instructed to build their own variant of the 'good' kernel to validate the trimmed .config file created during early in the guide, as performing a bisection with a broken one would be a waste of time. There is a small downside of this order: readers might have to go back to testing mainline, if it turns out there is a problem with their .config. But that should be rare -- and if the regression was already fixed readers might not get to this point anyway. Hence in the end this order should mean that readers built less kernels overall. This sequence allows the text to easily cover the "check if a bug is present in the upstream kernel" case while only making things a tiny bit more complicated. The text tries to prevent readers from running into many mistakes users are known to frequently make. The steps required for this might look superfluous for people that are already familiar with bisections -- but anyone with that knowledge should be able to adapt the instructions to their use-case or will not need this text at all. Style and structure of the text match the one Documentation/admin-guide/quickly-build-trimmed-linux.rst uses. Quite a few paragraphs are even copied from there and not changed at all or only slightly. This will complicate maintenance, as some future changes to one of these documents will have to be replicated in the other. But this is the lesser evil: solutions like "sending readers from one document over to the other" or "extracting the common parts into a separate document" might work in other cases, but would be too confusing here given the topic and the target audience. Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info> [jc: Undo spurious removal of subsection header line] Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <02b084a06de4ad61ac4ecd92b9265d4df4d03d71.1709282441.git.linux@leemhuis.info>
2024-03-01 09:41:06 +01:00
verify-bugs-and-bisect-regressions
docs-rst: create an user's manual book Place README, REPORTING-BUGS, SecurityBugs and kernel-parameters on an user's manual book. As we'll be numbering the user's manual, remove the manual numbering from SecurityBugs. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-09-21 09:51:11 -03:00
bug-hunting
doc-rst: admin-guide: move bug bisect to a separate file Better organize the admin guide documentation by moving the bug bisect to a separate file. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-07 17:03:17 -02:00
bug-bisect
admin-guide: move tainted kernels info to a separate file The tainted kernels info is not directly related to the oops tracing. So, let's move it to a separate file. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-07 17:03:18 -02:00
tainted-kernels
docs-rst: create an user's manual book Place README, REPORTING-BUGS, SecurityBugs and kernel-parameters on an user's manual book. As we'll be numbering the user's manual, remove the manual numbering from SecurityBugs. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-09-21 09:51:11 -03:00
ramoops
dynamic-debug-howto
docs: Clean up and organize the admin guide a bit The admin guide is a good start, but it's time to turn it into something better than an unordered blob of files. This is a first step in that direction. The TOC has been split up and annotated, the guides have been reordered, and minor tweaks have been applied to a few of them. One consequence of splitting up the TOC is that we don't really want to use :numbered: anymore, since the count resets every time and there doesn't seem to be a way to change that. Eventually we probably want to group the documents into sub-books, at which point we can go back to a single TOC, but it's probably early to do that. Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-10-26 16:14:52 -06:00
init
docs: admin-guide: add kdump documentation into it The Kdump documentation describes procedures with admins use in order to solve issues on their systems. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
2019-06-13 15:21:39 -03:00
kdump/index
docs: perf: move to the admin-guide The perf infrastructure is used for userspace to track issues. At least a good part of what's described here is related to it. So, add it to the admin-guide. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
2019-06-18 16:06:08 -03:00
perf/index
docs: admin-guide/index.rst: Add pstore-blk.rst Fix the following warning: Documentation/admin-guide/pstore-blk.rst: WARNING: document isn't included in any toctree By adding 'pstore-blk.rst' to the index Signed-off-by: Daniel W. S. Almeida <dwlsalmeida@gmail.com> Link: https://lore.kernel.org/r/20200718165107.625847-9-dwlsalmeida@gmail.com Acked-by: Kees Cook <keescook@chromium.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-07-18 13:51:03 -03:00
pstore-blk
docs: admin-guide: bring some order to the "everything else" section The bulk of the admin guide had become a big pile of stuff haphazardly tossed together, mostly in the catch-all "everything else" section. Split that section into a few broad categories and sort the documents into them as appropriate. No documents have been added or removed, they are just reordered. Note that many of these documents are severely obsolete and should be considered for removal. Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20241213182057.343527-4-corbet@lwn.net
2024-12-13 11:20:54 -07:00
clearing-warn-once
kernel-per-CPU-kthreads
lockup-watchdogs
RAS/index
sysrq
docs: Clean up and organize the admin guide a bit The admin guide is a good start, but it's time to turn it into something better than an unordered blob of files. This is a first step in that direction. The TOC has been split up and annotated, the guides have been reordered, and minor tweaks have been applied to a few of them. One consequence of splitting up the TOC is that we don't really want to use :numbered: anymore, since the count resets every time and there doesn't seem to be a way to change that. Eventually we probably want to group the documents into sub-books, at which point we can go back to a single TOC, but it's probably early to do that. Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-10-26 16:14:52 -06:00
docs: admin-guide: bring some order to the "everything else" section The bulk of the admin guide had become a big pile of stuff haphazardly tossed together, mostly in the catch-all "everything else" section. Split that section into a few broad categories and sort the documents into them as appropriate. No documents have been added or removed, they are just reordered. Note that many of these documents are severely obsolete and should be considered for removal. Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20241213182057.343527-4-corbet@lwn.net
2024-12-13 11:20:54 -07:00
Core-kernel subsystems
----------------------
docs: admin-guide: add some subsection headings As part of the goal of bringing some order to this file, add subsection headings to help readers find what they are looking for. Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20241213182057.343527-3-corbet@lwn.net
2024-12-13 11:20:53 -07:00
docs: admin-guide: bring some order to the "everything else" section The bulk of the admin guide had become a big pile of stuff haphazardly tossed together, mostly in the catch-all "everything else" section. Split that section into a few broad categories and sort the documents into them as appropriate. No documents have been added or removed, they are just reordered. Note that many of these documents are severely obsolete and should be considered for removal. Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20241213182057.343527-4-corbet@lwn.net
2024-12-13 11:20:54 -07:00
These documents describe core-kernel administration interfaces that are
likely to be of interest on almost any system.
docs: Clean up and organize the admin guide a bit The admin guide is a good start, but it's time to turn it into something better than an unordered blob of files. This is a first step in that direction. The TOC has been split up and annotated, the guides have been reordered, and minor tweaks have been applied to a few of them. One consequence of splitting up the TOC is that we don't really want to use :numbered: anymore, since the count resets every time and there doesn't seem to be a way to change that. Eventually we probably want to group the documents into sub-books, at which point we can go back to a single TOC, but it's probably early to do that. Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-10-26 16:14:52 -06:00
.. toctree::
:maxdepth: 1
admin-guide: move tainted kernels info to a separate file The tainted kernels info is not directly related to the oops tracing. So, let's move it to a separate file. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-07 17:03:18 -02:00
docs: admin-guide: bring some order to the "everything else" section The bulk of the admin guide had become a big pile of stuff haphazardly tossed together, mostly in the catch-all "everything else" section. Split that section into a few broad categories and sort the documents into them as appropriate. No documents have been added or removed, they are just reordered. Note that many of these documents are severely obsolete and should be considered for removal. Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20241213182057.343527-4-corbet@lwn.net
2024-12-13 11:20:54 -07:00
cgroup-v2
cgroup-v1/index
cpu-load
mm/index
module-signing
namespaces/index
numastat
pm/index
syscall-user-dispatch
docs: admin-guide: add some subsection headings As part of the goal of bringing some order to this file, add subsection headings to help readers find what they are looking for. Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20241213182057.343527-3-corbet@lwn.net
2024-12-13 11:20:53 -07:00
docs: admin-guide: bring some order to the "everything else" section The bulk of the admin guide had become a big pile of stuff haphazardly tossed together, mostly in the catch-all "everything else" section. Split that section into a few broad categories and sort the documents into them as appropriate. No documents have been added or removed, they are just reordered. Note that many of these documents are severely obsolete and should be considered for removal. Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20241213182057.343527-4-corbet@lwn.net
2024-12-13 11:20:54 -07:00
Support for non-native binary formats. Note that some of these
documents are ... old ...
docs: add workload-tracing document to admin-guide Add a new section to the admin-guide with information of interest to application developers and system integrators doing analysis of the Linux kernel for safety critical applications. This section will contain documents supporting analysis of kernel interactions with applications, and key kernel subsystems expectations. Add a new workload-tracing document to this new section. Signed-off-by: Shefali Sharma <sshefali021@gmail.com> Signed-off-by: Shuah Khan <skhan@linuxfoundation.org> Link: https://lore.kernel.org/r/20230131221105.39216-1-skhan@linuxfoundation.org [jc: tweaked the sphinx formatting a bit] Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2023-01-31 15:11:05 -07:00
.. toctree::
:maxdepth: 1
docs: admin-guide: bring some order to the "everything else" section The bulk of the admin guide had become a big pile of stuff haphazardly tossed together, mostly in the catch-all "everything else" section. Split that section into a few broad categories and sort the documents into them as appropriate. No documents have been added or removed, they are just reordered. Note that many of these documents are severely obsolete and should be considered for removal. Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20241213182057.343527-4-corbet@lwn.net
2024-12-13 11:20:54 -07:00
binfmt-misc
java
mono
docs: add workload-tracing document to admin-guide Add a new section to the admin-guide with information of interest to application developers and system integrators doing analysis of the Linux kernel for safety critical applications. This section will contain documents supporting analysis of kernel interactions with applications, and key kernel subsystems expectations. Add a new workload-tracing document to this new section. Signed-off-by: Shefali Sharma <sshefali021@gmail.com> Signed-off-by: Shuah Khan <skhan@linuxfoundation.org> Link: https://lore.kernel.org/r/20230131221105.39216-1-skhan@linuxfoundation.org [jc: tweaked the sphinx formatting a bit] Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2023-01-31 15:11:05 -07:00
docs: admin-guide: add some subsection headings As part of the goal of bringing some order to this file, add subsection headings to help readers find what they are looking for. Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20241213182057.343527-3-corbet@lwn.net
2024-12-13 11:20:53 -07:00
docs: admin-guide: bring some order to the "everything else" section The bulk of the admin guide had become a big pile of stuff haphazardly tossed together, mostly in the catch-all "everything else" section. Split that section into a few broad categories and sort the documents into them as appropriate. No documents have been added or removed, they are just reordered. Note that many of these documents are severely obsolete and should be considered for removal. Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20241213182057.343527-4-corbet@lwn.net
2024-12-13 11:20:54 -07:00
Block-layer and filesystem administration
-----------------------------------------
docs: Clean up and organize the admin guide a bit The admin guide is a good start, but it's time to turn it into something better than an unordered blob of files. This is a first step in that direction. The TOC has been split up and annotated, the guides have been reordered, and minor tweaks have been applied to a few of them. One consequence of splitting up the TOC is that we don't really want to use :numbered: anymore, since the count resets every time and there doesn't seem to be a way to change that. Eventually we probably want to group the documents into sub-books, at which point we can go back to a single TOC, but it's probably early to do that. Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-10-26 16:14:52 -06:00
.. toctree::
:maxdepth: 1
admin-guide: move tainted kernels info to a separate file The tainted kernels info is not directly related to the oops tracing. So, let's move it to a separate file. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-07 17:03:18 -02:00
docs: admin-guide: Sort the "unordered guides" to avoid merge conflicts Since the "unordered guides" linked in admin-guide/index.rst are not supposed to be in any particular order, let's sort them alphabetically to avoid the risk of merge conflicts by spreading newly added lines more evenly. Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-10-12 19:11:09 +02:00
bcache
binderfs
blockdev/index
cifs/index
docs: device-mapper: move it to the admin-guide The DM support describes lots of aspects related to mapped disk partitions from the userspace PoV. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
2019-06-18 12:40:23 -03:00
device-mapper/index
docs: admin-guide: Sort the "unordered guides" to avoid merge conflicts Since the "unordered guides" linked in admin-guide/index.rst are not supposed to be in any particular order, let's sort them alphabetically to avoid the risk of merge conflicts by spreading newly added lines more evenly. Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-10-12 19:11:09 +02:00
ext4
docs: Document the FAN_FS_ERROR event Document the FAN_FS_ERROR event for user administrators and user space developers. Link: https://lore.kernel.org/r/20211025192746.66445-32-krisman@collabora.com Reviewed-by: Amir Goldstein <amir73il@gmail.com> Signed-off-by: Gabriel Krisman Bertazi <krisman@collabora.com> Reviewed-by: Jan Kara <jack@suse.cz> Signed-off-by: Jan Kara <jack@suse.cz>
2021-10-25 16:27:46 -03:00
filesystem-monitoring
Documentation: convert nfs.txt to ReST This patch converts nfs.txt to RST. It also moves it to admin-guide. The reason for moving it is because this document contains information useful for system administrators, as noted on the following paragraph: 'The purpose of this document is to provide information on some of the special features of the NFS client that can be configured by system administrators'. Signed-off-by: Daniel W. S. Almeida <dwlsalmeida@gmail.com> Link: https://lore.kernel.org/r/cb9f2da2f2f6dd432b4cf9e05f79f74f4d54b6ab.1578697871.git.dwlsalmeida@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-01-10 20:24:23 -03:00
nfs/index
docs: admin-guide: add a series of orphaned documents There are lots of documents that belong to the admin-guide but are on random places (most under Documentation root dir). Move them to the admin guide. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Acked-by: Alexandre Belloni <alexandre.belloni@bootlin.com> Acked-by: Bartlomiej Zolnierkiewicz <b.zolnierkie@samsung.com>
2019-06-27 14:56:51 -03:00
iostats
docs: admin-guide: Sort the "unordered guides" to avoid merge conflicts Since the "unordered guides" linked in admin-guide/index.rst are not supposed to be in any particular order, let's sort them alphabetically to avoid the risk of merge conflicts by spreading newly added lines more evenly. Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-10-12 19:11:09 +02:00
jfs
docs: admin-guide: bring some order to the "everything else" section The bulk of the admin guide had become a big pile of stuff haphazardly tossed together, mostly in the catch-all "everything else" section. Split that section into a few broad categories and sort the documents into them as appropriate. No documents have been added or removed, they are just reordered. Note that many of these documents are severely obsolete and should be considered for removal. Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20241213182057.343527-4-corbet@lwn.net
2024-12-13 11:20:54 -07:00
md
ufs
xfs
Device-specific guides
----------------------
How to configure your hardware within your Linux system.
.. toctree::
:maxdepth: 1
acpi/index
aoe/index
auxdisplay/index
braille-console
btmrvl
dell_rbu
edid
gpio/index
hw_random
docs: admin-guide: add laptops documentation The docs under Documentation/laptops contain users specific information. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Acked-by: Andy Shevchenko <andy.shevchenko@gmail.com>
2019-06-13 15:07:43 -03:00
laptops/index
docs: admin-guide: add a series of orphaned documents There are lots of documents that belong to the admin-guide but are on random places (most under Documentation root dir). Move them to the admin guide. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Acked-by: Alexandre Belloni <alexandre.belloni@bootlin.com> Acked-by: Bartlomiej Zolnierkiewicz <b.zolnierkie@samsung.com>
2019-06-27 14:56:51 -03:00
lcd-panel-cgram
media: docs: move user-facing docs to the admin guide Most of the driver-specific documentation is meant to help users of the media subsystem. Move them to the admin-guide. It should be noticed, however, that several of those files are outdated and will require further work in order to make them useful again. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
2020-03-04 13:08:03 +01:00
media/index
docs: admin-guide: bring some order to the "everything else" section The bulk of the admin guide had become a big pile of stuff haphazardly tossed together, mostly in the catch-all "everything else" section. Split that section into a few broad categories and sort the documents into them as appropriate. No documents have been added or removed, they are just reordered. Note that many of these documents are severely obsolete and should be considered for removal. Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20241213182057.343527-4-corbet@lwn.net
2024-12-13 11:20:54 -07:00
nvme-multipath
docs: admin-guide: Sort the "unordered guides" to avoid merge conflicts Since the "unordered guides" linked in admin-guide/index.rst are not supposed to be in any particular order, let's sort them alphabetically to avoid the risk of merge conflicts by spreading newly added lines more evenly. Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-10-12 19:11:09 +02:00
parport
docs: admin-guide: add a series of orphaned documents There are lots of documents that belong to the admin-guide but are on random places (most under Documentation root dir). Move them to the admin guide. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Acked-by: Alexandre Belloni <alexandre.belloni@bootlin.com> Acked-by: Bartlomiej Zolnierkiewicz <b.zolnierkie@samsung.com>
2019-06-27 14:56:51 -03:00
pnp
docs: admin-guide: Sort the "unordered guides" to avoid merge conflicts Since the "unordered guides" linked in admin-guide/index.rst are not supposed to be in any particular order, let's sort them alphabetically to avoid the risk of merge conflicts by spreading newly added lines more evenly. Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-10-12 19:11:09 +02:00
rapidio
docs: admin-guide: add a series of orphaned documents There are lots of documents that belong to the admin-guide but are on random places (most under Documentation root dir). Move them to the admin guide. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Acked-by: Alexandre Belloni <alexandre.belloni@bootlin.com> Acked-by: Bartlomiej Zolnierkiewicz <b.zolnierkie@samsung.com>
2019-06-27 14:56:51 -03:00
rtc
docs: admin-guide: Sort the "unordered guides" to avoid merge conflicts Since the "unordered guides" linked in admin-guide/index.rst are not supposed to be in any particular order, let's sort them alphabetically to avoid the risk of merge conflicts by spreading newly added lines more evenly. Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-10-12 19:11:09 +02:00
serial-console
docs: admin-guide: add a series of orphaned documents There are lots of documents that belong to the admin-guide but are on random places (most under Documentation root dir). Move them to the admin guide. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Acked-by: Alexandre Belloni <alexandre.belloni@bootlin.com> Acked-by: Bartlomiej Zolnierkiewicz <b.zolnierkie@samsung.com>
2019-06-27 14:56:51 -03:00
svga
Documentation: admin-guide: Add toctree entry for thermal docs kernel test robot reported htmldocs warnings: Documentation/admin-guide/index.rst:62: WARNING: toctree contains reference to nonexisting document 'admin-guide/thermal' Documentation/admin-guide/thermal/intel_powerclamp.rst: WARNING: document isn't included in any toctree Add toctree entry for thermal/ docs to fix these warnings. Link: https://lore.kernel.org/linux-doc/202302121759.MmJgDTxc-lkp@intel.com/ Fixes: 707bf8e1dfd51d ("Documentation: admin-guide: Move intel_powerclamp documentation") Reported-by: kernel test robot <lkp@intel.com> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com> Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
2023-02-13 17:07:59 +07:00
thermal/index
docs: admin-guide: Sort the "unordered guides" to avoid merge conflicts Since the "unordered guides" linked in admin-guide/index.rst are not supposed to be in any particular order, let's sort them alphabetically to avoid the risk of merge conflicts by spreading newly added lines more evenly. Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-10-12 19:11:09 +02:00
thunderbolt
vga-softcursor
docs: admin-guide: add a series of orphaned documents There are lots of documents that belong to the admin-guide but are on random places (most under Documentation root dir). Move them to the admin guide. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Acked-by: Alexandre Belloni <alexandre.belloni@bootlin.com> Acked-by: Bartlomiej Zolnierkiewicz <b.zolnierkie@samsung.com>
2019-06-27 14:56:51 -03:00
video-output
docs: admin-guide: bring some order to the "everything else" section The bulk of the admin guide had become a big pile of stuff haphazardly tossed together, mostly in the catch-all "everything else" section. Split that section into a few broad categories and sort the documents into them as appropriate. No documents have been added or removed, they are just reordered. Note that many of these documents are severely obsolete and should be considered for removal. Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20241213182057.343527-4-corbet@lwn.net
2024-12-13 11:20:54 -07:00
Workload analysis
-----------------
This is the beginning of a section with information of interest to
application developers and system integrators doing analysis of the
Linux kernel for safety critical applications. Documents supporting
analysis of kernel interactions with applications, and key kernel
subsystems expectations will be found here.
.. toctree::
:maxdepth: 1
workload-tracing
Everything else
---------------
A few hard-to-categorize and generally obsolete documents.
.. toctree::
:maxdepth: 1
ldm
unicode
doc-rst: include index only in subproject AND html The index should only be included if the build of the sub-folder is done with the html-builder (HTML output). Signed-off-by: Markus Heiser <markus.heiser@darmarit.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-10-26 08:23:16 +02:00
.. only:: subproject and html
Indices
=======
* :ref:`genindex`
Reference in a new issue Copy permalink