Doc: mention packager-supplied tools for server start/stop, initdb, etc.

The majority of our audience is probably using a pre-packaged Postgres
build rather than raw sources.  For them, much of runtime.sgml is not
too relevant, and they should be reading the packager's docs instead.
Add some notes pointing that way in appropriate places.

Text by me; thanks to Daniel Gustafsson for review and discussion,
and to Laurenz Albe for an earlier version.

Discussion: https://postgr.es/m/159430831443.16535.11360317280100947016@wrigleys.postgresql.org

diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 6cda39f3abfc9dda42437ad3d4607f1c84ca0c16..f5842319358b534e9d75928da97aaad4a2f71402 100644 (file)
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -4,10 +4,22 @@
  Server Setup and Operation
 
  
-  This chapter discusses how to set up and run the database server
+  This chapter discusses how to set up and run the database server,
   and its interactions with the operating system.
  
 
+ 
+  The directions in this chapter assume that you are working with
+  plain PostgreSQL without any additional
+  infrastructure, for example a copy that you built from source
+  according to the directions in the preceding chapters.
+  If you are working with a pre-packaged or vendor-supplied
+  version of PostgreSQL, it is likely that
+  the packager has made special provisions for installing and starting
+  the database server according to your system's conventions.
+  Consult the package-level documentation for details.
+ 
+
  
   The <productname>PostgreSQL</productname> User Account
 
@@ -21,9 +33,15 @@
    separate user account. This user account should only own the data
    that is managed by the server, and should not be shared with other
    daemons. (For example, using the user nobody is a bad
-   idea.) It is not advisable to install executables owned by this
-   user because compromised systems could then modify their own
-   binaries.
+   idea.) In particular, it is advisable that this user account not own
+   the PostgreSQL executable files, to ensure
+   that a compromised server process could not modify those executables.
+  
+
+  
+   Pre-packaged versions of PostgreSQL will
+   typically create a suitable user account automatically during
+   package installation.
   
 
   
@@ -71,11 +89,26 @@
    completely up to you where you choose to store your data.  There is no
    default, although locations such as
    /usr/local/pgsql/data or
-   /var/lib/pgsql/data are popular. To initialize a
-   database cluster, use the command 
-   linkend="app-initdb"/>,initdb which is
-   installed with PostgreSQL. The desired
-   file system location of your database cluster is indicated by the
+   /var/lib/pgsql/data are popular.
+   The data directory must be initialized before being used, using the program
+   initdb
+   which is installed with PostgreSQL.
+  
+
+  
+   If you are using a pre-packaged version
+   of PostgreSQL, it may well have a specific
+   convention for where to place the data directory, and it may also
+   provide a script for creating the data directory.  In that case you
+   should use that script in preference to
+   running initdb directly.
+   Consult the package-level documentation for details.
+  
+
+  
+   To initialize a database cluster manually,
+   run initdb and specify the desired
+   file system location of the database cluster with the
    -D option, for example:
 
 $ initdb -D /usr/local/pgsql/data
@@ -309,10 +342,22 @@ postgres$ initdb -D /usr/local/pgsql/data
    Before anyone can access the database, you must start the database
    server. The database server program is called
    postgres.postgres
-   The postgres program must know where to
-   find the data it is supposed to use. This is done with the
-   -D option. Thus, the simplest way to start the
-   server is:
+  
+
+  
+   If you are using a pre-packaged version
+   of PostgreSQL, it almost certainly includes
+   provisions for running the server as a background task according to the
+   conventions of your operating system.  Using the package's
+   infrastructure to start the server will be much less work than figuring
+   out how to do this yourself.  Consult the package-level documentation
+   for details.
+  
+
+  
+   The bare-bones way to start the server manually is just to invoke
+   postgres directly, specifying the location of the
+   data directory with the -D option, for example:
 
 $ postgres -D /usr/local/pgsql/data
 
@@ -364,7 +409,7 @@ pg_ctl start -l logfile
      starting the server during
    
    Autostart scripts are operating-system-specific.
-   There are a few distributed with
+   There are a few example scripts distributed with
    PostgreSQL in the
    contrib/start-scripts directory. Installing one will require
    root privileges.
@@ -1481,9 +1526,23 @@ $ cat /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages
   
 
   
-   There are several ways to shut down the database server. You control
-   the type of shutdown by sending different signals to the supervisor
+   There are several ways to shut down the database server.
+   Under the hood, they all reduce to sending a signal to the supervisor
    postgres process.
+  
+
+  
+   If you are using a pre-packaged version
+   of PostgreSQL, and you used its provisions
+   for starting the server, then you should also use its provisions for
+   stopping the server.  Consult the package-level documentation for
+   details.
+  
+
+  
+   When managing the server directly, you can control the type of shutdown
+   by sending different signals to the postgres
+   process:
 
    
     
@@ -1620,6 +1679,10 @@ $ kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`
    is to dump and reload the database, though this can be slow.  A
    faster method is .  Replication methods are
    also available, as discussed below.
+   (If you are using a pre-packaged version
+   of PostgreSQL, it may provide scripts to
+   assist with major version upgrades.  Consult the package-level
+   documentation for details.)