Better INSTALL file

Поиск
Список
Период
Сортировка
От Bruce Momjian
Тема Better INSTALL file
Дата
Msg-id 199910040521.BAA10636@candle.pha.pa.us
обсуждение исходный текст
Список pgsql-docs
Here is a better version generated by Netscape, not lynx.  I did "save
as text" on the HTML file.

This looks very good.  I think using Netscape rather than sgml/jade to
generate the flat ASCII files in our distribution would be a good idea.

--
  Bruce Momjian                        |  http://www.op.net/~candle
  maillist@candle.pha.pa.us            |  (610) 853-3000
  +  If your life is a hard drive,     |  830 Blythe Avenue
  +  Christ can be your backup.        |  Drexel Hill, Pennsylvania 19026
                                Installation
Prev                                                                    Next
  ------------------------------------------------------------------------

Installation Procedure

Postgres Installation

For a fresh install or upgrading from previous releases of Postgres:

  1. Read any last minute information and platform specific porting notes.
     There are some platform specific notes at the end of this file for
     Ultrix4.x, Linux, BSD/OS and NeXT. There are other files in directory
     /usr/src/pgsql/doc, including files FAQ-Irix and FAQ-Linux. Also look
     in directory ftp://ftp.postgresql.org/pub. If there is a file called
     INSTALL in this directory then this file will contain the latest
     installation information.

     Please note that a "tested" platform in the list given earlier simply
     means that someone went to the effort at some point of making sure that
     a Postgres distribution would compile and run on this platform without
     modifying the code. Since the current developers will not have access
     to all of these platforms, some of them may not compile cleanly and
     pass the regression tests in the current release due to minor problems.
     Any such known problems and their solutions will be posted in
     ftp://ftp.postgresql.org/pub/INSTALL.

  2. Create the Postgres superuser account (postgres is commonly used) if it
     does not already exist.

     The owner of the Postgres files can be any unprivileged user account.
     It must not be root, bin, or any other account with special access
     rights, as that would create a security risk.

  3. Log in to the Postgres superuser account. Most of the remaining steps
     in the installation will happen in this account.

  4. Ftp file ftp://ftp.postgresql.org/pub/postgresql-v6.5.1.tar.gz from the
     Internet. Store it in your home directory.

  5. Some platforms use flex. If your system uses flex then make sure you
     have a good version. To check, type

     $ flex --version

     If the flex command is not found then you probably do not need it. If
     the version is 2.5.2 or 2.5.4 or greater then you are okay. If it is
     2.5.3 or before 2.5.2 then you will have to upgrade flex. You may get
     it at ftp://prep.ai.mit.edu/pub/gnu/flex-2.5.4.tar.gz.

     If you need flex and don't have it or have the wrong version, then you
     will be told so when you attempt to compile the program. Feel free to
     skip this step if you aren't sure you need it. If you do need it then
     you will be told to install/upgrade flex when you try to compile
     Postgres.

     You may want to do the entire flex installation from the root account,
     though that is not absolutely necessary. Assuming that you want the
     installation to place files in the usual default areas, type the
     following:

     $ su -
     $ cd /usr/local/src
     ftp prep.ai.mit.edu
     ftp> cd /pub/gnu/
     ftp> binary
     ftp> get flex-2.5.4.tar.gz
     ftp> quit
     $ gunzip -c flex-2.5.4.tar.gz | tar xvf -
     $ cd flex-2.5.4
     $ configure --prefix=/usr
     $ gmake
     $ gmake check
     # You must be root when typing the next line:
     $ gmake install
     $ cd /usr/local/src
     $ rm -rf flex-2.5.4

     This will update files /usr/man/man1/flex.1, /usr/bin/flex,
     /usr/lib/libfl.a, /usr/include/FlexLexer.h and will add a link
     /usr/bin/flex++ which points to flex.

  6. If you are not upgrading an existing system then skip to . If you are
     upgrading from 6.5, you do not need to dump/reload or initdb. Simply
     compile the source code, stop the postmaster, do a "make install", and
     restart the postmaster. If you are upgrading from 6.4.* or earlier,
     back up your database. For alpha- and beta-level releases, the database
     format is liable to change, often every few weeks, with no notice
     besides a quick comment in the HACKERS mailing list. Full releases
     always require a dump/reload from previous releases. It is therefore a
     bad idea to skip this step.

          Tip: Do not use the pg_dumpall script from v6.0 or everything
          will be owned by the Postgres super user.

     To dump your fairly recent post-v6.0 database installation, type

     $ pg_dumpall > db.out

     To use the latest pg_dumpall script on your existing older database
     before upgrading Postgres, pull the most recent version of pg_dumpall
     from the new distribution:

     $ cd
     $ gunzip -c postgresql-v6.5.1.tar.gz \
         | tar xvf - src/bin/pg_dump/pg_dumpall
     $ chmod a+x src/bin/pg_dump/pg_dumpall
     $ src/bin/pg_dump/pg_dumpall > db.out
     $ rm -rf src

     If you wish to preserve object id's (oids), then use the -o option when
     running pg_dumpall. However, unless you have a special reason for doing
     this (such as using OIDs as keys in tables), don't do it.

     If the pg_dumpall command seems to take a long time and you think it
     might have died, then, from another terminal, type

     $ ls -l db.out

     several times to see if the size of the file is growing.

     Please note that if you are upgrading from a version prior to
     Postgres95 v1.09 then you must back up your database, install
     Postgres95 v1.09, restore your database, then back it up again. You
     should also read the release notes which should cover any
     release-specific issues.

                                        Caution
      You must make sure that your database is not updated in the middle of your
      backup. If necessary, bring down postmaster, edit the permissions in file
      /usr/local/pgsql/data/pg_hba.conf to allow only you on, then bring
      postmaster back up.
  7. If you are upgrading an existing system then kill the postmaster. Type

     $ ps -ax | grep postmaster

     This should list the process numbers for a number of processes. Type
     the following line, with pid replaced by the process id for process
     postmaster. (Do not use the id for process "grep postmaster".) Type

     $ kill pid

     to actually stop the process.

          Tip: On systems which have Postgres started at boot time,
          there is probably a startup file which will accomplish the
          same thing. For example, on my Linux system I can type

          $ /etc/rc.d/init.d/postgres.init stop

          to halt Postgres.

  8. If you are upgrading an existing system then move the old directories
     out of the way. If you are short of disk space then you may have to
     back up and delete the directories instead. If you do this, save the
     old database in the /usr/local/pgsql/data directory tree. At a minimum,
     save file /usr/local/pgsql/data/pg_hba.conf.

     Type the following:

     $ su -
     $ cd /usr/src
     $ mv pgsql pgsql_6_0
     $ cd /usr/local
     $ mv pgsql pgsql_6_0
     $ exit

     If you are not using /usr/local/pgsql/data as your data directory
     (check to see if environment variable PGDATA is set to something else)
     then you will also want to move this directory in the same manner.

  9. Make new source and install directories. The actual paths can be
     different for your installation but you must be consistent throughout
     this procedure.

          Note: There are two places in this installation procedure
          where you will have an opportunity to specify installation
          locations for programs, libraries, documentation, and other
          files. Usually it is sufficient to specify these at the gmake
          install stage of installation.

     Type

     $ su
     $ cd /usr/src
     $ mkdir pgsql
     $ chown postgres:postgres pgsql
     $ cd /usr/local
     $ mkdir pgsql
     $ chown postgres:postgres pgsql
     $ exit

 10. Unzip and untar the new source file. Type

     $ cd /usr/src/pgsql
     $ gunzip -c ~/postgresql-v6.5.1.tar.gz | tar xvf -

 11. Configure the source code for your system. It is this step at which you
     can specify your actual installation path for the build process (see
     the --prefix option below). Type

     $ cd /usr/src/pgsql/src
     $ ./configure [ options ]

       a. Among other chores, the configure script selects a system-specific
          "template" file from the files provided in the template
          subdirectory. If it cannot guess which one to use for your system,
          it will say so and exit. In that case you'll need to figure out
          which one to use and run configure again, this time giving the
          --with-template=TEMPLATE option to make the right file be chosen.

               Please Report Problems: If your system is not
               automatically recognized by configure and you have to do
               this, please send email to scrappy@hub.org with the
               output of the program ./config.guess. Indicate what the
               template file should be.

       b. Choose configuration options. Check for details. However, for a
          plain-vanilla first installation with no extra options like
          multi-byte character support or locale collation support it may be
          adequate to have chosen the installation areas and to run
          configure without extra options specified. The configure script
          accepts many additional options that you can use if you don't like
          the default configuration. To see them all, type

               ./configure --help

          Some of the more commonly used ones are:

                 --prefix=BASEDIR   Selects a different base directory for the
                                    installation of the Postgres configuration.
                                    The default is /usr/local/pgsql.
                 --with-template=TEMPLATE
                                    Use template file TEMPLATE - the template
                                    files are assumed to be in the directory
                                    src/template, so look there for proper values.
                 --with-tcl         Build interface libraries and programs requiring
                                    Tcl/Tk, including libpgtcl, pgtclsh, and pgtksh.
                 --with-perl        Build the Perl interface library.
                 --with-odbc        Build the ODBC driver package.
                 --enable-hba       Enables Host Based Authentication (DEFAULT)
                 --disable-hba      Disables Host Based Authentication
                 --enable-locale    Enables USE_LOCALE
                 --enable-cassert   Enables ASSERT_CHECKING
                 --with-CC=compiler
                                    Use a specific C compiler that the configure
                                    script cannot find.
                 --with-CXX=compiler
                 --without-CXX
                                    Use a specific C++ compiler that the configure
                                    script cannot find, or exclude C++ compilation
                                    altogether.   (This only affects libpq++ at
                                    present.)

       c. Here is the configure script used on a Sparc Solaris 2.5 system
          with /opt/postgres specified as the installation base directory:

          $ ./configure --prefix=/opt/postgres \
              --with-template=sparc_solaris-gcc --with-pgport=5432 \
              --enable-hba --disable-locale

               Tip: Of course, you may type these three lines all on
               the same line.

 12. Install the man and HTML documentation. Type

     $ cd /usr/src/pgsql/doc
     $ gmake install

     The documentation is also available in Postscript format. Look for
     files ending with .ps.gz in the same directory.

 13. Compile the program. Type

     $ cd /usr/src/pgsql/src
     $ gmake all > make.log 2>&1 &
     $ tail -f make.log

     The last line displayed will hopefully be

     All of PostgreSQL is successfully made. Ready to install.

     Remember, "gmake" may be called "make" on your system. At this point,
     or earlier if you wish, type control-C to get out of tail. (If you have
     problems later on you may wish to examine file make.log for warning and
     error messages.)

          Note: You will probably find a number of warning messages in
          make.log. Unless you have problems later on, these messages
          may be safely ignored.

     If the compiler fails with a message stating that the flex command
     cannot be found then install flex as described earlier. Next, change
     directory back to this directory, type

     $ gmake clean

     then recompile again.

     Compiler options, such as optimization and debugging, may be specified
     on the command line using the COPT variable. For example, typing

     $ gmake COPT="-g" all > make.log 2>&1 &

     would invoke your compiler's -g option in all steps of the build. See
     src/Makefile.global.in for further details.

 14. Install the program. Type

     $ cd /usr/src/pgsql/src
     $ gmake install > make.install.log 2>&1 &
     $ tail -f make.install.log

     The last line displayed will be

     gmake[1]: Leaving directory `/usr/src/pgsql/src/man'

     At this point, or earlier if you wish, type control-C to get out of
     tail. Remember, "gmake" may be called "make" on your system.

 15. If necessary, tell your system how to find the new shared libraries.
     You can do one of the following, preferably the first:

       a. As root, edit file /etc/ld.so.conf. Add a line

          /usr/local/pgsql/lib

          to the file. Then run command /sbin/ldconfig.

       b. In a bash shell, type

              export LD_LIBRARY_PATH=/usr/local/pgsql/lib

       c. In a csh shell, type

              setenv LD_LIBRARY_PATH /usr/local/pgsql/lib

     Please note that the above commands may vary wildly for different
     operating systems. Check the platform specific notes, such as those for
     Ultrix4.x or and for non-ELF Linux.

     If, when you create the database, you get the message

     pg_id: can't load library 'libpq.so'

     then the above step was necessary. Simply do this step, then try to
     create the database again.

 16. If you used the --with-perl option to configure, check the install log
     to see whether the Perl module was actually installed. If you've
     followed our advice to make the Postgres files be owned by an
     unprivileged userid, then the Perl module won't have been installed,
     for lack of write privileges on the Perl library directories. You can
     complete its installation, either now or later, by becoming the user
     that does own the Perl library (often root) (via su) and doing

           $ cd /usr/src/pgsql/src/interfaces/perl5
           $ gmake install


 17. If it has not already been done, then prepare account postgres for
     using Postgres. Any account that will use Postgres must be similarly
     prepared.

     There are several ways to influence the runtime environment of the
     Postgres server. Refer to the Administrator's Guide for more
     information.

          Note: The following instructions are for a bash/sh shell.
          Adapt accordingly for other shells.

       a. Add the following lines to your login environment: shell,
          ~/.bash_profile:

                  PATH=$PATH:/usr/local/pgsql/bin
                  MANPATH=$MANPATH:/usr/local/pgsql/man
                  PGLIB=/usr/local/pgsql/lib
                  PGDATA=/usr/local/pgsql/data
                  export PATH MANPATH PGLIB PGDATA


       b. Several regression tests could fail if the user's locale collation
          scheme is different from that of the standard C locale.

          If you configure and compile Postgres with --enable-locale then
          you should set the locale environment to "C" (or unset all "LC_*"
          variables) by putting these additional lines to your login
          environment before starting postmaster:

                  LC_COLLATE=C
                  LC_CTYPE=C
                  export LC_COLLATE LC_CTYPE





       c. Make sure that you have defined these variables before continuing
          with the remaining steps. The easiest way to do this is to type:

                  $ source ~/.bash_profile


 18. Create the database installation from your Postgres superuser account
     (typically account postgres). Do not do the following as root! This
     would be a major security hole. Type

     $ initdb

 19. Set up permissions to access the database system. Do this by editing
     file /usr/local/pgsql/data/pg_hba.conf. The instructions are included
     in the file. (If your database is not located in the default location,
     i.e. if PGDATA is set to point elsewhere, then the location of this
     file will change accordingly.) This file should be made read only again
     once you are finished. If you are upgrading from v6.0 or later you can
     copy file pg_hba.conf from your old database on top of the one in your
     new database, rather than redoing the file from scratch.

 20. Briefly test that the backend will start and run by running it from the
     command line.

       a. Start the postmaster daemon running in the background by typing

          $ cd
          $ nohup postmaster -i > pgserver.log 2>&1 &

       b. Create a database by typing

          $ createdb

       c. Connect to the new database:

          $ psql

       d. And run a sample query:

          postgres=> SELECT datetime 'now';

       e. Exit psql:

          postgres=> \q

       f. Remove the test database (unless you will want to use it later for
          other tests):

          $ destroydb

 21. Run postmaster in the background from your Postgres superuser account
     (typically account postgres). Do not run postmaster from the root
     account!

     Usually, you will want to modify your computer so that it will
     automatically start postmaster whenever it boots. It is not required;
     the Postgres server can be run successfully from non-privileged
     accounts without root intervention.

     Here are some suggestions on how to do this, contributed by various
     users.

     Whatever you do, postmaster must be run by the Postgres superuser
     (postgres?) and not by root. This is why all of the examples below
     start by switching user (su) to postgres. These commands also take into
     account the fact that environment variables like PATH and PGDATA may
     not be set properly. The examples are as follows. Use them with extreme
     caution.

        o If you are installing from a non-privileged account and have no
          root access, then start the postmaster and send it to the
          background:

          $ cd
          $ nohup postmaster > regress.log 2>&1 &

        o Edit file rc.local on NetBSD or file rc2.d on SPARC Solaris 2.5.1
          to contain the following single line:

          su postgres -c "/usr/local/pgsql/bin/postmaster -S -D /usr/local/pgsql/data"

        o In FreeBSD 2.2-RELEASE edit /usr/local/etc/rc.d/pgsql.sh to
          contain the following lines and make it chmod 755 and chown
          root:bin.

          #!/bin/sh
          [ -x /usr/local/pgsql/bin/postmaster ] && {
              su -l pgsql -c 'exec /usr/local/pgsql/bin/postmaster
                  -D/usr/local/pgsql/data
                  -S -o -F > /usr/local/pgsql/errlog' &
              echo -n ' pgsql'
          }

          You may put the line breaks as shown above. The shell is smart
          enough to keep parsing beyond end-of-line if there is an
          expression unfinished. The exec saves one layer of shell under the
          postmaster process so the parent is init.

        o In RedHat Linux add a file /etc/rc.d/init.d/postgres.init which is
          based on the example in contrib/linux/. Then make a softlink to
          this file from /etc/rc.d/rc5.d/S98postgres.init.

        o In RedHat Linux edit file /etc/inittab to add the following as a
          single line:

          pg:2345:respawn:/bin/su - postgres -c
              "/usr/local/pgsql/bin/postmaster -D/usr/local/pgsql/data
               /usr/local/pgsql/server.log 2&1 /dev/null"

          (The author of this example says this example will revive the
          postmaster if it dies, but he doesn't know if there are other side
          effects.)

 22. Run the regression tests. The file
     /usr/src/pgsql/src/test/regress/README has detailed instructions for
     running and interpreting the regression tests. A short version follows
     here:

       a. Type

          $ cd /usr/src/pgsql/src/test/regress
          $ gmake clean
          $ gmake all runtest

          You do not need to type gmake clean if this is the first time you
          are running the tests.

          You should get on the screen (and also written to file
          ./regress.out) a series of statements stating which tests passed
          and which tests failed. Please note that it can be normal for some
          tests to "fail" on some platforms. The script says a test has
          failed if there is any difference at all between the actual output
          of the test and the expected output. Thus, tests may "fail" due to
          minor differences in wording of error messages, small differences
          in floating-point roundoff, etc, between your system and the
          regression test reference platform. "Failures" of this type do not
          indicate a problem with Postgres. The file ./regression.diffs
          contains the textual differences between the actual test output on
          your machine and the "expected" output (which is simply what the
          reference system produced). You should carefully examine each
          difference listed to see whether it appears to be a significant
          issue.

          For example,

             + For a i686/Linux-ELF platform, no tests failed since this is
               the v6.5.1 regression testing reference platform.

          Even if a test result clearly indicates a real failure, it may be
          a localized problem that will not affect you. An example is that
          the int8 test will fail, producing obviously incorrect output, if
          your machine and C compiler do not provide a 64-bit integer data
          type (or if they do but configure didn't discover it). This is not
          something to worry about unless you need to store 64-bit integers.

          Conclusion? If you do see failures, try to understand the nature
          of the differences and then decide if those differences will
          affect your intended use of Postgres. The regression tests are a
          helpful tool, but they may require some study to be useful.

          After running the regression tests, type

          $ destroydb regression
          $ cd /usr/src/pgsql/src/test/regress
          $ gmake clean

          to recover the disk space used for the tests. (You may want to
          save the regression.diffs file in another place before doing
          this.)

 23. If you haven't already done so, this would be a good time to modify
     your computer to do regular maintainence. The following should be done
     at regular intervals:

     Minimal Backup Procedure

       1. Run the SQL command VACUUM. This will clean up your database.

       2. Back up your system. (You should probably keep the last few
          backups on hand.) Preferably, no one else should be using the
          system at the time.

     Ideally, the above tasks should be done by a shell script that is run
     nightly or weekly by cron. Look at the man page for crontab for a
     starting point on how to do this. (If you do it, please e-mail us a
     copy of your shell script. We would like to set up our own systems to
     do this too.)

 24. If you are upgrading an existing system then reinstall your old
     database. Type

     $ cd
     $ psql -e template1 < db.out

     If your pre-v6.2 database uses either path or polygon geometric data
     types, then you will need to upgrade any columns containing those
     types. To do so, type (from within psql)

     UPDATE FirstTable SET PathCol = UpgradePath(PathCol);
     UPDATE SecondTable SET PathCol = UpgradePath(PathCol);
     ...
     VACUUM;

     UpgradePath() checks to see that a path value is consistant with the
     old syntax, and will not update a column which fails that examination.
     UpgradePoly() cannot verify that a polygon is in fact from an old
     syntax, but RevertPoly() is provided to reverse the effects of a
     mis-applied upgrade.

 25. If you are a new user, you may wish to play with Postgres as described
     below.

 26. Clean up after yourself. Type

     $ rm -rf /usr/src/pgsql_6_5
     $ rm -rf /usr/local/pgsql_6_5
     # Also delete old database directory tree if it is not in
     #  /usr/local/pgsql_6_5/data
     $ rm ~/postgresql-v6.5.1.tar.gz

 27. You will probably want to print out the documentation. If you have a
     Postscript printer, or have your machine already set up to accept
     Postscript files using a print filter, then to print the User's Guide
     simply type

     $ cd /usr/local/pgsql/doc
     $ gunzip user.ps.tz | lpr

     Here is how you might do it if you have Ghostscript on your system and
     are writing to a laserjet printer.

     $ alias gshp='gs -sDEVICE=laserjet -r300 -dNOPAUSE'
     $ export GS_LIB=/usr/share/ghostscript:/usr/share/ghostscript/fonts
     $ gunzip user.ps.gz
     $ gshp -sOUTPUTFILE=user.hp user.ps
     $ gzip user.ps
     $ lpr -l -s -r manpage.hp

 28. The Postgres team wants to keep Postgres working on all of the
     supported platforms. We therefore ask you to let us know if you did or
     did not get Postgres to work on you system. Please send a mail message
     to pgsql-ports@postgresql.org telling us the following:

        o The version of Postgres (v6.5.1, 6.5, beta 990318, etc.).

        o Your operating system (i.e. RedHat v5.1 Linux v2.0.34).

        o Your hardware (SPARC, i486, etc.).

        o Did you compile, install and run the regression tests cleanly? If
          not, what source code did you change (i.e. patches you applied,
          changes you made, etc.), what tests failed, etc. It is normal to
          get many warning when you compile. You do not need to report
          these.

 29. Now create, access and manipulate databases as desired. Write client
     programs to access the database server. In other words, enjoy!

  ------------------------------------------------------------------------
Prev                                Home                                Next
Installation                                           Playing with Postgres

В списке pgsql-docs по дате отправления:

Предыдущее
От: Bruce Momjian
Дата:
Сообщение: INSTALL file - new version
Следующее
От: "Oliver Elphick"
Дата:
Сообщение: Re: [ADMIN] user auth & passwords