Skip to contentSkip to conversation

Update/kill Documentation/sysctl/* docs?

RFC In review Diego Calleja 2 participants 4 messages May 8, 2006 – May 11, 2006 Documentation

lore
Share & tools
lore
#0 lore raw

RFC 1/1 Update/kill Documentation/sysctl/* docs?

In http://bugzilla.kernel.org/show_bug.cgi?id=6145 you asked to update the sysctl docs. I've updated them and added/deleted the neccesary stuff (except the ones that I don't know what on earth are they doing because they're not...documented). However it looks like there's duplication - Documentation/filesystems/proc.txt seems to document all that aswell (but in a single doc, which makes it a bit unreadable for such big document, IMO)

What should be the best step? Kill Documentation/sysctl/ and keep filesystems/proc.txt updated and maybe split it in several files to make it more readable? Update it but maintain in sync with filesystems/proc.txt? delete proc.txt and keep sysctl/ updated...?

Documentation/sysctl/fs.txt renamed from Documentation/sysctl/fs.txt.old +45 -27
@@ -1,4 +1,4 @@
-Documentation for /proc/sys/fs/*	kernel version 2.2.10
+Documentation for /proc/sys/fs/*
 	(c) 1998, 1999,  Rik van Riel <[email protected]>
 
 For general info and legal blurb, please look in README.
@@ -6,7 +6,7 @@
 ==============================================================
 
 This file contains documentation for the sysctl files in
-/proc/sys/fs/ and is valid for Linux kernel version 2.2.
+/proc/sys/fs/
 
 The files in this directory can be used to tune and monitor
 miscellaneous and general things in the operation of the Linux
@@ -15,21 +15,29 @@
 before actually making adjustments.
 
 Currently, these files are in /proc/sys/fs:
+- aio-max-nr
+- aio-nr
+- binfmt_misc/ ==> see Documentation/binfmt_misc.txt
 - dentry-state
 - dquot-max
 - dquot-nr
+- dir-notify-enable
 - file-max
 - file-nr
-- inode-max
 - inode-nr
 - inode-state
+- inotify/ ==> See Documentation/filesystem/inotify.txt
 - overflowuid
 - overflowgid
-- super-max
-- super-nr
+- suid_dumpable
 
-Documentation for the files in /proc/sys/fs/binfmt_misc is
-in Documentation/binfmt_misc.txt.
+==============================================================
+
+aio-nr & aio-max-nr:
+
+aio-nr shows the current system-wide number of asynchronous io
+requests.  aio-max-nr allows you to change the maximum value
+aio-nr can grow to.
 
 ==============================================================
 
@@ -71,6 +79,21 @@
 
 ==============================================================
 
+dir-notify-enable:
+
+This file controls dnotify, a directory notification mechanism,
+and will not appear if dnotify support is compiled out. It was
+introduced with inotify (see Documentation/filesystems/inotify.txt)
+in case some people want to disable dnotify support at runtime.
+There're two possible values:
+
+1 - dnotify is enabled (default)
+0 - dnotify is disabled
+
+For more information about dnotify, see Documentation/dnotify.txt
+
+==============================================================
+
 file-max & file-nr:
 
 The kernel allocates file handles dynamically, but as yet it
@@ -90,17 +113,11 @@
 
 ==============================================================
 
-inode-max, inode-nr & inode-state:
+inode-nr & inode-state:
 
 As with file handles, the kernel allocates the inode structures
 dynamically, but can't free them yet.
 
-The value in inode-max denotes the maximum number of inode
-handlers. This value should be 3-4 times larger than the value
-in file-max, since stdin, stdout and network sockets also
-need an inode struct to handle them. When you regularly run
-out of inodes, you need to increase this value.
-
 The file inode-nr contains the first two items from
 inode-state, so we'll skip to that file...
 
@@ -131,20 +148,21 @@
 
 ==============================================================
 
-super-max & super-nr:
-
-These numbers control the maximum number of superblocks, and
-thus the maximum number of mounted filesystems the kernel
-can have. You only need to increase super-max if you need to
-mount more filesystems than the current value in super-max
-allows you to.
-
-==============================================================
+suid_dumpable:
 
-aio-nr & aio-max-nr:
+This value can be used to query and set the core dump mode for setuid
+or otherwise protected/tainted binaries. The modes are
 
-aio-nr shows the current system-wide number of asynchronous io
-requests.  aio-max-nr allows you to change the maximum value
-aio-nr can grow to.
+0 - (default) - traditional behaviour. Any process which has changed
+    privilege levels or is execute only will not be dumped
+1 - (debug) - all processes dump core when possible. The core dump is
+    owned by the current user and no security is applied. This is
+    intended for system debugging situations only. Ptrace is unchecked.
+2 - (suidsafe) - any binary which normally would not be dumped is dumped
+    readable by root only. This allows the end user to remove
+    such a dump but not access it directly. For security reasons
+    core dumps in this mode will not overwrite one another or
+    other files. This mode is appropriate when adminstrators are
+    attempting to debug problems in a normal environment.
 
 ==============================================================
Documentation/sysctl/kernel.txt renamed from Documentation/sysctl/kernel.txt.old +50 -27

149 lines not on this page · raw message

#1 lore raw
Quoted 5 lines · Diego Calleja

In http://bugzilla.kernel.org/show_bug.cgi?id=6145 you asked to update
the sysctl docs. I've updated them and added/deleted the neccesary stuff (except the ones that I don't know what on earth are they doing because they're not...documented).

OK..

Quoted 4 lines

However it looks like there's
duplication - Documentation/filesystems/proc.txt seems to document all that aswell (but in a single doc, which makes it a bit unreadable for such big document, IMO)

Yes, the duplication is silly and wasteful and error-inducing.

Quoted 4 lines

What should be the best step? Kill Documentation/sysctl/ and keep filesystems/proc.txt updated and maybe split it in several files to make it more readable? Update it but maintain in sync with filesystems/proc.txt? delete proc.txt and keep sysctl/ updated...?

I'd have thought that keeping everything in Documentation/sysctl/*.txt and killing proc.txt would be the best approach?

But I haven't looked into it much. You have - what approach are you recommending?

#2 lore raw
Quoted 5 lines · Andrew Morton

I'd have thought that keeping everything in Documentation/sysctl/*.txt and killing proc.txt would be the best approach?

But I haven't looked into it much. You have - what approach are you recommending?

Well, filesystems/proc.txt is somewhat more updated than sysctl/* - 2.4 vs 2.2 (sic) (and some small 2.6 updates spread in both places). However, filesystems/* should only contain IMO docs about the filesystem themselves not about the data in the filesystems, and proc.txt only documents sysctls, nothing else.

So I guess the Right Thing would be to move proc.txt to Documentation/sysctl, and use e-violence to make people update the non-documented parts ;) (And apparently there's more sysctl stuff lost in the noise like networking/ip-sysctl.txt, etc)

I'll try to move everything to sysctl/ and will post a RFC about it.

(Wouldn't have sense to have a Documentation/sysfs directory documenting the sysfs interfaces aswell?)

#3 lore raw
Quoted 3 lines · Diego Calleja

(Wouldn't have sense to have a Documentation/sysfs directory documenting
the sysfs interfaces aswell?)

Spose so. It would take a lot of your e-violence to get that filled out.