Bug 175763 - misleading overcommit_memory reference in Documentation/filesystems/proc.txt
misleading overcommit_memory reference in Documentation/filesystems/proc.txt
Status: CLOSED ERRATA
Product: Red Hat Enterprise Linux 4
Classification: Red Hat
Component: kernel (Show other bugs)
4.0
All Linux
medium Severity medium
: ---
: ---
Assigned To: Alan Cox
Brian Brock
:
Depends On:
Blocks: 181409
  Show dependency treegraph
 
Reported: 2005-12-14 14:37 EST by Bryn M. Reeves
Modified: 2007-11-30 17:07 EST (History)
1 user (show)

See Also:
Fixed In Version: RHSA-2006-0575
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2006-08-10 17:45:28 EDT
Type: ---
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)
correct misleading description of overcommit_memory in proc.txt (1.98 KB, patch)
2005-12-14 17:01 EST, Bryn M. Reeves
no flags Details | Diff
change description of Commited_AS /proc/meminfo item (2.28 KB, patch)
2005-12-14 17:07 EST, Bryn M. Reeves
no flags Details | Diff

  None (edit)
Description Bryn M. Reeves 2005-12-14 14:37:05 EST
From Bugzilla Helper:
User-Agent: Mozilla/5.0 (X11; U; Linux i686; en-GB; rv:1.7.12) Gecko/20050922 Fedora/1.0.7-1.1.fc4 Firefox/1.0.7

Description of problem:
The file Documentation/filesystems/proc.txt contains the following incorrect description of the overcommit_memory sysctl:

---begin---
overcommit_memory
-----------------

This file  contains  one  value.  The following algorithm is used to decide if
there's enough  memory:  if  the  value of overcommit_memory is positive, then
there's always  enough  memory. This is a useful feature, since programs often
malloc() huge  amounts  of  memory 'just in case', while they only use a small
part of  it.  Leaving  this value at 0 will lead to the failure of such a huge
malloc(), when in fact the system has enough memory for the program to run.

On the  other  hand,  enabling this feature can cause you to run out of memory
and thrash the system to death, so large and/or important servers will want to
set this value to 0.
---end---

This suggests that 0 is used to disable the feature, when in fact this enables heuristic overcommit mode. The statement that positive values enable overcommit is also untrue. 

The documentation was fixed upstream in 2.6.14.

This feature is documented correctly in at least two other files (vm/overcommit-accounting and sysctl/vm.txt) but the current state obviously confuses people and has crept into other documentation. This is compounded by a lack of references from proc.txt to these other files. 


Version-Release number of selected component (if applicable):
kernel-doc-2.6.9-22

How reproducible:
Always

Steps to Reproduce:
Read the file Documentation/filesystems/proc.txt packaged in the RHEL4 kernel-doc package or SRPM.

Actual Results:  Documentation is incorrect.

Expected Results:  Documentation should be consistent with other files and the kernel's actual behaviour. 

Additional info:
Comment 1 Bryn M. Reeves 2005-12-14 17:01:43 EST
Created attachment 122250 [details]
correct misleading description of overcommit_memory in proc.txt

The patch brings the RHEL4 kernel documentation inline with upstream 2.6.14.
Although there are functional changes in this area between the kernel versions,
the new upstream description of this sysctl still applies to the RHEL4
implementation and correctly describes the overcommit modes (unlike current
proc.txt).
Comment 2 Bryn M. Reeves 2005-12-14 17:07:37 EST
Created attachment 122251 [details]
change description of Commited_AS /proc/meminfo item

This patch replaces the description of Committed_AS to match the upstream
2.6.14 version. There is nothing incorrect about the original description, but
the new upstream version has useful cross references to the overcommit_memory
mode.

This is more debatable than the previous patch, hence posting separately.
Comment 3 Alan Cox 2006-01-19 05:43:32 EST
Both look fine to me. Not sure if the change is worth the effort for RHEL4 but
if product management want to get the change made then fine.
Comment 4 Jason Baron 2006-04-03 13:47:19 EDT
committed in stream U4 build 34.11. A test kernel with this patch is available
from http://people.redhat.com/~jbaron/rhel4/
Comment 5 Bryn M. Reeves 2006-04-20 07:03:57 EDT
Just checked kernel-doc-2.6.9-34.19.EL.noarch.rpm and the overcommit stuff in
proc.txt looks fine now.

Thanks,

Bryn.
Comment 9 Red Hat Bugzilla 2006-08-10 17:45:28 EDT
An advisory has been issued which should help the problem
described in this bug report. This report is therefore being
closed with a resolution of ERRATA. For more information
on the solution and/or where to find the updated files,
please follow the link below. You may reopen this bug report
if the solution does not work for you.

http://rhn.redhat.com/errata/RHSA-2006-0575.html

Note You need to log in before you can comment on or make changes to this bug.