begriffs open source - ai-pg/blob - full-docs/src/sgml/html/kernel-resources.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>18.4. Managing Kernel Resources</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="server-start.html" title="18.3. Starting the Database Server" /><link rel="next" href="server-shutdown.html" title="18.5. Shutting Down the Server" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">18.4. Managing Kernel Resources</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="server-start.html" title="18.3. Starting the Database Server">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="runtime.html" title="Chapter 18. Server Setup and Operation">Up</a></td><th width="60%" align="center">Chapter 18. Server Setup and Operation</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="server-shutdown.html" title="18.5. Shutting Down the Server">Next</a></td></tr></table><hr /></div><div class="sect1" id="KERNEL-RESOURCES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">18.4. Managing Kernel Resources <a href="#KERNEL-RESOURCES" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="kernel-resources.html#SYSVIPC">18.4.1. Shared Memory and Semaphores</a></span></dt><dt><span class="sect2"><a href="kernel-resources.html#SYSTEMD-REMOVEIPC">18.4.2. systemd RemoveIPC</a></span></dt><dt><span class="sect2"><a href="kernel-resources.html#KERNEL-RESOURCES-LIMITS">18.4.3. Resource Limits</a></span></dt><dt><span class="sect2"><a href="kernel-resources.html#LINUX-MEMORY-OVERCOMMIT">18.4.4. Linux Memory Overcommit</a></span></dt><dt><span class="sect2"><a href="kernel-resources.html#LINUX-HUGE-PAGES">18.4.5. Linux Huge Pages</a></span></dt></dl></div><p>
   3    <span class="productname">PostgreSQL</span> can sometimes exhaust various operating system
   4    resource limits, especially when multiple copies of the server are running
   5    on the same system, or in very large installations.  This section explains
   6    the kernel resources used by <span class="productname">PostgreSQL</span> and the steps you
   7    can take to resolve problems related to kernel resource consumption.
   8   </p><div class="sect2" id="SYSVIPC"><div class="titlepage"><div><div><h3 class="title">18.4.1. Shared Memory and Semaphores <a href="#SYSVIPC" class="id_link">#</a></h3></div></div></div><a id="id-1.6.5.7.3.2" class="indexterm"></a><a id="id-1.6.5.7.3.3" class="indexterm"></a><p>
   9     <span class="productname">PostgreSQL</span> requires the operating system to provide
  10     inter-process communication (<acronym class="acronym">IPC</acronym>) features, specifically
  11     shared memory and semaphores.  Unix-derived systems typically provide
  12     <span class="quote">“<span class="quote"><span class="systemitem">System V</span></span>”</span> <acronym class="acronym">IPC</acronym>,
  13     <span class="quote">“<span class="quote"><span class="systemitem">POSIX</span></span>”</span> <acronym class="acronym">IPC</acronym>, or both.
  14     <span class="systemitem">Windows</span> has its own implementation of
  15     these features and is not discussed here.
  16    </p><p>
  17     By default, <span class="productname">PostgreSQL</span> allocates
  18     a very small amount of System V shared memory, as well as a much larger
  19     amount of anonymous <code class="function">mmap</code> shared memory.
  20     Alternatively, a single large System V shared memory region can be used
  21     (see <a class="xref" href="runtime-config-resource.html#GUC-SHARED-MEMORY-TYPE">shared_memory_type</a>).
  22
  23     In addition a significant number of semaphores, which can be either
  24     System V or POSIX style, are created at server startup.  Currently,
  25     POSIX semaphores are used on Linux and FreeBSD systems while other
  26     platforms use System V semaphores.
  27    </p><p>
  28     System V <acronym class="acronym">IPC</acronym> features are typically constrained by
  29     system-wide allocation limits.
  30     When <span class="productname">PostgreSQL</span> exceeds one of these limits,
  31     the server will refuse to start and
  32     should leave an instructive error message describing the problem
  33     and what to do about it. (See also <a class="xref" href="server-start.html#SERVER-START-FAILURES" title="18.3.1. Server Start-up Failures">Section 18.3.1</a>.) The relevant kernel
  34     parameters are named consistently across different systems; <a class="xref" href="kernel-resources.html#SYSVIPC-PARAMETERS" title="Table 18.1. System V IPC Parameters">Table 18.1</a> gives an overview. The methods to set
  35     them, however, vary. Suggestions for some platforms are given below.
  36    </p><div class="table" id="SYSVIPC-PARAMETERS"><p class="title"><strong>Table 18.1. <span class="systemitem">System V</span> <acronym class="acronym">IPC</acronym> Parameters</strong></p><div class="table-contents"><table class="table" summary="System V IPC Parameters" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /></colgroup><thead><tr><th>Name</th><th>Description</th><th>Values needed to run one <span class="productname">PostgreSQL</span> instance</th></tr></thead><tbody><tr><td><code class="varname">SHMMAX</code></td><td>Maximum size of shared memory segment (bytes)</td><td>at least 1kB, but the default is usually much higher</td></tr><tr><td><code class="varname">SHMMIN</code></td><td>Minimum size of shared memory segment (bytes)</td><td>1</td></tr><tr><td><code class="varname">SHMALL</code></td><td>Total amount of shared memory available (bytes or pages)</td><td>same as <code class="varname">SHMMAX</code> if bytes,
  37         or <code class="literal">ceil(SHMMAX/PAGE_SIZE)</code> if pages,
  38         plus room for other applications</td></tr><tr><td><code class="varname">SHMSEG</code></td><td>Maximum number of shared memory segments per process</td><td>only 1 segment is needed, but the default is much higher</td></tr><tr><td><code class="varname">SHMMNI</code></td><td>Maximum number of shared memory segments system-wide</td><td>like <code class="varname">SHMSEG</code> plus room for other applications</td></tr><tr><td><code class="varname">SEMMNI</code></td><td>Maximum number of semaphore identifiers (i.e., sets)</td><td>at least <code class="literal">ceil(num_os_semaphores / 16)</code> plus room for other applications</td></tr><tr><td><code class="varname">SEMMNS</code></td><td>Maximum number of semaphores system-wide</td><td><code class="literal">ceil(num_os_semaphores / 16) * 17</code> plus room for other applications</td></tr><tr><td><code class="varname">SEMMSL</code></td><td>Maximum number of semaphores per set</td><td>at least 17</td></tr><tr><td><code class="varname">SEMMAP</code></td><td>Number of entries in semaphore map</td><td>see text</td></tr><tr><td><code class="varname">SEMVMX</code></td><td>Maximum value of semaphore</td><td>at least 1000 (The default is often 32767; do not change unless necessary)</td></tr></tbody></table></div></div><br class="table-break" /><p>
  39     <span class="productname">PostgreSQL</span> requires a few bytes of System V shared memory
  40     (typically 48 bytes, on 64-bit platforms) for each copy of the server.
  41     On most modern operating systems, this amount can easily be allocated.
  42     However, if you are running many copies of the server or you explicitly
  43     configure the server to use large amounts of System V shared memory (see
  44     <a class="xref" href="runtime-config-resource.html#GUC-SHARED-MEMORY-TYPE">shared_memory_type</a> and <a class="xref" href="runtime-config-resource.html#GUC-DYNAMIC-SHARED-MEMORY-TYPE">dynamic_shared_memory_type</a>), it may be necessary to
  45     increase <code class="varname">SHMALL</code>, which is the total amount of System V shared
  46     memory system-wide.  Note that <code class="varname">SHMALL</code> is measured in pages
  47     rather than bytes on many systems.
  48    </p><p>
  49     Less likely to cause problems is the minimum size for shared
  50     memory segments (<code class="varname">SHMMIN</code>), which should be at most
  51     approximately 32 bytes for <span class="productname">PostgreSQL</span> (it is
  52     usually just 1). The maximum number of segments system-wide
  53     (<code class="varname">SHMMNI</code>) or per-process (<code class="varname">SHMSEG</code>) are unlikely
  54     to cause a problem unless your system has them set to zero.
  55    </p><p>
  56     When using System V semaphores,
  57     <span class="productname">PostgreSQL</span> uses one semaphore per allowed connection
  58     (<a class="xref" href="runtime-config-connection.html#GUC-MAX-CONNECTIONS">max_connections</a>), allowed autovacuum worker process
  59     (<a class="xref" href="runtime-config-vacuum.html#GUC-AUTOVACUUM-WORKER-SLOTS">autovacuum_worker_slots</a>), allowed WAL sender process
  60     (<a class="xref" href="runtime-config-replication.html#GUC-MAX-WAL-SENDERS">max_wal_senders</a>), allowed background
  61     process (<a class="xref" href="runtime-config-resource.html#GUC-MAX-WORKER-PROCESSES">max_worker_processes</a>), etc., in sets of 16.
  62     The runtime-computed parameter <a class="xref" href="runtime-config-preset.html#GUC-NUM-OS-SEMAPHORES">num_os_semaphores</a>
  63     reports the number of semaphores required.  This parameter can be viewed
  64     before starting the server with a <code class="command">postgres</code> command like:
  65 </p><pre class="programlisting">
  66 $ <strong class="userinput"><code>postgres -D $PGDATA -C num_os_semaphores</code></strong>
  67 </pre><p>
  68    </p><p>
  69     Each set of 16 semaphores will
  70     also contain a 17th semaphore which contains a <span class="quote">“<span class="quote">magic
  71     number</span>”</span>, to detect collision with semaphore sets used by
  72     other applications. The maximum number of semaphores in the system
  73     is set by <code class="varname">SEMMNS</code>, which consequently must be at least
  74     as high as <code class="literal">num_os_semaphores</code> plus one extra for
  75     each set of 16 required semaphores (see the formula in <a class="xref" href="kernel-resources.html#SYSVIPC-PARAMETERS" title="Table 18.1. System V IPC Parameters">Table 18.1</a>).  The parameter <code class="varname">SEMMNI</code>
  76     determines the limit on the number of semaphore sets that can
  77     exist on the system at one time.  Hence this parameter must be at
  78     least <code class="literal">ceil(num_os_semaphores / 16)</code>.
  79     Lowering the number
  80     of allowed connections is a temporary workaround for failures,
  81     which are usually confusingly worded <span class="quote">“<span class="quote">No space
  82     left on device</span>”</span>, from the function <code class="function">semget</code>.
  83    </p><p>
  84     In some cases it might also be necessary to increase
  85     <code class="varname">SEMMAP</code> to be at least on the order of
  86     <code class="varname">SEMMNS</code>.  If the system has this parameter
  87     (many do not), it defines the size of the semaphore
  88     resource map, in which each contiguous block of available semaphores
  89     needs an entry. When a semaphore set is freed it is either added to
  90     an existing entry that is adjacent to the freed block or it is
  91     registered under a new map entry. If the map is full, the freed
  92     semaphores get lost (until reboot). Fragmentation of the semaphore
  93     space could over time lead to fewer available semaphores than there
  94     should be.
  95    </p><p>
  96     Various other settings related to <span class="quote">“<span class="quote">semaphore undo</span>”</span>, such as
  97     <code class="varname">SEMMNU</code> and <code class="varname">SEMUME</code>, do not affect
  98     <span class="productname">PostgreSQL</span>.
  99    </p><p>
 100     When using POSIX semaphores, the number of semaphores needed is the
 101     same as for System V, that is one semaphore per allowed connection
 102     (<a class="xref" href="runtime-config-connection.html#GUC-MAX-CONNECTIONS">max_connections</a>), allowed autovacuum worker process
 103     (<a class="xref" href="runtime-config-vacuum.html#GUC-AUTOVACUUM-WORKER-SLOTS">autovacuum_worker_slots</a>), allowed WAL sender process
 104     (<a class="xref" href="runtime-config-replication.html#GUC-MAX-WAL-SENDERS">max_wal_senders</a>), allowed background
 105     process (<a class="xref" href="runtime-config-resource.html#GUC-MAX-WORKER-PROCESSES">max_worker_processes</a>), etc.
 106     On the platforms where this option is preferred, there is no specific
 107     kernel limit on the number of POSIX semaphores.
 108    </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="systemitem">FreeBSD</span>
 109       <a id="id-1.6.5.7.3.15.1.1.2" class="indexterm"></a>
 110       </span></dt><dd><p>
 111         The default shared memory settings are usually good enough, unless
 112         you have set <code class="literal">shared_memory_type</code> to <code class="literal">sysv</code>.
 113         System V semaphores are not used on this platform.
 114        </p><p>
 115         The default IPC settings can be changed using
 116         the <code class="command">sysctl</code> or
 117         <code class="command">loader</code> interfaces.  The following
 118         parameters can be set using <code class="command">sysctl</code>:
 119 </p><pre class="screen">
 120 <code class="prompt">#</code> <strong class="userinput"><code>sysctl kern.ipc.shmall=32768</code></strong>
 121 <code class="prompt">#</code> <strong class="userinput"><code>sysctl kern.ipc.shmmax=134217728</code></strong>
 122 </pre><p>
 123         To make these settings persist over reboots, modify
 124         <code class="filename">/etc/sysctl.conf</code>.
 125        </p><p>
 126         If you have set <code class="literal">shared_memory_type</code> to
 127         <code class="literal">sysv</code>, you might also want to configure your kernel
 128         to lock System V shared memory into RAM and prevent it from being paged
 129         out to swap.  This can be accomplished using the <code class="command">sysctl</code>
 130         setting <code class="literal">kern.ipc.shm_use_phys</code>.
 131        </p><p>
 132         If running in a FreeBSD jail, you should set its
 133         <code class="literal">sysvshm</code> parameter to <code class="literal">new</code>, so that
 134         it has its own separate System V shared memory namespace.
 135         (Before FreeBSD 11.0, it was necessary to enable shared access to
 136         the host's IPC namespace from jails, and take measures to avoid
 137         collisions.)
 138        </p></dd><dt><span class="term"><span class="systemitem">NetBSD</span>
 139       <a id="id-1.6.5.7.3.15.2.1.2" class="indexterm"></a>
 140       </span></dt><dd><p>
 141         The default shared memory settings are usually good enough, unless
 142         you have set <code class="literal">shared_memory_type</code> to <code class="literal">sysv</code>.
 143         However, you will need to increase <code class="literal">kern.ipc.semmni</code>
 144         and <code class="literal">kern.ipc.semmns</code>,
 145         as <span class="systemitem">NetBSD</span>'s default settings
 146         for these are unworkably small.
 147        </p><p>
 148         IPC parameters can be adjusted using <code class="command">sysctl</code>,
 149         for example:
 150 </p><pre class="screen">
 151 <code class="prompt">#</code> <strong class="userinput"><code>sysctl -w kern.ipc.semmni=100</code></strong>
 152 </pre><p>
 153         To make these settings persist over reboots, modify
 154         <code class="filename">/etc/sysctl.conf</code>.
 155        </p><p>
 156         If you have set <code class="literal">shared_memory_type</code> to
 157         <code class="literal">sysv</code>, you might also want to configure your kernel
 158         to lock System V shared memory into RAM and prevent it from being paged
 159         out to swap.  This can be accomplished using the <code class="command">sysctl</code>
 160         setting <code class="literal">kern.ipc.shm_use_phys</code>.
 161        </p></dd><dt><span class="term"><span class="systemitem">OpenBSD</span>
 162       <a id="id-1.6.5.7.3.15.3.1.2" class="indexterm"></a>
 163       </span></dt><dd><p>
 164         The default shared memory settings are usually good enough, unless
 165         you have set <code class="literal">shared_memory_type</code> to <code class="literal">sysv</code>.
 166         However, you will need to
 167         increase <code class="literal">kern.seminfo.semmni</code>
 168         and <code class="literal">kern.seminfo.semmns</code>,
 169         as <span class="systemitem">OpenBSD</span>'s default settings
 170         for these are unworkably small.
 171        </p><p>
 172         IPC parameters can be adjusted using <code class="command">sysctl</code>,
 173         for example:
 174 </p><pre class="screen">
 175 <code class="prompt">#</code> <strong class="userinput"><code>sysctl kern.seminfo.semmni=100</code></strong>
 176 </pre><p>
 177         To make these settings persist over reboots, modify
 178         <code class="filename">/etc/sysctl.conf</code>.
 179        </p></dd><dt><span class="term"><span class="systemitem">Linux</span>
 180       <a id="id-1.6.5.7.3.15.4.1.2" class="indexterm"></a>
 181       </span></dt><dd><p>
 182         The default shared memory settings are usually good enough, unless
 183         you have set <code class="literal">shared_memory_type</code> to <code class="literal">sysv</code>,
 184         and even then only on older kernel versions that shipped with low defaults.
 185         System V semaphores are not used on this platform.
 186        </p><p>
 187         The shared memory size settings can be changed via the
 188         <code class="command">sysctl</code> interface.  For example, to allow 16 GB:
 189 </p><pre class="screen">
 190 <code class="prompt">$</code> <strong class="userinput"><code>sysctl -w kernel.shmmax=17179869184</code></strong>
 191 <code class="prompt">$</code> <strong class="userinput"><code>sysctl -w kernel.shmall=4194304</code></strong>
 192 </pre><p>
 193         To make these settings persist over reboots, see
 194         <code class="filename">/etc/sysctl.conf</code>.
 195        </p></dd><dt><span class="term"><span class="systemitem">macOS</span>
 196       <a id="id-1.6.5.7.3.15.5.1.2" class="indexterm"></a>
 197       </span></dt><dd><p>
 198         The default shared memory and semaphore settings are usually good enough, unless
 199         you have set <code class="literal">shared_memory_type</code> to <code class="literal">sysv</code>.
 200        </p><p>
 201         The recommended method for configuring shared memory in macOS
 202         is to create a file named <code class="filename">/etc/sysctl.conf</code>,
 203         containing variable assignments such as:
 204 </p><pre class="programlisting">
 205 kern.sysv.shmmax=4194304
 206 kern.sysv.shmmin=1
 207 kern.sysv.shmmni=32
 208 kern.sysv.shmseg=8
 209 kern.sysv.shmall=1024
 210 </pre><p>
 211         Note that in some macOS versions,
 212         <span class="emphasis"><em>all five</em></span> shared-memory parameters must be set in
 213         <code class="filename">/etc/sysctl.conf</code>, else the values will be ignored.
 214        </p><p>
 215         <code class="varname">SHMMAX</code> can only be set to a multiple of 4096.
 216        </p><p>
 217         <code class="varname">SHMALL</code> is measured in 4 kB pages on this platform.
 218        </p><p>
 219         It is possible to change all but <code class="varname">SHMMNI</code> on the fly, using
 220         <span class="application">sysctl</span>.  But it's still best to set up your preferred
 221         values via <code class="filename">/etc/sysctl.conf</code>, so that the values will be
 222         kept across reboots.
 223        </p></dd><dt><span class="term"><span class="systemitem">Solaris</span><br /></span><span class="term"><span class="systemitem">illumos</span></span></dt><dd><p>
 224         The default shared memory and semaphore settings are usually good enough for most
 225         <span class="productname">PostgreSQL</span> applications.  Solaris defaults
 226         to a <code class="varname">SHMMAX</code> of one-quarter of system <acronym class="acronym">RAM</acronym>.
 227         To further adjust this setting, use a project setting associated
 228         with the <code class="literal">postgres</code> user.  For example, run the
 229         following as <code class="literal">root</code>:
 230 </p><pre class="programlisting">
 231 projadd -c "PostgreSQL DB User" -K "project.max-shm-memory=(privileged,8GB,deny)" -U postgres -G postgres user.postgres
 232 </pre><p>
 233        </p><p>
 234         This command adds the <code class="literal">user.postgres</code> project and
 235         sets the shared memory maximum for the <code class="literal">postgres</code>
 236         user to 8GB, and takes effect the next time that user logs
 237         in, or when you restart <span class="productname">PostgreSQL</span> (not reload).
 238         The above assumes that <span class="productname">PostgreSQL</span> is run by
 239         the <code class="literal">postgres</code> user in the <code class="literal">postgres</code>
 240         group.  No server reboot is required.
 241        </p><p>
 242         Other recommended kernel setting changes for database servers which will
 243         have a large number of connections are:
 244 </p><pre class="programlisting">
 245 project.max-shm-ids=(priv,32768,deny)
 246 project.max-sem-ids=(priv,4096,deny)
 247 project.max-msg-ids=(priv,4096,deny)
 248 </pre><p>
 249        </p><p>
 250         Additionally, if you are running <span class="productname">PostgreSQL</span>
 251         inside a zone, you may need to raise the zone resource usage
 252         limits as well.  See "Chapter2:  Projects and Tasks" in the
 253         <em class="citetitle">System Administrator's Guide</em> for more
 254         information on <code class="literal">projects</code> and <code class="command">prctl</code>.
 255        </p></dd></dl></div></div><div class="sect2" id="SYSTEMD-REMOVEIPC"><div class="titlepage"><div><div><h3 class="title">18.4.2. systemd RemoveIPC <a href="#SYSTEMD-REMOVEIPC" class="id_link">#</a></h3></div></div></div><a id="id-1.6.5.7.4.2" class="indexterm"></a><p>
 256     If <span class="productname">systemd</span> is in use, some care must be taken
 257     that IPC resources (including shared memory) are not prematurely
 258     removed by the operating system.  This is especially of concern when
 259     installing PostgreSQL from source.  Users of distribution packages of
 260     PostgreSQL are less likely to be affected, as
 261     the <code class="literal">postgres</code> user is then normally created as a system
 262     user.
 263    </p><p>
 264     The setting <code class="literal">RemoveIPC</code>
 265     in <code class="filename">logind.conf</code> controls whether IPC objects are
 266     removed when a user fully logs out.  System users are exempt.  This
 267     setting defaults to on in stock <span class="productname">systemd</span>, but
 268     some operating system distributions default it to off.
 269    </p><p>
 270     A typical observed effect when this setting is on is that shared memory
 271     objects used for parallel query execution are removed at apparently random
 272     times, leading to errors and warnings while attempting to open and remove
 273     them, like
 274 </p><pre class="screen">
 275 WARNING:  could not remove shared memory segment "/PostgreSQL.1450751626": No such file or directory
 276 </pre><p>
 277     Different types of IPC objects (shared memory vs. semaphores, System V
 278     vs. POSIX) are treated slightly differently
 279     by <span class="productname">systemd</span>, so one might observe that some IPC
 280     resources are not removed in the same way as others.  But it is not
 281     advisable to rely on these subtle differences.
 282    </p><p>
 283     A <span class="quote">“<span class="quote">user logging out</span>”</span> might happen as part of a maintenance
 284     job or manually when an administrator logs in as
 285     the <code class="literal">postgres</code> user or something similar, so it is hard
 286     to prevent in general.
 287    </p><p>
 288     What is a <span class="quote">“<span class="quote">system user</span>”</span> is determined
 289     at <span class="productname">systemd</span> compile time from
 290     the <code class="symbol">SYS_UID_MAX</code> setting
 291     in <code class="filename">/etc/login.defs</code>.
 292    </p><p>
 293     Packaging and deployment scripts should be careful to create
 294     the <code class="literal">postgres</code> user as a system user by
 295     using <code class="literal">useradd -r</code>, <code class="literal">adduser --system</code>,
 296     or equivalent.
 297    </p><p>
 298     Alternatively, if the user account was created incorrectly or cannot be
 299     changed, it is recommended to set
 300 </p><pre class="programlisting">
 301 RemoveIPC=no
 302 </pre><p>
 303     in <code class="filename">/etc/systemd/logind.conf</code> or another appropriate
 304     configuration file.
 305    </p><div class="caution"><h3 class="title">Caution</h3><p>
 306      At least one of these two things has to be ensured, or the PostgreSQL
 307      server will be very unreliable.
 308     </p></div></div><div class="sect2" id="KERNEL-RESOURCES-LIMITS"><div class="titlepage"><div><div><h3 class="title">18.4.3. Resource Limits <a href="#KERNEL-RESOURCES-LIMITS" class="id_link">#</a></h3></div></div></div><p>
 309     Unix-like operating systems enforce various kinds of resource limits
 310     that might interfere with the operation of your
 311     <span class="productname">PostgreSQL</span> server. Of particular
 312     importance are limits on the number of processes per user, the
 313     number of open files per process, and the amount of memory available
 314     to each process. Each of these have a <span class="quote">“<span class="quote">hard</span>”</span> and a
 315     <span class="quote">“<span class="quote">soft</span>”</span> limit. The soft limit is what actually counts
 316     but it can be changed by the user up to the hard limit. The hard
 317     limit can only be changed by the root user. The system call
 318     <code class="function">setrlimit</code> is responsible for setting these
 319     parameters. The shell's built-in command <code class="command">ulimit</code>
 320     (Bourne shells) or <code class="command">limit</code> (<span class="application">csh</span>) is
 321     used to control the resource limits from the command line. On
 322     BSD-derived systems the file <code class="filename">/etc/login.conf</code>
 323     controls the various resource limits set during login. See the
 324     operating system documentation for details. The relevant
 325     parameters are <code class="varname">maxproc</code>,
 326     <code class="varname">openfiles</code>, and <code class="varname">datasize</code>. For
 327     example:
 328 </p><pre class="programlisting">
 329 default:\
 330 ...
 331         :datasize-cur=256M:\
 332         :maxproc-cur=256:\
 333         :openfiles-cur=256:\
 334 ...
 335 </pre><p>
 336     (<code class="literal">-cur</code> is the soft limit.  Append
 337     <code class="literal">-max</code> to set the hard limit.)
 338    </p><p>
 339     Kernels can also have system-wide limits on some resources.
 340     </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
 341       On <span class="productname">Linux</span> the kernel parameter
 342       <code class="varname">fs.file-max</code> determines the maximum number of open
 343       files that the kernel will support.  It can be changed with
 344       <code class="literal">sysctl -w fs.file-max=<em class="replaceable"><code>N</code></em></code>.
 345       To make the setting persist across reboots, add an assignment
 346       in <code class="filename">/etc/sysctl.conf</code>.
 347       The maximum limit of files per process is fixed at the time the
 348       kernel is compiled; see
 349       <code class="filename">/usr/src/linux/Documentation/proc.txt</code> for
 350       more information.
 351       </p></li></ul></div><p>
 352    </p><p>
 353     The <span class="productname">PostgreSQL</span> server uses one process
 354     per connection so you should provide for at least as many processes
 355     as allowed connections, in addition to what you need for the rest
 356     of your system.  This is usually not a problem but if you run
 357     several servers on one machine things might get tight.
 358    </p><p>
 359     The factory default limit on open files is often set to
 360     <span class="quote">“<span class="quote">socially friendly</span>”</span> values that allow many users to
 361     coexist on a machine without using an inappropriate fraction of
 362     the system resources.  If you run many servers on a machine this
 363     is perhaps what you want, but on dedicated servers you might want to
 364     raise this limit.
 365    </p><p>
 366     On the other side of the coin, some systems allow individual
 367     processes to open large numbers of files; if more than a few
 368     processes do so then the system-wide limit can easily be exceeded.
 369     If you find this happening, and you do not want to alter the
 370     system-wide limit, you can set <span class="productname">PostgreSQL</span>'s <a class="xref" href="runtime-config-resource.html#GUC-MAX-FILES-PER-PROCESS">max_files_per_process</a> configuration parameter to
 371     limit the consumption of open files.
 372    </p><p>
 373     Another kernel limit that may be of concern when supporting large
 374     numbers of client connections is the maximum socket connection queue
 375     length.  If more than that many connection requests arrive within a very
 376     short period, some may get rejected before the <span class="productname">PostgreSQL</span> server can service
 377     the requests, with those clients receiving unhelpful connection failure
 378     errors such as <span class="quote">“<span class="quote">Resource temporarily unavailable</span>”</span> or
 379     <span class="quote">“<span class="quote">Connection refused</span>”</span>.  The default queue length limit is 128
 380     on many platforms.  To raise it, adjust the appropriate kernel parameter
 381     via <span class="application">sysctl</span>, then restart the <span class="productname">PostgreSQL</span> server.
 382     The parameter is variously named <code class="varname">net.core.somaxconn</code>
 383     on Linux, <code class="varname">kern.ipc.soacceptqueue</code> on newer FreeBSD,
 384     and <code class="varname">kern.ipc.somaxconn</code> on macOS and other BSD
 385     variants.
 386    </p></div><div class="sect2" id="LINUX-MEMORY-OVERCOMMIT"><div class="titlepage"><div><div><h3 class="title">18.4.4. Linux Memory Overcommit <a href="#LINUX-MEMORY-OVERCOMMIT" class="id_link">#</a></h3></div></div></div><a id="id-1.6.5.7.6.2" class="indexterm"></a><a id="id-1.6.5.7.6.3" class="indexterm"></a><a id="id-1.6.5.7.6.4" class="indexterm"></a><p>
 387     The default virtual memory behavior on Linux is not
 388     optimal for <span class="productname">PostgreSQL</span>. Because of the
 389     way that the kernel implements memory overcommit, the kernel might
 390     terminate the <span class="productname">PostgreSQL</span> postmaster (the
 391     supervisor server process) if the memory demands of either
 392     <span class="productname">PostgreSQL</span> or another process cause the
 393     system to run out of virtual memory.
 394    </p><p>
 395     If this happens, you will see a kernel message that looks like
 396     this (consult your system documentation and configuration on where
 397     to look for such a message):
 398 </p><pre class="programlisting">
 399 Out of Memory: Killed process 12345 (postgres).
 400 </pre><p>
 401     This indicates that the <code class="filename">postgres</code> process
 402     has been terminated due to memory pressure.
 403     Although existing database connections will continue to function
 404     normally, no new connections will be accepted.  To recover,
 405     <span class="productname">PostgreSQL</span> will need to be restarted.
 406    </p><p>
 407     One way to avoid this problem is to run
 408     <span class="productname">PostgreSQL</span> on a machine where you can
 409     be sure that other processes will not run the machine out of
 410     memory.  If memory is tight, increasing the swap space of the
 411     operating system can help avoid the problem, because the
 412     out-of-memory (OOM) killer is invoked only when physical memory and
 413     swap space are exhausted.
 414    </p><p>
 415     If <span class="productname">PostgreSQL</span> itself is the cause of the
 416     system running out of memory, you can avoid the problem by changing
 417     your configuration.  In some cases, it may help to lower memory-related
 418     configuration parameters, particularly
 419     <a class="link" href="runtime-config-resource.html#GUC-SHARED-BUFFERS"><code class="varname">shared_buffers</code></a>,
 420     <a class="link" href="runtime-config-resource.html#GUC-WORK-MEM"><code class="varname">work_mem</code></a>, and
 421     <a class="link" href="runtime-config-resource.html#GUC-HASH-MEM-MULTIPLIER"><code class="varname">hash_mem_multiplier</code></a>.
 422     In other cases, the problem may be caused by allowing too many
 423     connections to the database server itself.  In many cases, it may
 424     be better to reduce
 425     <a class="link" href="runtime-config-connection.html#GUC-MAX-CONNECTIONS"><code class="varname">max_connections</code></a>
 426     and instead make use of external connection-pooling software.
 427    </p><p>
 428     It is possible to modify the
 429     kernel's behavior so that it will not <span class="quote">“<span class="quote">overcommit</span>”</span> memory.
 430     Although this setting will not prevent the <a class="ulink" href="https://lwn.net/Articles/104179/" target="_top">OOM killer</a> from being invoked
 431     altogether, it will lower the chances significantly and will therefore
 432     lead to more robust system behavior.  This is done by selecting strict
 433     overcommit mode via <code class="command">sysctl</code>:
 434 </p><pre class="programlisting">
 435 sysctl -w vm.overcommit_memory=2
 436 </pre><p>
 437     or placing an equivalent entry in <code class="filename">/etc/sysctl.conf</code>.
 438     You might also wish to modify the related setting
 439     <code class="varname">vm.overcommit_ratio</code>.  For details see the kernel documentation
 440     file <a class="ulink" href="https://www.kernel.org/doc/Documentation/vm/overcommit-accounting" target="_top">https://www.kernel.org/doc/Documentation/vm/overcommit-accounting</a>.
 441    </p><p>
 442     Another approach, which can be used with or without altering
 443     <code class="varname">vm.overcommit_memory</code>, is to set the process-specific
 444     <em class="firstterm">OOM score adjustment</em> value for the postmaster process to
 445     <code class="literal">-1000</code>, thereby guaranteeing it will not be targeted by the OOM
 446     killer.  The simplest way to do this is to execute
 447 </p><pre class="programlisting">
 448 echo -1000 &gt; /proc/self/oom_score_adj
 449 </pre><p>
 450     in the <span class="productname">PostgreSQL</span> startup script just before
 451     invoking <code class="filename">postgres</code>.
 452     Note that this action must be done as root, or it will have no effect;
 453     so a root-owned startup script is the easiest place to do it.  If you
 454     do this, you should also set these environment variables in the startup
 455     script before invoking <code class="filename">postgres</code>:
 456 </p><pre class="programlisting">
 457 export PG_OOM_ADJUST_FILE=/proc/self/oom_score_adj
 458 export PG_OOM_ADJUST_VALUE=0
 459 </pre><p>
 460     These settings will cause postmaster child processes to run with the
 461     normal OOM score adjustment of zero, so that the OOM killer can still
 462     target them at need.  You could use some other value for
 463     <code class="envar">PG_OOM_ADJUST_VALUE</code> if you want the child processes to run
 464     with some other OOM score adjustment.  (<code class="envar">PG_OOM_ADJUST_VALUE</code>
 465     can also be omitted, in which case it defaults to zero.)  If you do not
 466     set <code class="envar">PG_OOM_ADJUST_FILE</code>, the child processes will run with the
 467     same OOM score adjustment as the postmaster, which is unwise since the
 468     whole point is to ensure that the postmaster has a preferential setting.
 469    </p></div><div class="sect2" id="LINUX-HUGE-PAGES"><div class="titlepage"><div><div><h3 class="title">18.4.5. Linux Huge Pages <a href="#LINUX-HUGE-PAGES" class="id_link">#</a></h3></div></div></div><p>
 470     Using huge pages reduces overhead when using large contiguous chunks of
 471     memory, as <span class="productname">PostgreSQL</span> does, particularly when
 472     using large values of <a class="xref" href="runtime-config-resource.html#GUC-SHARED-BUFFERS">shared_buffers</a>.  To use this
 473     feature in <span class="productname">PostgreSQL</span> you need a kernel
 474     with <code class="varname">CONFIG_HUGETLBFS=y</code> and
 475     <code class="varname">CONFIG_HUGETLB_PAGE=y</code>. You will also have to configure
 476     the operating system to provide enough huge pages of the desired size.
 477     The runtime-computed parameter
 478     <a class="xref" href="runtime-config-preset.html#GUC-SHARED-MEMORY-SIZE-IN-HUGE-PAGES">shared_memory_size_in_huge_pages</a> reports the number
 479     of huge pages required.  This parameter can be viewed before starting the
 480     server with a <code class="command">postgres</code> command like:
 481 </p><pre class="programlisting">
 482 $ <strong class="userinput"><code>postgres -D $PGDATA -C shared_memory_size_in_huge_pages</code></strong>
 483 3170
 484 $ <strong class="userinput"><code>grep ^Hugepagesize /proc/meminfo</code></strong>
 485 Hugepagesize:       2048 kB
 486 $ <strong class="userinput"><code>ls /sys/kernel/mm/hugepages</code></strong>
 487 hugepages-1048576kB  hugepages-2048kB
 488 </pre><p>
 489
 490      In this example the default is 2MB, but you can also explicitly request
 491      either 2MB or 1GB with <a class="xref" href="runtime-config-resource.html#GUC-HUGE-PAGE-SIZE">huge_page_size</a> to adapt
 492      the number of pages calculated by
 493      <code class="varname">shared_memory_size_in_huge_pages</code>.
 494
 495      While we need at least <code class="literal">3170</code> huge pages in this example,
 496      a larger setting would be appropriate if other programs on the machine
 497      also need huge pages.
 498      We can set this with:
 499 </p><pre class="programlisting">
 500 # <strong class="userinput"><code>sysctl -w vm.nr_hugepages=3170</code></strong>
 501 </pre><p>
 502      Don't forget to add this setting to <code class="filename">/etc/sysctl.conf</code>
 503      so that it is reapplied after reboots.  For non-default huge page sizes,
 504      we can instead use:
 505 </p><pre class="programlisting">
 506 # <strong class="userinput"><code>echo 3170 &gt; /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages</code></strong>
 507 </pre><p>
 508     It is also possible to provide these settings at boot time using
 509     kernel parameters such as <code class="literal">hugepagesz=2M hugepages=3170</code>.
 510    </p><p>
 511     Sometimes the kernel is not able to allocate the desired number of huge
 512     pages immediately due to fragmentation, so it might be necessary
 513     to repeat the command or to reboot.  (Immediately after a reboot, most of
 514     the machine's memory should be available to convert into huge pages.)
 515     To verify the huge page allocation situation for a given size, use:
 516 </p><pre class="programlisting">
 517 $ <strong class="userinput"><code>cat /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages</code></strong>
 518 </pre><p>
 519    </p><p>
 520     It may also be necessary to give the database server's operating system
 521     user permission to use huge pages by setting
 522     <code class="varname">vm.hugetlb_shm_group</code> via <span class="application">sysctl</span>, and/or
 523     give permission to lock memory with <code class="command">ulimit -l</code>.
 524    </p><p>
 525     The default behavior for huge pages in
 526     <span class="productname">PostgreSQL</span> is to use them when possible, with
 527     the system's default huge page size, and
 528     to fall back to normal pages on failure. To enforce the use of huge
 529     pages, you can set <a class="xref" href="runtime-config-resource.html#GUC-HUGE-PAGES">huge_pages</a>
 530     to <code class="literal">on</code> in <code class="filename">postgresql.conf</code>.
 531     Note that with this setting <span class="productname">PostgreSQL</span> will fail to
 532     start if not enough huge pages are available.
 533    </p><p>
 534     For a detailed description of the <span class="productname">Linux</span> huge
 535     pages feature have a look
 536     at <a class="ulink" href="https://www.kernel.org/doc/Documentation/vm/hugetlbpage.txt" target="_top">https://www.kernel.org/doc/Documentation/vm/hugetlbpage.txt</a>.
 537    </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="server-start.html" title="18.3. Starting the Database Server">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="runtime.html" title="Chapter 18. Server Setup and Operation">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="server-shutdown.html" title="18.5. Shutting Down the Server">Next</a></td></tr><tr><td width="40%" align="left" valign="top">18.3. Starting the Database Server </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 18.5. Shutting Down the Server</td></tr></table></div></body></html>