summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorPavel Raiskup <praiskup@redhat.com>2015-03-04 16:00:31 +0100
committerPavel Raiskup <praiskup@redhat.com>2015-03-04 16:06:45 +0100
commit834c0e34d7828f96550c7a7bbb94f3dcaacd2029 (patch)
tree853ae4201f0e4a9f261352549b6ef359d0d24869
parentf6c4b5674f9ea68634fa13197405a89fde64985f (diff)
downloadpostgresql-setup-834c0e34d7828f96550c7a7bbb94f3dcaacd2029.zip
postgresql-setup-834c0e34d7828f96550c7a7bbb94f3dcaacd2029.tar.gz
postgresql-setup-834c0e34d7828f96550c7a7bbb94f3dcaacd2029.tar.xz
README.rpm-dist: use docbook2txt for generation
The benefit is that sgml format we write does not need to be kept formated precisely. The output format still needs some "style" fixes, but now docbook2txt is able to generates correct text-file README.rpm-dist without problems on RHEL 5.10+. * .gitignore: Added all intermediate files of README file. * Makefile.am: Generated README file is firstly filtered through $(SED_RULES), then macros are expanded by m4 and then docbook2txt is called. * README: Document subset of dependencies. * README.rpm-dist.in: Move to ... * README.rpm-dist.template: ... here, with docbook transformation. * TODO: Document we should should work docbook docs. * configure.ac: AC_SUBST also WANT_SYSVINIT.
-rw-r--r--.gitignore2
-rw-r--r--Makefile.am31
-rw-r--r--README3
-rw-r--r--README.rpm-dist.in359
-rw-r--r--README.rpm-dist.template568
-rw-r--r--TODO2
-rw-r--r--configure.ac5
7 files changed, 604 insertions, 366 deletions
diff --git a/.gitignore b/.gitignore
index 19f4432..a72b090 100644
--- a/.gitignore
+++ b/.gitignore
@@ -22,7 +22,7 @@ postgresql*-ctl
postgresql*.service
/postgresql*-setup
postgresql*-setup.1
-README.rpm-dist
+README.rpm-dist*
testsuite
testsuite.dir/
initdb
diff --git a/Makefile.am b/Makefile.am
index 3f64a38..68717c9 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -15,6 +15,12 @@ serviceat_in = postgresql.service.in
initscript = $(NAME_SERVICE)
initscript_in = postgresql.init.in
+readme_dist = README.rpm-dist
+readme_dist_db = README.rpm-dist.sgml
+readme_dist_m4 = README.rpm-dist.m4
+readme_dist_sed = README.rpm-dist.sed
+readme_template = README.rpm-dist.template
+
EXTRA_DIST =
GENERATED_FILES =
CLEANFILES =
@@ -36,7 +42,7 @@ systemdunits_DATA = $(service) $(serviceat)
legacyscripts_SCRIPTS = initdb upgrade
endif
-pgdoc_DATA = $(README_DIST_BASENAME)
+pgdoc_DATA = $(readme_dist)
noinst_DATA = $(TEST_GEN_FILES_LIST)
@@ -69,12 +75,26 @@ $(service): $(service_in) $(c_s)
-e 's|@PGDATA_ENVIRONMENT[@]|Environment=PGDATA=$(PGDATADIR)|' \
$< > $@
-$(README_DIST_BASENAME): $(README_DIST_BASENAME).in $(c_s)
+$(readme_dist_sed): $(readme_template) $(c_s)
$(INSTANTIATE)
+$(readme_dist_m4): $(readme_dist_sed)
+ $(INSTANTIATE_CONV) && \
+ m4 -P < $< > $@
+
+$(readme_dist_db): $(readme_dist_m4)
+ $(INSTANTIATE_CONV) && \
+ $(SED_CALL) < $(readme_dist_m4) | m4 -P > $(readme_dist_db)
+
+$(readme_dist): $(readme_dist_db) style.dsl
+ $(INSTANTIATE_CONV) && docbook2txt -d style.dsl $(readme_dist_db) >/dev/null && \
+ mv -f $(readme_dist).txt $(readme_dist)
+
EXTRA_DIST += \
$(srcdir)/*.in \
- $(srcdir)/etc/postgresql-setup/upgrade/postgresql.conf
+ $(srcdir)/etc/postgresql-setup/upgrade/postgresql.conf \
+ $(readme_template) \
+ style.dsl
include $(srcdir)/share/postgresql-setup/Makefile.inc
@@ -85,7 +105,10 @@ GENERATED_FILES += \
$(pkgsysconf_DATA) \
$(systemdunits_DATA) \
$(initscripts_DATA) \
- $(legacyscripts_SCRIPTS)
+ $(legacyscripts_SCRIPTS) \
+ $(readme_dist_m4) \
+ $(readme_dist_sed) \
+ $(readme_dist_db)
CLEANFILES += $(GENERATED_FILES) $(TEST_GEN_FILES_LIST)
diff --git a/README b/README
index 8eda5e6..49ace1a 100644
--- a/README
+++ b/README
@@ -2,4 +2,5 @@
postgresql-setup
----------------
-TODO
+BuildRequires:
+ - m4, docbook-utils, help2man
diff --git a/README.rpm-dist.in b/README.rpm-dist.in
deleted file mode 100644
index 8fabcc2..0000000
--- a/README.rpm-dist.in
+++ /dev/null
@@ -1,359 +0,0 @@
-README.rpm-dist
------------------------------------------------------------------------------
-Version @PGMAJORVERSION@, for the PostgreSQL @PGMAJORVERSION@ RPM set.
-Devrim Gündüz <devrim@gunduz.org>
------------------------------------------------------------------------------
-
-Contents:
- 1.) Introduction and QuickStart
- 2.) Upgrading an installation
- 3.) PostgreSQL RPM packages and rationale
- 4.) Starting multiple postmasters
- 5.) Regression Testing
- 6.) Starting postmaster automatically on startup
- 7.) Grand Unified Configuration(GUC) File
- 8.) Logging set up
- 9.) Rebuilding from the source RPM
-10.) Contrib files
-11.) Further Information Resource
-
-INTRODUCTION
------------------------------------------------------------------------------
-This document exists to explain the layout of the RPMs for PostgreSQL, to
-describe various RPM specifics, and to document special features found
-in the RPMset.
-
-This document is written to be applicable to version @PGMAJORVERSION@ of PostgreSQL,
-which is the current version of the RPMs as of this writing. More to the
-point, versions prior to @PGMAJORVERSION@ are not documented here.
-
-This document is intended for use only with the RPMs supplied in Red Hat
-Enterprise Linux, CentOS and Fedora. Note that there are also "PGDG"
-RPMs available directly from the upstream PostgreSQL project. Those are
-slightly different.
-
-QUICKSTART (note that this requires @NAME_PACKAGE@-server installed)
------------------------------------------------------------------------------
-For a fresh installation, you will need to initialize the cluster first. Run:
-
- @NAME_BINARYBASE@-setup --initdb
-
-as root, and it will prepare a new database cluster for you. Then you will
-need to start PostgreSQL. Again as root, run:
-
- systemctl start @NAME_SERVICE@.service
-
-This command will start a postmaster that will listen on localhost and Unix
-socket 5432 only. Edit @PGDATADIR@/postgresql.conf and pg_hba.conf
-if you want to allow remote access -- see the section on Grand Unified
-Configuration.
-
-You will probably also want to do
-
- systemctl enable @NAME_SERVICE@.service
-
-so that the postmaster is automatically started during future reboots.
-
-The file /var/lib/pgsql/.bash_profile is packaged to help with the
-setting of environment variables. You may edit this file, and it won't be
-overwritten during an upgrade. However, enhancements and bugfixes may
-be added to this file, so be sure to check .bash_profile.rpmnew after
-upgrading.
-
-The user 'postgres' is created during installation of the server subpackage.
-This user by default is UID and GID 26. The user has the default shell set to
-bash, and the home directory set to @POSTGRES_HOMEDIR@. This user also has no
-default password, so the only way to become this user is to su to it from root.
-If you want to be able to su to it from a non-root account or log in directly
-as 'postgres' you will need to set a password using passwd.
-
-UPGRADING AN INSTALLATION
------------------------------------------------------------------------------
-For a minor-version upgrade (such as 9.3.1 to 9.3.4; last number changes), just
-install the new RPMs; there's usually nothing more to it than that. Upgrading
-across a major release of PostgreSQL (for example, from 9.2.x to 9.3.x) requires
-more effort.
-
-If you are upgrading across more than one major release of PostgreSQL
-(for example, from 8.3.x to 9.0.x), you will need to follow the "traditional"
-dump and reload process to bring your data into the new version. That is:
-*before* upgrading, run pg_dumpall to extract all your data into a SQL file.
-Shut down the old postmaster, upgrade to the new version RPMs, perform initdb,
-and run the dump file through psql to restore your data.
-
-In some major releases, the RPMs also support in-place upgrade from the
-immediately previous major release. Currently, you can upgrade in-place
-from @PREVMAJORVERSION@.x to @PGMAJORVERSION@.x. This is much faster than a dump and reload.
-To do an in-place upgrade:
-* shut down the old postmaster ("systemctl stop @NAME_SERVICE@.service")
-* optionally make a backup of @PGDATADIR@ (recommended!)
-* install the new version's RPMs (install all the ones you had before,
- plus @NAME_PACKAGE@-upgrade)
-* as root, run "@NAME_BINARYBASE@-setup --upgrade"
-* update the configuration files @PGDATADIR@/*.conf with any
- customizations you had before (your old configuration files are in
- @POSTGRES_HOMEDIR@/data-old/)
-* as root, run "systemctl start @NAME_SERVICE@.service"
-* the @NAME_PACKAGE@-upgrade package can be removed after the update is complete,
- as can @POSTGRES_HOMEDIR@/data-old/
-
-NOTE: The in-place upgrade process is new and relatively poorly tested,
-so if your data is critical it's a really good idea to make a tarball
-backup of @PGDATADIR@ before running the upgrade. This will
-let you get back to where you were in case of disaster.
-
-POSTGRESQL RPM PACKAGES AND RATIONALE.
------------------------------------------------------------------------------
-PostgreSQL is split up into multiple packages so that users can 'pick and
-choose' what pieces are needed, and what dependencies are required.
-
-The RPMset is packaged in the following subpackages:
-
-@NAME_PACKAGE@: Key client programs and basic documentation
-@NAME_PACKAGE@-libs: Client shared libraries
-@NAME_PACKAGE@-server: Server executables and data files
-@NAME_PACKAGE@-devel: Development libraries and include files
-@NAME_PACKAGE@-test: The regression tests and associated files
-@NAME_PACKAGE@-upgrade: Support files for upgrading from previous major version
-@NAME_PACKAGE@-docs: Full documentation in HTML and PDF, the tutorial files
-@NAME_PACKAGE@-contrib: Add-on loadable modules and programs
-@NAME_PACKAGE@-plperl: PL/Perl procedural language
-@NAME_PACKAGE@-plpython: PL/Python procedural language (for Python 2)
-@NAME_PACKAGE@-plpython3: PL/Python procedural language (for Python 3)
-@NAME_PACKAGE@-pltcl: PL/Tcl procedural language
-
-You have to install @NAME_PACKAGE@ and @NAME_PACKAGE@-libs to do anything.
-@NAME_PACKAGE@-server is needed unless you only plan to use the clients to work with
-a remote PostgreSQL server. The others are optional.
-
-Note that there are no @NAME_PACKAGE@-perl, @NAME_PACKAGE@-jdbc, @NAME_PACKAGE@-odbc,
-@NAME_PACKAGE@-python, @NAME_PACKAGE@-tcl, or @NAME_PACKAGE@-tk subpackages any longer.
-Those programs have been split off into separate source distributions.
-They are still available, but in some cases not under those RPM names.
-
-RPM FILE LOCATIONS.
------------------------------------------------------------------------------
-To be in compliance with the Linux FHS, the PostgreSQL RPMs install files in
-a manner not consistent with most of the PostgreSQL documentation. According
-to the standard PostgreSQL documentation, PostgreSQL is installed under the
-directory /usr/local/pgsql, with executables, source, and data existing in
-various subdirectories.
-
-Different distributions have different ideas of some of these file locations.
-In particular, the documentation directory can be /usr/doc, /usr/doc/packages,
-/usr/share/doc, /usr/share/doc/packages, or some other similar path.
-
-However, this installation (which usually matches the Red Hat / CentOS / Fedora
-RPM's) install the files like this:
-
-Executables: @bindir@
-Libraries: @libdir@
-Documentation: /usr/share/doc/postgresql/html
-PDF documentation: /usr/share/doc/postgresql-docs
-Contrib documentation: /usr/share/doc/postgresql-contrib
-Source: not installed
-Data: /var/lib/pgsql/data
-Backup area: /var/lib/pgsql/backups
-Templates: /usr/share/pgsql
-Procedural Languages: @libdir@/pgsql
-Development Headers: /usr/include/pgsql
-Other shared data: /usr/share/pgsql
-Regression tests: @libdir@/pgsql/test/regress (in the -test package)
-
-While it may seem gratuitous to place these files in different locations, the
-FHS requires it -- distributions should not ever touch /usr/local. It may
-also seem like more work to keep track of where everything is -- but, that's
-the beauty of RPM -- you don't have to keep track of the files, RPM does it
-for you.
-
-These RPMs are designed to be LSB-compliant -- if you find this not to be the
-case, please let us know by way of the pgsql-pkg-yum@postgresql.org
-mailing list.
-
-MULTIPLE POSTMASTERS
--------------------------------------------------------------------------------
-The postgresql-server package contains a systemd "unit" files @NAME_SERVICE@.service
-and @NAME_SERVICE@@.service. The first file is used solely to start the default
-PostgreSQL server. The second one is designed to allow instantiating
-additional PostgreSQL servers on same machine.
-
-As an example, let us create a secondary PostgreSQL service called, creatively
-enough, 'postgresql@secondary'. Here are the steps:
-
-1) Run the following command to create the necessary configuration and
- to initialize the new database cluster:
- @NAME_BINARYBASE@-setup --initdb \
- --unit postgresql@secondary \
- --new-systemd-unit \
- --datadir /path/to/data/directory \
- --port NNNN
- Replace the "/path/to/data/directory" path and NNNN port with
- appropriate settings that don't conflict with any other PostgreSQL
- setup. Make sure that the parent directory of specified path has
- appropriate ownership and permissions. Note the SELinux issues
- mentioned below.
-
-2) Edit postgresql.conf in the target 'datadir' directory to change
- settings as needed.
-
-3) Start the new service with this command:
- 'systemctl start @NAME_SERVICE@@secondary.service'
- You will probably also want to run the command
- 'systemctl enable @NAME_SERVICE@@secondary.service'
- so that the new service is automatically started in future reboots.
-
-When doing a major-version upgrade of a secondary service, add the service name
-to the @NAME_BINARYBASE@-setup command, for example:
- '@NAME_BINARYBASE@-setup --upgrade --unit @NAME_SERVICE@@secondary'
-This will let @NAME_BINARYBASE@-setup find the correct data directory from the proper
-configuration file.
-
-If you are running SELinux in enforcing mode (which is highly recommended,
-particularly for network-exposed services like PostgreSQL) you will need to
-adjust SELinux policy to allow the secondary server to use non-default PGPORT
-or PGDATA settings. To allow use of a non-default port, say 5433, do this as
-root:
- semanage port -a -t postgresql_port_t -p tcp 5433
-To allow use of a non-default data directory, say /special/pgdata, do:
- semanage fcontext -a -t postgresql_db_t "/special/pgdata(/.*)?"
-If you already created the directory, follow that with:
- restorecon -R /special/pgdata
-These settings are persistent across reboots. For more information
-see "man semanage".
-
-REGRESSION TESTING
--------------------------------------------------------------------------------
-If you install the @NAME_PACKAGE@-test RPM then you can run the PostgreSQL
-regression tests. These tests stress your database installation and produce
-results that give you assurances that the installation is complete, and that
-your database machine is up to the task.
-
-To run the regression tests under the RPM installation, make sure that the
-PostgreSQL server has been started (if not, su to root and do "systemctl start
-@NAME_SERVICE@.service"), su to postgres, cd to @libdir@/pgsql/test/regress and
-execute "make check".
-This command will start the regression tests and will both show the
-results to the screen and store the results in the file regress.out.
-
-If any tests fail, see the file regression.diffs in that directory for details,
-and read the "Regression Tests" section of the PostgreSQL documentation to
-find out whether the differences are actually significant. If you need help
-interpreting the results, contact the pgsql-general list at postgresql.org.
-
-After testing, run "make clean" to remove the files generated by the test
-script. Then you can remove the @NAME_PACKAGE@-test RPM, if you wish.
-
-STARTING POSTMASTER AUTOMATICALLY AT SYSTEM STARTUP
--------------------------------------------------------------------------------
-Fedora / Red Hat / CentOS use the systemd package to manage server startup.
-A systemd unit file for PostgreSQL is provided in the server package, as
-@systemdunitsdir@/@NAME_SERVICE@.service. To start the postmaster manually,
-as root run
- systemctl start @NAME_SERVICE@.service
-To shut the postmaster down,
- systemctl stop @NAME_SERVICE@.service
-These two commands only change the postmaster's current status. If you
-want the postmaster to be started automatically during future system startups,
-run
- systemctl enable @NAME_SERVICE@.service
-To undo that again,
- systemctl disable @NAME_SERVICE@.service
-See "man systemctl" for other possible subcommands.
-
-GRAND UNIFIED CONFIGURATION (GUC) FILE
--------------------------------------------------------------------------------
-The PostgreSQL server has many tunable parameters -- the file
-@PGDATADIR@/postgresql.conf is the master configuration file for the
-whole system.
-
-The RPM ships with a mostly-default file -- you will need to tune the
-parameters for your installation. In particular, you might want to allow
-nonlocal TCP/IP socket connections -- in order to allow these, you will need
-to edit the postgresql.conf file. The line in question contains the string
-'listen_addresses' -- you need to both uncomment the line and set the value
-to '*' to get the postmaster to accept nonlocal connections. You'll also need
-to adjust pg_hba.conf appropriately.
-
-LOGGING SET UP
--------------------------------------------------------------------------------
-By default, the postmaster's stderr log is directed into files placed in a
-pg_log subdirectory of the data directory (ie, @PGDATADIR@/pg_log).
-The out-of-the-box configuration rotates among seven files, one for each
-day of the week. You can adjust this by changing postgresql.conf settings.
-
-REBUILDING FROM SOURCE RPM
--------------------------------------------------------------------------------
-If your distribution is not supported by the binary RPMs from PostgreSQL.org,
-you will need to rebuild from the source RPM.
-
-If you have not previously rebuilt any RPMs, set up the required environment:
-make a work directory, say ~/rpmwork, then cd into it and do
- mkdir BUILD BUILDROOT RPMS SOURCES SPECS SRPMS
-Then make a file ~/.rpmmacros containing
- %_topdir <full path to work directory here>
-
-Download the postgresql .src.rpm for the release you want and place it in
-the SRPMS subdirectory, then cd there and execute
- rpmbuild --rebuild postgresql-nnn.src.rpm
-The results will appear under the RPMS subdirectory.
-
-You will have to have a full development environment to rebuild the RPM set.
-If rpmbuild complains of lack of certain packages, install them and try
-again. In some cases, you can disable features to avoid needing some
-development packages, as detailed next.
-
-This release of the RPMset includes the ability to conditionally build
-sets of packages. The parameters, their defaults, and the meanings are:
-
-beta 0 #build with cassert and do not strip the binaries
-runselftest 1 #do "make check" during the build
-test 1 #build the postgresql-test package
-upgrade 1 #build the postgresql-upgrade package
-plpython 1 #build the PL/Python procedural language package
-plpython3 1 #build the PL/Python3 procedural language package
-pltcl 1 #build the PL/Tcl procedural language package
-plperl 1 #build the PL/Perl procedural language package
-ssl 1 #build with OpenSSL support
-kerberos 1 #build with Kerberos 5 support
-ldap 1 #build with LDAP support
-nls 1 #build with national language support
-pam 1 #build with PAM support
-sdt 1 #build with SystemTap support
-xml 1 #build with XML support
-pgfts 1 #build with --enable-thread-safety
-selinux 1 #build contrib/selinux
-uuid 1 #build contrib/uuid-ossp
-
-To use these defines, invoke a rebuild like this:
-rpmbuild --rebuild --define 'plpython 0' --define 'pltcl 0' \
- --define 'test 0' --define 'runselftest 0' --define 'kerberos 0' \
- postgresql-9.2.0-1.src.rpm
-This line would disable the plpython, pltcl, and test subpackages, disable
-the regression test run during build, and disable kerberos support.
-
-You might need to disable runselftest if there is an installed version of
-PostgreSQL that is a different major version from what you are trying to
-build. The self test tends to pick up the installed libpq.so shared library
-in place of the one being built :-(, so if that isn't compatible the test will
-fail. Also, you can't use runselftest when doing the build as root.
-
-More of these conditionals will be added in the future.
-
-CONTRIB FILES
--------------------------------------------------------------------------------
-The contents of the contrib tree are packaged into the -contrib subpackage
-and are processed with make and make install. There is documentation in
-@pgcontribdocdir@ for these modules. Most of the
-modules are in @libdir@/pgsql for loadable modules, and binaries are in
-@bindir@. In the future these files may be split out, depending upon function
-and dependencies.
-
-MORE INFORMATION
--------------------------------------------------------------------------------
-You can get more information at http://www.postgresql.org and
-http://yum.postgresql.org
-
-Please help make this packaging better -- let us know if you find problems, or
-better ways of doing things. You can reach us by e-mail at
-pgsql-pkg-yum@postgresql.org
--------------------------------------------------------------------------------
diff --git a/README.rpm-dist.template b/README.rpm-dist.template
new file mode 100644
index 0000000..ba57706
--- /dev/null
+++ b/README.rpm-dist.template
@@ -0,0 +1,568 @@
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
+
+<!--- m4_divert(-1)
+m4_changequote(`[', `]')
+# vim: ft=xml
+
+m4_define([PGSETUP_SERVICE],
+m4_ifelse([@WANT_SYSVINIT@], [1], m4_dnl
+[service $1 $2],m4_dnl
+[systemctl $1.service $2]))
+
+m4_define([PGSETUP_SERVICE_START], PGSETUP_SERVICE($1, start))
+m4_define([PGSETUP_SERVICE_STOP], PGSETUP_SERVICE($1, stop))
+m4_define([PGSETUP_SERVICE_ENABLE], PGSETUP_SERVICE($1, enable))
+
+m4_define([PGSETUP_ADMIN], [postgres])
+
+m4_define([PGSETUP_COMMAND], [
+<screen>
+ <prompt>$ </prompt><userinput>$1</userinput>
+</screen>
+])
+
+m4_divert[]m4_dnl
+-->
+
+<article lang="en">
+<articleinfo>
+<title>PostgreSQL in RPMs</title>
+</articleinfo>
+
+<sect1 id="introduction">
+ <title>INTRODUCTION</title>
+ <para>
+ This document exists to explain the layout of the RPMs for PostgreSQL, to
+ describe various RPM specifics, and to document special features found in
+ the RPMset.
+ </para>
+ <para>
+ This document is written to be applicable to version @PGMAJORVERSION@ of PostgreSQL,
+ which is the current version of the RPMs as of this writing. More to the
+ point, versions prior to @PGMAJORVERSION@ are not documented here.
+ </para>
+ <para>
+ This document is intended for use only with the RPMs supplied in Red Hat
+ Enterprise Linux, CentOS and Fedora. Note that there are also "PGDG"
+ RPMs available directly from the upstream PostgreSQL project. Those are
+ slightly different.
+ </para>
+</sect1>
+
+<sect1>
+ <title>QUICKSTART</title>
+ <para>
+ For a fresh installation, you will need to initialize the cluster first (as
+ a PGSETUP_ADMIN user):
+
+ PGSETUP_COMMAND(@NAME_BINARYBASE@-setup --initdb)
+
+ and it will prepare a new database cluster for you. Then you will need to
+ start PostgreSQL. Now, as 'root', run:
+
+ PGSETUP_COMMAND([PGSETUP_SERVICE_START(@NAME_SERVICE@)])
+
+ This command will start a postmaster that will listen on localhost and Unix
+ socket 5432 only. Edit @PGDATADIR@/postgresql.conf and pg_hba.conf if you
+ want to allow remote access -- see the section on Grand Unified
+ Configuration.
+
+ You will probably also want to do
+
+ PGSETUP_COMMAND([PGSETUP_SERVICE_ENABLE(@NAME_SERVICE@)])
+
+ so that the postmaster is automatically started during future reboots.
+
+ </para>
+
+ <para>
+ The file @POSTGRES_HOMEDIR@/.bash_profile is packaged to help with the
+ setting of environment variables. You may edit this file, and it won't be
+ overwritten during an upgrade. However, enhancements and bugfixes may be
+ added to this file, so be sure to check .bash_profile.rpmnew after
+ upgrading.
+ </para>
+
+ <para>
+ The user 'postgres' is created during installation of the server subpackage.
+ This user by default is UID and GID 26. The user has the default shell set
+ to bash, and the home directory set to @POSTGRES_HOMEDIR@. This user also
+ has no default password, so the only way to become this user is to su to it
+ from root. If you want to be able to su to it from a non-root account or
+ log in directly as 'postgres' you will need to set a password using passwd.
+ Test section 2.
+ </para>
+
+</sect1>
+
+<sect1>
+ <title>UPGRADING AN INSTALLATION</title>
+
+ <para>
+ For a minor-version upgrade (such as 9.3.1 to 9.3.4; last number changes),
+ just install the new RPMs; there's usually nothing more to it than that.
+ Upgrading across a major release of PostgreSQL (for example, from 9.2.x to
+ 9.3.x) requires more effort.
+ </para>
+
+ <para>
+ If you are upgrading across more than one major release of PostgreSQL
+ (for example, from 8.3.x to 9.0.x), you will need to follow the
+ "traditional" dump and reload process to bring your data into the new
+ version. That is: *before* upgrading, run pg_dumpall to extract all your
+ data into a SQL file. Shut down the old postmaster, upgrade to the new
+ version RPMs, perform initdb, and run the dump file through psql to restore
+ your data.
+ </para>
+
+ <para>
+ In some major releases, the RPMs also support in-place upgrade from the
+ immediately previous major release. Currently, you can upgrade in-place
+ from .x to @PGMAJORVERSION@.x. This is much faster than a
+ dump and reload.
+ To do an in-place upgrade:
+ <orderedlist>
+ <listitem>
+ <para>
+ shut down the old postmaster
+ PGSETUP_COMMAND(PGSETUP_SERVICE_STOP(@NAME_SERVICE@))
+ </para>
+ </listitem>
+ <listitem>
+ <para>optionally make a backup of @PGDATADIR@ (recommended!)</para>
+ </listitem>
+ <listitem>
+ <para>
+ install the new version's RPMs (install all the ones you
+ had before, plus @NAME_PACKAGE@-upgrade)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ as root, run "@NAME_BINARYBASE@-setup --upgrade"
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ update the configuration files @PGDATADIR@/*.conf with any
+ customizations you had before (your old configuration files are in
+ @POSTGRES_HOMEDIR@/data-old/)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ as root, run
+ PGSETUP_SERVICE_START(@NAME_SERVICE@)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ the @NAME_PACKAGE@-upgrade package can be removed after the update is
+ complete, as can @POSTGRES_HOMEDIR@/data-old/
+ </para>
+ </listitem>
+ </orderedlist>
+
+ NOTE: The in-place upgrade process is new and relatively poorly tested,
+ so if your data is critical it's a really good idea to make a tarball
+ backup of @PGDATADIR@ before running the upgrade. This will
+ let you get back to where you were in case of disaster.
+
+ </para>
+</sect1>
+
+<sect1>
+ <title>POSTGRESQL RPM PACKAGES AND RATIONALE</title>
+
+ <para>
+ PostgreSQL is split up into multiple packages so that users can 'pick and
+ choose' what pieces are needed, and what dependencies are required.
+ </para>
+
+ <table>
+ <title>Sub-package list</title>
+ <tgroup cols='2' align='left' colsep='1' rowsep='1'>
+ <thead>
+ <row><entry>Package</entry><entry>Description</entry></row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>@NAME_PACKAGE@:</entry>
+ <entry>Key client programs and basic documentation</entry>
+ </row>
+ <row>
+ <entry>@NAME_PACKAGE@-libs:</entry>
+ <entry>Client shared libraries</entry>
+ </row>
+ <row>
+ <entry>@NAME_PACKAGE@-server:</entry>
+ <entry>Server executables and data files</entry>
+ </row>
+ <row>
+ <entry>@NAME_PACKAGE@-test:</entry>
+ <entry>The regression tests and associated files</entry>
+ </row>
+ <row>
+ <entry>@NAME_PACKAGE@-upgrade:</entry>
+ <entry>Support files for upgrading from previous major version</entry>
+ </row>
+ <row>
+ <entry>@NAME_PACKAGE@-docs:</entry>
+ <entry>Full documentation in HTML and PDF, the tutorial files</entry>
+ </row>
+ <row>
+ <entry>@NAME_PACKAGE@-contrib:</entry>
+ <entry>Add-on loadable modules and programs</entry>
+ </row>
+ <row>
+ <entry>@NAME_PACKAGE@-plperl:</entry>
+ <entry>PL/Perl procedural language</entry>
+ </row>
+ <row>
+ <entry>@NAME_PACKAGE@-plpython:</entry>
+ <entry>PL/Python procedural language (for Python 2)</entry>
+ </row>
+ <row>
+ <entry>@NAME_PACKAGE@-plpython3:</entry>
+ <entry>PL/Python procedural language (for Python 3)</entry>
+ </row>
+ <row>
+ <entry>@NAME_PACKAGE@-pltcl:</entry>
+ <entry>PL/Tcl procedural language</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>
+ You have to install @NAME_PACKAGE@ and @NAME_PACKAGE@-libs to do anything.
+ @NAME_PACKAGE@-server is needed unless you only plan to use the clients to
+ work with a remote PostgreSQL server. The others are optional.
+ </para>
+ <para>
+ Note that there are no @NAME_PACKAGE@-perl, @NAME_PACKAGE@-jdbc,
+ @NAME_PACKAGE@-odbc, @NAME_PACKAGE@-python, @NAME_PACKAGE@-tcl, or
+ @NAME_PACKAGE@-tk subpackages any longer. Those programs have been split
+ off into separate source distributions. They are still available, but in
+ some cases not under those RPM names.
+ </para>
+</sect1>
+
+<sect1>
+ <title>RPM FILE LOCATIONS</title>
+ <para>
+ To be in compliance with the Linux FHS, the PostgreSQL RPMs install files in
+ a manner not consistent with most of the PostgreSQL documentation.
+ According to the standard PostgreSQL documentation, PostgreSQL is installed
+ under the directory /usr/local/pgsql, with executables, source, and data
+ existing in various subdirectories.
+ </para>
+ <para>
+ Different distributions have different ideas of some of these file
+ locations. In particular, the documentation directory can be /usr/doc,
+ /usr/doc/packages, /usr/share/doc, /usr/share/doc/packages, or some other
+ similar path.
+ </para>
+ <para>
+ However, this installation (which usually matches the Red Hat / CentOS /
+ Fedora RPM's) install the files like:
+ </para>
+ <table>
+ <title>Filesystem layout</title>
+ <tgroup cols='2' align='left' colsep='1' rowsep='1'>
+ <thead>
+ <row><entry>Description</entry><entry><emphasis>Directory</emphasis></entry></row>
+ </thead>
+ <tbody>
+ <row><entry>Executables</entry><entry>@bindir@</entry></row>
+ <row><entry>Libraries</entry><entry>@libdir@</entry></row>
+ <row><entry>Documentation</entry><entry>/usr/share/doc/postgresql/html</entry></row>
+ <row><entry>PDF documentation</entry><entry>/usr/share/doc/postgresql-docs</entry></row>
+ <row><entry>Contrib documentation</entry><entry>/usr/share/doc/postgresql-contrib</entry></row>
+ <row><entry>Source</entry><entry>not installed</entry></row>
+ <row><entry>Data</entry><entry>/var/lib/pgsql/data</entry></row>
+ <row><entry>Backup area</entry><entry>/var/lib/pgsql/backups</entry></row>
+ <row><entry>Templates</entry><entry>/usr/share/pgsql</entry></row>
+ <row><entry>Procedural Languages</entry><entry>@libdir@/pgsql</entry></row>
+ <row><entry>Development Headers</entry><entry>/usr/include/pgsql</entry></row>
+ <row><entry>Other shared data</entry><entry>/usr/share/pgsql</entry></row>
+ <row><entry>Regression tests</entry><entry>@libdir@/pgsql/test/regress (in the -test package)</entry></row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+ While it may seem gratuitous to place these files in different locations,
+ the FHS requires it -- distributions should not ever touch /usr/local. It
+ may also seem like more work to keep track of where everything is -- but,
+ that's the beauty of RPM -- you don't have to keep track of the files, RPM
+ does it for you.
+ </para>
+ <para>
+ These RPMs are designed to be LSB-compliant -- if you find this not to be
+ the case, please let us know by way of the pgsql-pkg-yum@postgresql.org
+ mailing list.
+ </para>
+</sect1>
+
+<sect1>
+ <title>MULTIPLE POSTMASTERS</title>
+ <para>
+ The postgresql-server package contains a systemd "unit" files
+ @NAME_SERVICE@.service and @NAME_SERVICE@@.service. The first file is used
+ solely to start the default PostgreSQL server. The second one is designed
+ to allow instantiating additional PostgreSQL servers on same machine.
+ </para>
+ <para>
+ As an example, let us create a secondary PostgreSQL service called,
+ creatively enough, 'postgresql@secondary'. Here are the steps:
+ </para>
+
+ <orderedlist>
+ <listitem>
+ <para>
+ Run the following command to create the necessary configuration and to
+ initialize the new database cluster
+ </para>
+ <screen>
+ <prompt>$ </prompt><userinput>@NAME_BINARYBASE@-setup --initdb \</userinput>
+ <userinput> --unit postgresql@secondary \</userinput>
+ <userinput> --new-systemd-unit \</userinput>
+ <userinput> --datadir /path/to/data/directory \</userinput>
+ <userinput> --port NNNN</userinput>
+ </screen>
+ <para>
+ Replace the "/path/to/data/directory" path and NNNN port with
+ appropriate settings that don't conflict with any other PostgreSQL
+ setup. Make sure that the parent directory of specified path has
+ appropriate ownership and permissions. Note the SELinux issues
+ mentioned below.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Edit postgresql.conf in the target 'datadir' directory to change
+ settings as needed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Start the new service with this command:
+ PGSETUP_COMMAND(PGSETUP_SERVICE_START(@NAME_SERVICE@@secondary))
+ You will probably also want to run the command
+ PGSETUP_COMMAND(PGSETUP_SERVICE_ENABLE(@NAME_SERVICE@@secondary))
+ so that the new service is automatically started in future reboots.
+ </para>
+ </listitem>
+ </orderedlist>
+ <para>
+ When doing a major-version upgrade of a secondary service, add the service
+ name to the @NAME_BINARYBASE@-setup command, for example:
+ PGSETUP_COMMAND(@NAME_BINARYBASE@-setup --upgrade --unit @NAME_SERVICE@@secondary)
+ This will let @NAME_BINARYBASE@-setup find the correct data directory from
+ the proper configuration file.
+ </para>
+ <para>
+ If you are running SELinux in enforcing mode (which is highly recommended,
+ particularly for network-exposed services like PostgreSQL) you will need to
+ adjust SELinux policy to allow the secondary server to use non-default
+ PGPORT or PGDATA settings. To allow use of a non-default port, say 5433, do
+ this as root:
+ PGSETUP_COMMAND(semanage port -a -t postgresql_port_t -p tcp 5433)
+ To allow use of a non-default data directory, say /special/pgdata, do:
+ PGSETUP_COMMAND(semanage fcontext -a -t postgresql_db_t "/special/pgdata(/.*)?")
+ If you already created the directory, follow that with:
+ PGSETUP_COMMAND(restorecon -R /special/pgdata)
+ These settings are persistent across reboots. For more information see "man
+ semanage".
+ </para>
+
+</sect1>
+
+<sect1>
+ <title>REGRESSION TESTING</title>
+ <para>
+ If you install the @NAME_PACKAGE@-test RPM then you can run the PostgreSQL
+ regression tests. These tests stress your database installation and produce
+ results that give you assurances that the installation is complete, and that
+ your database machine is up to the task.
+ </para>
+ <para>
+ To run the regression tests under the RPM installation, make sure that the
+ PostgreSQL server has been started (if not, su to root and do "systemctl
+ start @NAME_SERVICE@.service"), su to postgres, cd to
+ @libdir@/pgsql/test/regress and execute "make check". This command will
+ start the regression tests and will both show the results to the screen and
+ store the results in the file regress.out.
+ </para>
+ <para>
+ If any tests fail, see the file regression.diffs in that directory for
+ details, and read the "Regression Tests" section of the PostgreSQL
+ documentation to find out whether the differences are actually significant.
+ If you need help interpreting the results, contact the pgsql-general list at
+ postgresql.org.
+ </para>
+ <para>
+ After testing, run "make clean" to remove the files generated by the test
+ script. Then you can remove the @NAME_PACKAGE@-test RPM, if you wish.
+ </para>
+</sect1>
+
+<sect1>
+ <title>STARTING POSTMASTER AUTOMATICALLY AT SYSTEM STARTUP</title>
+ <para>
+ Fedora / Red Hat / CentOS use the systemd package to manage server startup.
+ A systemd unit file for PostgreSQL is provided in the server package, as
+ @systemdunitsdir@/@NAME_SERVICE@.service. To start the postmaster manually,
+ as root run
+ PGSETUP_COMMAND(systemctl start @NAME_SERVICE@.service)
+ To shut the postmaster down,
+ PGSETUP_COMMAND(systemctl stop @NAME_SERVICE@.service)
+ These two commands only change the postmaster's current status. If you want
+ the postmaster to be started automatically during future system startups,
+ run
+ PGSETUP_COMMAND(systemctl enable @NAME_SERVICE@.service)
+ To undo that again,
+ PGSETUP_COMMAND(systemctl disable @NAME_SERVICE@.service)
+ See "man systemctl" for other possible subcommands.
+ </para>
+</sect1>
+
+<sect1>
+ <title>GRAND UNIFIED CONFIGURATION (GUC) FILE</title>
+ <para>
+ The PostgreSQL server has many tunable parameters -- the file
+ @PGDATADIR@/postgresql.conf is the master configuration file for the
+ whole system.
+ </para>
+ <para>
+ The RPM ships with a mostly-default file -- you will need to tune the
+ parameters for your installation. In particular, you might want to allow
+ nonlocal TCP/IP socket connections -- in order to allow these, you will need
+ to edit the postgresql.conf file. The line in question contains the string
+ 'listen_addresses' -- you need to both uncomment the line and set the value
+ to '*' to get the postmaster to accept nonlocal connections. You'll also
+ need to adjust pg_hba.conf appropriately.
+ </para>
+</sect1>
+
+<sect1>
+ <title>LOGGING SET UP</title>
+ <para>
+ By default, the postmaster's stderr log is directed into files placed in a
+ pg_log subdirectory of the data directory (ie, @PGDATADIR@/pg_log).
+ The out-of-the-box configuration rotates among seven files, one for each
+ day of the week. You can adjust this by changing postgresql.conf settings.
+ </para>
+</sect1>
+
+<sect1>
+ <title>REBUILDING FROM SOURCE RPM</title>
+ <para>
+ If your distribution is not supported by the binary RPMs from
+ PostgreSQL.org, you will need to rebuild from the source RPM.
+ </para>
+ <para>
+ If you have not previously rebuilt any RPMs, set up the required environment:
+ make a work directory, say ~/rpmwork, then cd into it and do
+ PGSETUP_COMMAND(mkdir BUILD BUILDROOT RPMS SOURCES SPECS SRPMS)
+ Then make a file ~/.rpmmacros containing
+ <screen><userinput>%_topdir full_path_to_work_directory_here</userinput></screen>
+ </para>
+ <para>
+ Download the postgresql .src.rpm for the release you want and place it in
+ the SRPMS subdirectory, then cd there and execute
+ PGSETUP_COMMAND(rpmbuild --rebuild postgresql-nnn.src.rpm)
+ The results will appear under the RPMS subdirectory.
+ </para>
+ <para>
+ You will have to have a full development environment to rebuild the RPM set.
+ If rpmbuild complains of lack of certain packages, install them and try
+ again. In some cases, you can disable features to avoid needing some
+ development packages, as detailed next.
+ </para>
+ <para>
+ This release of the RPMset includes the ability to conditionally build sets
+ of packages. The parameters, their defaults, and the meanings are:
+ </para>
+
+ <table>
+ <title>SRPM configuration options</title>
+ <tgroup cols='3' align='left' colsep='0' rowsep='0'>
+ <thead>
+ <row><entry>Variable</entry><entry>Default</entry><entry>Comment</entry></row>
+ </thead>
+ <tbody>
+ <row><entry>beta</entry><entry>0</entry><entry>build with cassert and do not strip the binaries</entry></row>
+ <row><entry>runselftest</entry><entry>1</entry><entry>do "make check" during the build</entry></row>
+ <row><entry>test</entry><entry>1</entry><entry>build the postgresql-test package</entry></row>
+ <row><entry>upgrade</entry><entry>1</entry><entry>build the postgresql-upgrade package</entry></row>
+ <row><entry>plpython</entry><entry>1</entry><entry>build the PL/Python procedural language package</entry></row>
+ <row><entry>plpython3</entry><entry>1</entry><entry>build the PL/Python3 procedural language package</entry></row>
+ <row><entry>pltcl</entry><entry>1</entry><entry>build the PL/Tcl procedural language package</entry></row>
+ <row><entry>plperl</entry><entry>1</entry><entry>build the PL/Perl procedural language package</entry></row>
+ <row><entry>ssl</entry><entry>1</entry><entry>build with OpenSSL support</entry></row>
+ <row><entry>kerberos</entry><entry>1</entry><entry>build with Kerberos 5 support</entry></row>
+ <row><entry>ldap</entry><entry>1</entry><entry>build with LDAP support</entry></row>
+ <row><entry>nls</entry><entry>1</entry><entry>build with national language support</entry></row>
+ <row><entry>pam</entry><entry>1</entry><entry>build with PAM support</entry></row>
+ <row><entry>sdt</entry><entry>1</entry><entry>build with SystemTap support</entry></row>
+ <row><entry>xml</entry><entry>1</entry><entry>build with XML support</entry></row>
+ <row><entry>pgfts</entry><entry>1</entry><entry>build with --enable-thread-safety</entry></row>
+ <row><entry>selinux</entry><entry>1</entry><entry>build contrib/selinux</entry></row>
+ <row><entry>uuid</entry><entry>1</entry><entry>build contrib/uuid-ossp</entry></row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+ To use these defines, invoke a rebuild like this:
+ <screen>
+ <prompt>$ </prompt><userinput>rpmbuild --rebuild \
+ --define 'plpython 0' \
+ --define 'pltcl 0' \
+ --define 'test 0' \
+ --define 'runselftest 0' \
+ --define 'kerberos 0' \
+ postgresql-9.2.0-1.src.rpm
+ </userinput></screen>
+ This command would disable the plpython, pltcl, and test subpackages,
+ disable the regression test run during build, and disable kerberos support.
+ </para>
+ <para>
+ You might need to disable runselftest if there is an installed version of
+ PostgreSQL that is a different major version from what you are trying to
+ build. The self test tends to pick up the installed libpq.so shared library
+ in place of the one being built :-(, so if that isn't compatible the test
+ will fail. Also, you can't use runselftest when doing the build as root.
+ </para>
+ <para>
+ More of these conditionals will be added in the future.
+ </para>
+</sect1>
+
+<sect1>
+ <title>CONTRIB FILES</title>
+ <para>
+ The contents of the contrib tree are packaged into the -contrib subpackage
+ and are processed with make and make install. There is documentation in
+ @pgcontribdocdir@ for these modules. Most of the modules are in
+ @libdir@/pgsql for loadable modules, and binaries are in @bindir@. In the
+ future these files may be split out, depending upon function and
+ dependencies.
+ </para>
+</sect1>
+
+<sect1>
+ <title>MORE INFORMATION</title>
+ <para>
+ You can get more information at http://www.postgresql.org and
+ http://yum.postgresql.org
+ </para>
+ <para>
+ Please help make this packaging better -- let us know if you find problems,
+ or better ways of doing things. You can reach us by e-mail at
+ pgsql-pkg-yum@postgresql.org
+ </para>
+</sect1>
+
+</article>
diff --git a/TODO b/TODO
index 8e234d4..b0203d1 100644
--- a/TODO
+++ b/TODO
@@ -22,3 +22,5 @@
edit generated file instead its '*.in' parent
* Allow guys from KDE upgrade the PG stack somehow.
+
+* stylesheets & html version for README.rpm-dist
diff --git a/configure.ac b/configure.ac
index aa82982..c8c67c5 100644
--- a/configure.ac
+++ b/configure.ac
@@ -24,7 +24,9 @@ AC_ARG_WITH([sysvinit],
[WANT_SYSVINIT=0]
)
+test -z "$WANT_SYSVINIT" && WANT_SYSVINIT=0
AM_CONDITIONAL([WANT_SYSVINIT], [test "$WANT_SYSVINIT" -eq 1])
+AC_SUBST([WANT_SYSVINIT])
# Instatiating generated files by sed instead of config.status.
# This is encouraged by autoconf documentation itself because if we used
@@ -47,7 +49,8 @@ sed_subst_var_pattern(README_DIST)
sed_subst_var_pattern(SU_POSTGRES)
sed_subst_var_pattern(sysconfdir)
sed_subst_var_pattern(TEST_GEN_FILES_LIST)
-sed_subst_var_pattern(VERSION)"
+sed_subst_var_pattern(VERSION)
+sed_subst_var_pattern(WANT_SYSVINIT)"
m4_define([add_sed_subst_var], [
SED_RULES="$SED_RULES