Thread: [BUGS] BUG #14814: Documentation errors for OpenBSD
The following bug has been logged on the website: Bug reference: 14814 Logged by: Paul Covello Email address: pfcovello@gmail.com PostgreSQL version: 9.6.2 Operating system: OpenBSD 6.1 Description: In section 18.3. Starting the Database Server there are instructions for starting the server on OpenBSD: if [ -x /usr/local/pgsql/bin/pg_ctl -a -x /usr/local/pgsql/bin/postgres ]; then su -l postgres -c '/usr/local/pgsql/bin/pg_ctl start -s -l /var/postgresql/log -D /usr/local/pgsql/data' echo -n ' postgresql' fi However, there are several problems with this instruction. First, the postgres user on openbsd is _postgresql (all daemon accounts begin with an underscore). Second, the path to the pg_ctl and postgres files are wrong. Finally, the part where the script sets where the log file and database are do not match with the readme that comes in the package, causing postgress to error out. Here is a correct copy of the rc.local file that correctly starts the postgres server at boot: if [ -x /usr/local/bin/pg_ctl -a -x /usr/local/bin/postgres ]; then su -l _postgresql -c '/usr/local/bin/pg_ctl start -s-l /var/postgresql/logfile -D /var/postgresql/data' echo -n ' postgresql' fi Please update the documentation as I hope this will save users like myself considerable time troubleshooting this issue as the documentation was incorrect. Thank you! -- Paul Covello. -- Sent via pgsql-bugs mailing list (pgsql-bugs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-bugs
pfcovello@gmail.com writes:
> In section 18.3. Starting the Database Server there are instructions for
> starting the server on OpenBSD:
> ...
> However, there are several problems with this instruction.
You seem to want us to adjust the community documentation to match
someone's packaging of Postgres. We can't really track every random
decision that packagers make; and if we tried, then the documentation
would be inaccurate for installations built directly from source.
Really, best practice for a packager who is modifying the default
configuration like this is to also modify the copy of the documentation
they ship, or at least make it very plain in a README file how their
installation differs from the out-of-the-box defaults.
In short, I think you've got a complaint for your packager here,
not one for the PG community.
regards, tom lane
--
Sent via pgsql-bugs mailing list (pgsql-bugs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-bugs
Thanks for the response, Tom. I am cc’ing the OpenBSD port maintainer here just for visibility. Port maintainer: I am not a developer or even a DBA. I am just an end user learning to set up PostGresql on OpenBSD 6.1. After installingthe package using pkg_add, I began to delve into the documentation at postgresql.org. I got to this section on starting the server: https://www.postgresql.org/docs/9.6/static/server-start.html The documentation did not match my experience (postgresql did not start) which prompted me to file a postgresql bug report#14814 on the documentation. Specifically, the instructions on what to put in rc.local for openbsd in the documentation says this: if [ -x /usr/local/pgsql/bin/pg_ctl -a -x /usr/local/pgsql/bin/postgres ]; then su -l postgres -c '/usr/local/pgsql/bin/pg_ctlstart -s -l /var/postgresql/log -D /usr/local/pgsql/data' echo -n ' postgresql' fi However, after taking the time to troubleshoot: This is what winds up working: if [ -x /usr/local/bin/pg_ctl -a -x /usr/local/bin/postgres ]; then su -l _postgresql -c '/usr/local/bin/pg_ctl start -s-l /var/postgresql/logfile -D /var/postgresql/data' echo -n ' postgresql' fi Knowing that it is openbsd policy to have service names begin with an _ (underscore) and believing that the path listed tothe executable does not seem to match the hier man page on openbsd, I thought this might be a documentation bug. I want to save other users the time I spent figuring this out which is what brought me here. In Tom’s response to me below,he believes this to be a port issue. Thanks for looking into this! — Paul. > On Sep 13, 2017, at 8:54 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote: > > pfcovello@gmail.com writes: >> In section 18.3. Starting the Database Server there are instructions for >> starting the server on OpenBSD: >> ... >> However, there are several problems with this instruction. > > You seem to want us to adjust the community documentation to match > someone's packaging of Postgres. We can't really track every random > decision that packagers make; and if we tried, then the documentation > would be inaccurate for installations built directly from source. > > Really, best practice for a packager who is modifying the default > configuration like this is to also modify the copy of the documentation > they ship, or at least make it very plain in a README file how their > installation differs from the out-of-the-box defaults. > > In short, I think you've got a complaint for your packager here, > not one for the PG community. > > regards, tom lane -- Sent via pgsql-bugs mailing list (pgsql-bugs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-bugs
Hi Paul, (I'm keeping the post posting). Thanks for your message. I agree with Tom. The PostgreSQL's documentation must stay "generic". The PostgreSQL's package on OpenBSD already have a README file with all the OpenBSD specific instructions. You can find it in /usr/local/share/doc/pkg-readmes (or online version here: https://cvsweb.openbsd.org/cgi-bin/cvsweb/ports/databases/postgresql/pkg/README-server?rev=1.23&content-type=text/x-cvsweb-markup ) Feel free to ask me directly if you have any questions. Regards, On Wed, Sep 13, 2017 at 02:00:33PM -0500, Paul Covello wrote: > Thanks for the response, Tom. I am cc’ing the OpenBSD port maintainer here just for visibility. > > Port maintainer: > > I am not a developer or even a DBA. I am just an end user learning to set up PostGresql on OpenBSD 6.1. After installingthe package using pkg_add, I began to delve into the documentation at postgresql.org. > > I got to this section on starting the server: > > https://www.postgresql.org/docs/9.6/static/server-start.html > > > The documentation did not match my experience (postgresql did not start) which prompted me to file a postgresql bug report#14814 on the documentation. > > Specifically, the instructions on what to put in rc.local for openbsd in the documentation says this: > > if [ -x /usr/local/pgsql/bin/pg_ctl -a -x /usr/local/pgsql/bin/postgres ]; then > su -l postgres -c '/usr/local/pgsql/bin/pg_ctl start -s -l /var/postgresql/log -D /usr/local/pgsql/data' > echo -n ' postgresql' > fi > > However, after taking the time to troubleshoot: This is what winds up working: > > if [ -x /usr/local/bin/pg_ctl -a -x /usr/local/bin/postgres ]; then > su -l _postgresql -c '/usr/local/bin/pg_ctl start -s -l /var/postgresql/logfile -D /var/postgresql/data' > echo -n ' postgresql' > fi > > Knowing that it is openbsd policy to have service names begin with an _ (underscore) and believing that the path listedto the executable does not seem to match the hier man page on openbsd, I thought this might be a documentation bug. > > I want to save other users the time I spent figuring this out which is what brought me here. In Tom’s response to me below,he believes this to be a port issue. > > Thanks for looking into this! > > — Paul. > > > On Sep 13, 2017, at 8:54 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote: > > > > pfcovello@gmail.com writes: > >> In section 18.3. Starting the Database Server there are instructions for > >> starting the server on OpenBSD: > >> ... > >> However, there are several problems with this instruction. > > > > You seem to want us to adjust the community documentation to match > > someone's packaging of Postgres. We can't really track every random > > decision that packagers make; and if we tried, then the documentation > > would be inaccurate for installations built directly from source. > > > > Really, best practice for a packager who is modifying the default > > configuration like this is to also modify the copy of the documentation > > they ship, or at least make it very plain in a README file how their > > installation differs from the out-of-the-box defaults. > > > > In short, I think you've got a complaint for your packager here, > > not one for the PG community. > > > > regards, tom lane > -- Sent via pgsql-bugs mailing list (pgsql-bugs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-bugs
Hi Paul, (I'm keeping the post posting). Thanks for your message. I agree with Tom. The PostgreSQL's documentation must stay "generic". The PostgreSQL's package on OpenBSD already have a README file with all the OpenBSD specific instructions. You can find it in /usr/local/share/doc/pkg-readmes (or online version here: https://cvsweb.openbsd.org/cgi-bin/cvsweb/ports/databases/postgresql/pkg/README-server?rev=1.23&content-type=text/x-cvsweb-markup ) Feel free to ask me directly if you have any questions. Regards, On Thu, Sep 14, 2017 at 09:43:32AM +0200, Pierre-Emmanuel André wrote: > Hi Paul, > > (I'm keeping the post posting). > Thanks for your message. I agree with Tom. The PostgreSQL's documentation must stay "generic". > The PostgreSQL's package on OpenBSD already have a README file with all the OpenBSD specific instructions. > You can find it in /usr/local/share/doc/pkg-readmes (or online version here: > https://cvsweb.openbsd.org/cgi-bin/cvsweb/ports/databases/postgresql/pkg/README-server?rev=1.23&content-type=text/x-cvsweb-markup ) > > Feel free to ask me directly if you have any questions. > > Regards, > > > > On Wed, Sep 13, 2017 at 02:00:33PM -0500, Paul Covello wrote: > > Thanks for the response, Tom. I am cc’ing the OpenBSD port maintainer here just for visibility. > > > > Port maintainer: > > > > I am not a developer or even a DBA. I am just an end user learning to set up PostGresql on OpenBSD 6.1. After installingthe package using pkg_add, I began to delve into the documentation at postgresql.org. > > > > I got to this section on starting the server: > > > > https://www.postgresql.org/docs/9.6/static/server-start.html > > > > > > The documentation did not match my experience (postgresql did not start) which prompted me to file a postgresql bug report#14814 on the documentation. > > > > Specifically, the instructions on what to put in rc.local for openbsd in the documentation says this: > > > > if [ -x /usr/local/pgsql/bin/pg_ctl -a -x /usr/local/pgsql/bin/postgres ]; then > > su -l postgres -c '/usr/local/pgsql/bin/pg_ctl start -s -l /var/postgresql/log -D /usr/local/pgsql/data' > > echo -n ' postgresql' > > fi > > > > However, after taking the time to troubleshoot: This is what winds up working: > > > > if [ -x /usr/local/bin/pg_ctl -a -x /usr/local/bin/postgres ]; then > > su -l _postgresql -c '/usr/local/bin/pg_ctl start -s -l /var/postgresql/logfile -D /var/postgresql/data' > > echo -n ' postgresql' > > fi > > > > Knowing that it is openbsd policy to have service names begin with an _ (underscore) and believing that the path listedto the executable does not seem to match the hier man page on openbsd, I thought this might be a documentation bug. > > > > I want to save other users the time I spent figuring this out which is what brought me here. In Tom’s response to mebelow, he believes this to be a port issue. > > > > Thanks for looking into this! > > > > — Paul. > > > > > On Sep 13, 2017, at 8:54 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote: > > > > > > pfcovello@gmail.com writes: > > >> In section 18.3. Starting the Database Server there are instructions for > > >> starting the server on OpenBSD: > > >> ... > > >> However, there are several problems with this instruction. > > > > > > You seem to want us to adjust the community documentation to match > > > someone's packaging of Postgres. We can't really track every random > > > decision that packagers make; and if we tried, then the documentation > > > would be inaccurate for installations built directly from source. > > > > > > Really, best practice for a packager who is modifying the default > > > configuration like this is to also modify the copy of the documentation > > > they ship, or at least make it very plain in a README file how their > > > installation differs from the out-of-the-box defaults. > > > > > > In short, I think you've got a complaint for your packager here, > > > not one for the PG community. > > > > > > regards, tom lane > > -- Sent via pgsql-bugs mailing list (pgsql-bugs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-bugs