From 6b8f96b5904edc10f9dd43aea15a3a91a8d0c65c Mon Sep 17 00:00:00 2001 From: Abhijit Menon-Sen Date: Thu, 12 Mar 2015 18:34:55 +0530 Subject: [PATCH] Split out packaging notes too --- OLD-README.rst | 208 ------------------------------------------------- PACKAGES.md | 123 +++++++++++++++++++++++++++++ README.md | 15 ++-- 3 files changed, 133 insertions(+), 213 deletions(-) create mode 100644 PACKAGES.md diff --git a/OLD-README.rst b/OLD-README.rst index a82752da..b4293ddd 100644 --- a/OLD-README.rst +++ b/OLD-README.rst @@ -5,41 +5,6 @@ repmgr: Replication Manager for PostgreSQL clusters Introduction ============ -PostgreSQL 9+ allow us to have replicated Hot Standby servers -which we can query and/or use for high availability. - -While the main components of the feature are included with -PostgreSQL, the user is expected to manage the high availability -part of it. - -repmgr allows you to monitor and manage your replicated PostgreSQL -databases as a single cluster. repmgr includes two components: - -* repmgr: command program that performs tasks and then exits - -* repmgrd: management and monitoring daemon that watches the cluster - and can automate remote actions. - -Supported Releases ------------------- - -repmgr works with PostgreSQL versions 9.0 and later. - -There are currently no incompatibilities when upgrading repmgr from 9.0 to 9.1, -so your 9.0 configuration will work with 9.1 - -Additional parameters must be added to postgresql.conf to take advantage of -the new 9.1 features such as synchronous replication or hot standby feedback. - -Requirements ------------- - -repmgr is currently aimed for installation on UNIX-like systems that include -development tools such as ``gcc`` and ``gmake``. It also requires that the -``rsync`` utility is available in the PATH of the user running the repmgr -programs. Some operations also require PostgreSQL components such -as ``pg_config`` and ``pg_ctl`` be in the PATH. - Introduction to repmgr commands =============================== @@ -102,179 +67,6 @@ To install and use repmgr and repmgrd follow these steps: 5. Setup repmgrd to aid in failover transitions -Build repmgr programs ---------------------- - -Both methods of installation will place the binaries at the same location as your -postgres binaries, such as ``psql``. There are two ways to build it. The second -requires a full PostgreSQL source code tree to install the program directly into. -The first instead uses the PostgreSQL Extension System (PGXS) to install. For -this method to work, you will need the pg_config program available in your PATH. -In some distributions of PostgreSQL, this requires installing a separate -development package in addition to the basic server software. - -Build repmgr programs - PGXS -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you are using a packaged PostgreSQL build and have ``pg_config`` -available, the package can be built and installed using PGXS instead:: - - tar xvzf repmgr-1.0.tar.gz - cd repmgr - make USE_PGXS=1 - make USE_PGXS=1 install - -This is preferred to building from the ``contrib`` subdirectory of the main -source code tree. - -If you need to remove the source code temporary files from this directory, -that can be done like this:: - - make USE_PGXS=1 clean - -See below for building notes specific to RedHat Linux variants. - -Using a full source code tree -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In this method, the repmgr distribution is copied into the PostgreSQL source -code tree, assumed to be under ${postgresql_sources} for this example. -The resulting subdirectory must be named ``contrib/repmgr``, without any -version number:: - - cp repmgr.tar.gz ${postgresql_sources}/contrib - cd ${postgresql_sources}/contrib - tar xvzf repmgr-1.0.tar.gz - cd repmgr - make - make install - -If you need to remove the source code temporary files from this directory, -that can be done like this:: - - make clean - -Notes on RedHat Linux, Fedora, and CentOS Builds -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The RPM packages of PostgreSQL put ``pg_config`` into the ``postgresql-devel`` -package, not the main server one. And if you have a RPM install of PostgreSQL -9.0, the entire PostgreSQL binary directory will not be in your PATH by default -either. Individual utilities are made available via the ``alternatives`` -mechanism, but not all commands will be wrapped that way. The files installed -by repmgr will certainly not be in the default PATH for the postgres user -on such a system. They will instead be in /usr/pgsql-9.0/bin/ on this -type of system. - -When building repmgr against a RPM packaged build, you may discover that some -development packages are needed as well. The following build errors can -occur:: - - /usr/bin/ld: cannot find -lxslt - /usr/bin/ld: cannot find -lpam - -Install the following packages to correct those:: - - yum install libxslt-devel - yum install pam-devel - -If building repmgr as a regular user, then doing the install into the system -directories using sudo, the syntax is hard. ``pg_config`` won't be in root's -path either. The following recipe should work:: - - sudo PATH="/usr/pgsql-9.0/bin:$PATH" make USE_PGXS=1 install - -Issues with 32 and 64 bit RPMs -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If when building, you receive a series of errors of this form:: - - /usr/bin/ld: skipping incompatible /usr/pgsql-9.0/lib/libpq.so when searching for -lpq - -This is likely because you have both the 32 and 64 bit versions of the -``postgresql90-devel`` package installed. You can check that like this:: - - rpm -qa --queryformat '%{NAME}\t%{ARCH}\n' | grep postgresql90-devel - -And if two packages appear, one for i386 and one for x86_64, that's not supposed -to be allowed. - -This can happen when using the PGDG repo to install that package; -here is an example sessions demonstrating the problem case appearing:: - - # yum install postgresql-devel - .. - Setting up Install Process - Resolving Dependencies - --> Running transaction check - ---> Package postgresql90-devel.i386 0:9.0.2-2PGDG.rhel5 set to be updated - ---> Package postgresql90-devel.x86_64 0:9.0.2-2PGDG.rhel5 set to be updated - --> Finished Dependency Resolution - - Dependencies Resolved - - ========================================================================= - Package Arch Version Repository Size - ========================================================================= - Installing: - postgresql90-devel i386 9.0.2-2PGDG.rhel5 pgdg90 1.5 M - postgresql90-devel x86_64 9.0.2-2PGDG.rhel5 pgdg90 1.6 M - -Note how both the i386 and x86_64 platform architectures are selected for -installation. Your main PostgreSQL package will only be compatible with one of -those, and if the repmgr build finds the wrong postgresql90-devel these -"skipping incompatible" messages appear. - -In this case, you can temporarily remove both packages, then just install the -correct one for your architecture. Example:: - - rpm -e postgresql90-devel --allmatches - yum install postgresql90-devel-9.0.2-2PGDG.rhel5.x86_64 - -Instead just deleting the package from the wrong platform might not leave behind -the correct files, due to the way in which these accidentally happen to interact. -If you already tried to build repmgr before doing this, you'll need to do:: - - make USE_PGXS=1 clean - -to get rid of leftover files from the wrong architecture. - -Notes on Ubuntu, Debian or other Debian-based Builds -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The Debian packages of PostgreSQL put ``pg_config`` into the development package -called ``postgresql-server-dev-$version``. - -When building repmgr against a Debian packages build, you may discover that some -development packages are needed as well. You will need the following development -packages installed:: - - sudo apt-get install libxslt-dev libxml2-dev libpam-dev libedit-dev - -If your using Debian packages for PostgreSQL and are building repmgr with the -USE_PGXS option you also need to install the corresponding development package:: - - sudo apt-get install postgresql-server-dev-9.0 - -If you build and install repmgr manually it will not be on the system path. The -binaries will be installed in /usr/lib/postgresql/$version/bin/ which is not on -the default path. The reason behind this is that Ubuntu/Debian systems manage -multiple installed versions of PostgreSQL on the same system through a wrapper -called pg_wrapper and repmgr is not (yet) known to this wrapper. - -You can solve this in many different ways, the most Debian like is to make an -alternate for repmgr and repmgrd:: - - sudo update-alternatives --install /usr/bin/repmgr repmgr /usr/lib/postgresql/9.0/bin/repmgr 10 - sudo update-alternatives --install /usr/bin/repmgrd repmgrd /usr/lib/postgresql/9.0/bin/repmgrd 10 - -You can also make a deb package of repmgr using:: - - make USE_PGXS=1 deb - -This will build a Debian package one level up from where you build, normally the -same directory that you have your repmgr/ directory in. - Confirm software was built correctly ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/PACKAGES.md b/PACKAGES.md new file mode 100644 index 00000000..11f2720f --- /dev/null +++ b/PACKAGES.md @@ -0,0 +1,123 @@ +Packaging +========= + +Notes on RedHat Linux, Fedora, and CentOS Builds +------------------------------------------------ + +The RPM packages of PostgreSQL put ``pg_config`` into the ``postgresql-devel`` +package, not the main server one. And if you have a RPM install of PostgreSQL +9.0, the entire PostgreSQL binary directory will not be in your PATH by default +either. Individual utilities are made available via the ``alternatives`` +mechanism, but not all commands will be wrapped that way. The files installed +by repmgr will certainly not be in the default PATH for the postgres user +on such a system. They will instead be in /usr/pgsql-9.0/bin/ on this +type of system. + +When building repmgr against a RPM packaged build, you may discover that some +development packages are needed as well. The following build errors can +occur:: + + /usr/bin/ld: cannot find -lxslt + /usr/bin/ld: cannot find -lpam + +Install the following packages to correct those:: + + yum install libxslt-devel + yum install pam-devel + +If building repmgr as a regular user, then doing the install into the system +directories using sudo, the syntax is hard. ``pg_config`` won't be in root's +path either. The following recipe should work:: + + sudo PATH="/usr/pgsql-9.0/bin:$PATH" make USE_PGXS=1 install + +Issues with 32 and 64 bit RPMs +------------------------------ + +If when building, you receive a series of errors of this form:: + + /usr/bin/ld: skipping incompatible /usr/pgsql-9.0/lib/libpq.so when searching for -lpq + +This is likely because you have both the 32 and 64 bit versions of the +``postgresql90-devel`` package installed. You can check that like this:: + + rpm -qa --queryformat '%{NAME}\t%{ARCH}\n' | grep postgresql90-devel + +And if two packages appear, one for i386 and one for x86_64, that's not supposed +to be allowed. + +This can happen when using the PGDG repo to install that package; +here is an example sessions demonstrating the problem case appearing:: + + # yum install postgresql-devel + .. + Setting up Install Process + Resolving Dependencies + --> Running transaction check + ---> Package postgresql90-devel.i386 0:9.0.2-2PGDG.rhel5 set to be updated + ---> Package postgresql90-devel.x86_64 0:9.0.2-2PGDG.rhel5 set to be updated + --> Finished Dependency Resolution + + Dependencies Resolved + + ========================================================================= + Package Arch Version Repository Size + ========================================================================= + Installing: + postgresql90-devel i386 9.0.2-2PGDG.rhel5 pgdg90 1.5 M + postgresql90-devel x86_64 9.0.2-2PGDG.rhel5 pgdg90 1.6 M + +Note how both the i386 and x86_64 platform architectures are selected for +installation. Your main PostgreSQL package will only be compatible with one of +those, and if the repmgr build finds the wrong postgresql90-devel these +"skipping incompatible" messages appear. + +In this case, you can temporarily remove both packages, then just install the +correct one for your architecture. Example:: + + rpm -e postgresql90-devel --allmatches + yum install postgresql90-devel-9.0.2-2PGDG.rhel5.x86_64 + +Instead just deleting the package from the wrong platform might not leave behind +the correct files, due to the way in which these accidentally happen to interact. +If you already tried to build repmgr before doing this, you'll need to do:: + + make USE_PGXS=1 clean + +to get rid of leftover files from the wrong architecture. + +Notes on Ubuntu, Debian or other Debian-based Builds +---------------------------------------------------- + +The Debian packages of PostgreSQL put ``pg_config`` into the development package +called ``postgresql-server-dev-$version``. + +When building repmgr against a Debian packages build, you may discover that some +development packages are needed as well. You will need the following development +packages installed:: + + sudo apt-get install libxslt-dev libxml2-dev libpam-dev libedit-dev + +If your using Debian packages for PostgreSQL and are building repmgr with the +USE_PGXS option you also need to install the corresponding development package:: + + sudo apt-get install postgresql-server-dev-9.0 + +If you build and install repmgr manually it will not be on the system path. The +binaries will be installed in /usr/lib/postgresql/$version/bin/ which is not on +the default path. The reason behind this is that Ubuntu/Debian systems manage +multiple installed versions of PostgreSQL on the same system through a wrapper +called pg_wrapper and repmgr is not (yet) known to this wrapper. + +You can solve this in many different ways, the most Debian like is to make an +alternate for repmgr and repmgrd:: + + sudo update-alternatives --install /usr/bin/repmgr repmgr /usr/lib/postgresql/9.0/bin/repmgr 10 + sudo update-alternatives --install /usr/bin/repmgrd repmgrd /usr/lib/postgresql/9.0/bin/repmgrd 10 + +You can also make a deb package of repmgr using:: + + make USE_PGXS=1 deb + +This will build a Debian package one level up from where you build, normally the +same directory that you have your repmgr/ directory in. diff --git a/README.md b/README.md index 89debaa1..5fb3cea4 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ repmgr: Replication Manager for PostgreSQL clusters =================================================== -`repmgr` is an open-source tool to mananage replication and failover +`repmgr` is an open-source tool to manage replication and failover between multiple PostgreSQL servers. It enhances PostgreSQL's built-in hot-standby capabilities with tools to set up standby servers, monitor replication, and perform administrative tasks such as failover or manual @@ -34,7 +34,8 @@ See the "QUICKSTART.md" file for examples of how to use these commands. Once the cluster is in operation, run `repmgr cluster show` to see the status of the registered primary and standby nodes. Any standby can be manually promoted using `repmgr standby promote`. Other standby nodes -can be told to follow the new master using `repmgr standby follow`. +can be told to follow the new master using `repmgr standby follow`. We +show examples of these commands below. Next, for detailed monitoring, you must run `repmgrd` (with the same configuration file) on all your nodes. Replication status information is @@ -70,14 +71,18 @@ Installation * Packages - PGDG publishes RPM packages for RedHat-based distributions - Debian/Ubuntu provide .deb packages. - - The files under the `debian` and `RHEL` directories can be used to - build .deb and .rpm packages directly from the `repmgr` source code. + - See "PACKAGES.md" for details on building .deb and .rpm packages + from the `repmgr` source code. * Source installation - `git clone https://github.com/2ndQuadrant/repmgr` - Or download tar.gz files from https://github.com/2ndQuadrant/repmgr/releases - - To install from source, just run `sudo make USE_PGXS=1 install` + - To install from source, run `sudo make USE_PGXS=1 install` + +After installation, you should be able to run `repmgr --version` and +`repmgrd --version`. These binaries should be installed in the same +directory as other PostgreSQL binaries, such as `psql`. Configuration -------------