Обсуждение: order of entries in admin docs
I was just looking for something in the admin docs, and it seems like the ordering of sections is sub-optimal. 17. Operating System Environment 18. Server Configuration 19. Database Roles and Privileges 20. Managing Databases 21. Client Authentication Seems that Client Authentication should come right after Server Configuration. After all, how is someone going to handle roles and database creation before they've authenticated? Is there some reason for the order that I'm missing? Is it an easy change? I'd be happy to try and make a patch for something like that if there's a chance of it getting through / my figuring out how to do it in the docs.
Scott Marlowe escribió: > Seems that Client Authentication should come right after Server > Configuration. After all, how is someone going to handle roles and > database creation before they've authenticated? Is there some reason > for the order that I'm missing? Is it an easy change? I'd be happy > to try and make a patch for something like that if there's a chance of > it getting through / my figuring out how to do it in the docs. Yeah, see postgres.sgml -- changing the order is just a matter of moving where the entries appear. The current order is probably just historical. -- Alvaro Herrera http://www.CommandPrompt.com/ PostgreSQL Replication, Consulting, Custom Development, 24x7 support
"Scott Marlowe" <scott.marlowe@gmail.com> writes:
> I was just looking for something in the admin docs, and it seems like
> the ordering of sections is sub-optimal.
> 17. Operating System Environment
> 18. Server Configuration
> 19. Database Roles and Privileges
> 20. Managing Databases
> 21. Client Authentication
> Seems that Client Authentication should come right after Server
> Configuration. After all, how is someone going to handle roles and
> database creation before they've authenticated?
Well, until you know what a role is, the client auth discussion might
not make too much sense to you...
I'm not wedded to the current ordering but I'm not sure it's silly
either.
Something else that ought to be considered here is that now that we have
CONNECT privilege for databases, manipulating privileges is a lot saner
way to control who-can-connect-where than setting up fancy combinations
of user and database entries in pg_hba.conf. AFAIR there is no mention
of this alternative in Chapter 21, but it seems like there ought to be.
With your proposed reorganization, that would become a forward
reference; is that OK?
regards, tom lane
On Tue, Mar 11, 2008 at 10:36 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
> "Scott Marlowe" <scott.marlowe@gmail.com> writes:
> > I was just looking for something in the admin docs, and it seems like
> > the ordering of sections is sub-optimal.
>
> > 17. Operating System Environment
> > 18. Server Configuration
> > 19. Database Roles and Privileges
> > 20. Managing Databases
> > 21. Client Authentication
>
> > Seems that Client Authentication should come right after Server
> > Configuration. After all, how is someone going to handle roles and
> > database creation before they've authenticated?
>
> Well, until you know what a role is, the client auth discussion might
> not make too much sense to you...
>
> I'm not wedded to the current ordering but I'm not sure it's silly
> either.
>
> Something else that ought to be considered here is that now that we have
> CONNECT privilege for databases, manipulating privileges is a lot saner
> way to control who-can-connect-where than setting up fancy combinations
> of user and database entries in pg_hba.conf. AFAIR there is no mention
> of this alternative in Chapter 21, but it seems like there ought to be.
> With your proposed reorganization, that would become a forward
> reference; is that OK?
I've deleted and rewritten this email like 4 times...
The more I read the docs, the more moving client authentication seems
to make sense. In fact, the authentication problems section is
probably the perfect final bit to the Connections and Authentication
section. I'd move it up a level, so that it looked something like
this:
18.3. Connections and Authentication
18.3.1. Connection Settings
18.3.2. Security and Authentication
18.3.3. The pg_hba.conf file
18.3.4. Authentication methods
18.3.5. Authentication problems
Unless a different level of indentation makes more sense, which I
could totally understand.
It definitely follows the flow of setting up a pg server better for
me. I might even move the pg_hba.conf file to 18.3.1 up there. It is
pretty much a firewall.
Tom Lane wrote:
> Something else that ought to be considered here is that now that we have
> CONNECT privilege for databases, manipulating privileges is a lot saner
> way to control who-can-connect-where than setting up fancy combinations
> of user and database entries in pg_hba.conf. AFAIR there is no mention
> of this alternative in Chapter 21, but it seems like there ought to be.
> With your proposed reorganization, that would become a forward
> reference; is that OK?
We do have a "Tip" about this in the pg_hba.conf section:
http://developer.postgresql.org/pgdocs/postgres/auth-pg-hba-conf.html
Tip: To connect to a particular database, a user must not only pass the
pg_hba.conf checks, but must have the CONNECT privilege for the
database. If you wish to restrict which users can connect to which
databases, it's usually easier to control this by granting/revoking
CONNECT privilege than to put the rules into pg_hba.conf entries.
Do we need more?
--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
+ If your life is a hard drive, Christ can be your backup. +
Scott Marlowe wrote: > I was just looking for something in the admin docs, and it seems like > the ordering of sections is sub-optimal. > > 17. Operating System Environment > 18. Server Configuration > 19. Database Roles and Privileges > 20. Managing Databases > 21. Client Authentication > > Seems that Client Authentication should come right after Server > Configuration. After all, how is someone going to handle roles and > database creation before they've authenticated? Is there some reason > for the order that I'm missing? Is it an easy change? I'd be happy > to try and make a patch for something like that if there's a chance of > it getting through / my figuring out how to do it in the docs. Agreed, section moved by attached patch. The new ordering makes more sense because you can't do much database management until you have client authentication setup properly. I bet this will reduce the number of people who don't realize they need to modify pg_hba.conf. -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + If your life is a hard drive, Christ can be your backup. + Index: doc/src/sgml/postgres.sgml =================================================================== RCS file: /cvsroot/pgsql/doc/src/sgml/postgres.sgml,v retrieving revision 1.85 diff -c -c -r1.85 postgres.sgml *** doc/src/sgml/postgres.sgml 14 Nov 2007 02:36:43 -0000 1.85 --- doc/src/sgml/postgres.sgml 7 May 2008 16:35:20 -0000 *************** *** 146,154 **** &installw; &runtime; &config; &user-manag; &manage-ag; - &client-auth; &charset; &maintenance; &backup; --- 146,154 ---- &installw; &runtime; &config; + &client-auth; &user-manag; &manage-ag; &charset; &maintenance; &backup;
Scott Marlowe wrote: > The more I read the docs, the more moving client authentication seems > to make sense. In fact, the authentication problems section is > probably the perfect final bit to the Connections and Authentication > section. I'd move it up a level, so that it looked something like > this: > > 18.3. Connections and Authentication > > 18.3.1. Connection Settings > 18.3.2. Security and Authentication > 18.3.3. The pg_hba.conf file > 18.3.4. Authentication methods > 18.3.5. Authentication problems > > Unless a different level of indentation makes more sense, which I > could totally understand. > > It definitely follows the flow of setting up a pg server better for > me. I might even move the pg_hba.conf file to 18.3.1 up there. It is > pretty much a firewall. I don't think this change makes sense --- All the "Connection Settings" stuff is in postgresql.conf. Pulling authentication in there will be too complex, I am afraid. -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + If your life is a hard drive, Christ can be your backup. +
On Wed, May 7, 2008 at 10:39 AM, Bruce Momjian <bruce@momjian.us> wrote: > Scott Marlowe wrote: > > The more I read the docs, the more moving client authentication seems > > to make sense. In fact, the authentication problems section is > > probably the perfect final bit to the Connections and Authentication > > section. I'd move it up a level, so that it looked something like > > this: > > > > 18.3. Connections and Authentication > > > > 18.3.1. Connection Settings > > 18.3.2. Security and Authentication > > 18.3.3. The pg_hba.conf file > > 18.3.4. Authentication methods > > 18.3.5. Authentication problems > > > > Unless a different level of indentation makes more sense, which I > > could totally understand. > > > > It definitely follows the flow of setting up a pg server better for > > me. I might even move the pg_hba.conf file to 18.3.1 up there. It is > > pretty much a firewall. > > I don't think this change makes sense --- All the "Connection Settings" > stuff is in postgresql.conf. Pulling authentication in there will be too > complex, I am afraid. Well, if you say so. It seems like a natural part of it to me, but the modifications required to move things like that are pretty big, and I really don't feel comfortable enough in sgml to get it right. The other move still makes more sense to me than the way it was originally though.
Scott Marlowe wrote:
> On Wed, May 7, 2008 at 10:39 AM, Bruce Momjian <bruce@momjian.us> wrote:
> > Scott Marlowe wrote:
> > > The more I read the docs, the more moving client authentication seems
> > > to make sense. In fact, the authentication problems section is
> > > probably the perfect final bit to the Connections and Authentication
> > > section. I'd move it up a level, so that it looked something like
> > > this:
> > >
> > > 18.3. Connections and Authentication
> > >
> > > 18.3.1. Connection Settings
> > > 18.3.2. Security and Authentication
> > > 18.3.3. The pg_hba.conf file
> > > 18.3.4. Authentication methods
> > > 18.3.5. Authentication problems
> > >
> > > Unless a different level of indentation makes more sense, which I
> > > could totally understand.
> > >
> > > It definitely follows the flow of setting up a pg server better for
> > > me. I might even move the pg_hba.conf file to 18.3.1 up there. It is
> > > pretty much a firewall.
> >
> > I don't think this change makes sense --- All the "Connection Settings"
> > stuff is in postgresql.conf. Pulling authentication in there will be too
> > complex, I am afraid.
>
> Well, if you say so. It seems like a natural part of it to me, but
> the modifications required to move things like that are pretty big,
> and I really don't feel comfortable enough in sgml to get it right.
Right now we have all postgresql.conf documentation in the same chapter.
To move it would split that up, which I think is confusing.
> The other move still makes more sense to me than the way it was
> originally though.
I did move the Authentication chapter up to after Configuration
Settings so the order now is:
17. Operating System Environment
18. Server Configuration
19. Client Authentication
20. Database Roles and Privileges
21. Managing Databases
22. Localization
--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
+ If your life is a hard drive, Christ can be your backup. +
Bruce Momjian escribió: > Scott Marlowe wrote: > > Well, if you say so. It seems like a natural part of it to me, but > > the modifications required to move things like that are pretty big, > > and I really don't feel comfortable enough in sgml to get it right. > > Right now we have all postgresql.conf documentation in the same chapter. > To move it would split that up, which I think is confusing. Perhaps it would be better to have prose explaining all the stuff structured like Scott proposes, and make the postgresql.conf be just a reference linking to that. I don't think making postgresql.conf be the primary documentation is very nice. -- Alvaro Herrera http://www.CommandPrompt.com/ The PostgreSQL Company - Command Prompt, Inc.
Alvaro Herrera wrote: > Bruce Momjian escribi?: > > Scott Marlowe wrote: > > > > Well, if you say so. It seems like a natural part of it to me, but > > > the modifications required to move things like that are pretty big, > > > and I really don't feel comfortable enough in sgml to get it right. > > > > Right now we have all postgresql.conf documentation in the same chapter. > > To move it would split that up, which I think is confusing. > > Perhaps it would be better to have prose explaining all the stuff > structured like Scott proposes, and make the postgresql.conf be just a > reference linking to that. I don't think making postgresql.conf be the > primary documentation is very nice. So you are suggesting splitting out the postgresql.conf content into its relevant sections and just linking to it? That would work. -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + If your life is a hard drive, Christ can be your backup. +
Bruce Momjian escribió: > Alvaro Herrera wrote: > > Bruce Momjian escribi?: > > > Scott Marlowe wrote: > > > > > > Well, if you say so. It seems like a natural part of it to me, but > > > > the modifications required to move things like that are pretty big, > > > > and I really don't feel comfortable enough in sgml to get it right. > > > > > > Right now we have all postgresql.conf documentation in the same chapter. > > > To move it would split that up, which I think is confusing. > > > > Perhaps it would be better to have prose explaining all the stuff > > structured like Scott proposes, and make the postgresql.conf be just a > > reference linking to that. I don't think making postgresql.conf be the > > primary documentation is very nice. > > So you are suggesting splitting out the postgresql.conf content into its > relevant sections and just linking to it? That would work. Yes, or something like that. I don't think leaving _just_ the links on the postgresql.conf would be enough. But a comprehensive, verbose explanation should be elsewhere; a short blurb and the link would remain on the postgresql.conf reference. -- Alvaro Herrera http://www.CommandPrompt.com/ The PostgreSQL Company - Command Prompt, Inc.
Alvaro Herrera wrote:
> > > Perhaps it would be better to have prose explaining all the stuff
> > > structured like Scott proposes, and make the postgresql.conf be just a
> > > reference linking to that. I don't think making postgresql.conf be the
> > > primary documentation is very nice.
> >
> > So you are suggesting splitting out the postgresql.conf content into its
> > relevant sections and just linking to it? That would work.
>
> Yes, or something like that. I don't think leaving _just_ the links on
> the postgresql.conf would be enough. But a comprehensive, verbose
> explanation should be elsewhere; a short blurb and the link would remain
> on the postgresql.conf reference.
Yea, that's certainly possible, though right now we pretty much have
_all_ the information about each configuration value in one place. We
would lose that. Looking at the connection postgresql.conf docs:
http://developer.postgresql.org/pgdocs/postgres/runtime-config-connection.html
There isn't much additional text except a description of each item.
--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
+ If your life is a hard drive, Christ can be your backup. +
Bruce Momjian wrote: > There isn't much additional text except a description of each item. That's the way it should be: Each parameter explains what it does. There can be more extensive documentation about how they all fit together elsewhere. What I would like to see is getting rid of the sections the parameters are grouped in and put them all in alphabetical order. I find the current arrangement completely unusable; nine times out of ten I cannot find the right section. The topical grouping of the options would be the job of the more extensive documentation elsewhere I mentioned above. I think Postfix has arranged this nicely: http://www.postfix.org/documentation.html -- You have various sections explaining how to configure for various jobs, and one big list of all parameters explained.
Peter Eisentraut escribió: > What I would like to see is getting rid of the sections the parameters are > grouped in and put them all in alphabetical order. I find the current > arrangement completely unusable; nine times out of ten I cannot find the > right section. The topical grouping of the options would be the job of the > more extensive documentation elsewhere I mentioned above. +1. That's what I was imagining. -- Alvaro Herrera http://www.CommandPrompt.com/ PostgreSQL Replication, Consulting, Custom Development, 24x7 support
2008/5/8 Peter Eisentraut <peter_e@gmx.net>: > Bruce Momjian wrote: >> There isn't much additional text except a description of each item. > > That's the way it should be: Each parameter explains what it does. There can > be more extensive documentation about how they all fit together elsewhere. > > What I would like to see is getting rid of the sections the parameters are > grouped in and put them all in alphabetical order. I find the current > arrangement completely unusable; nine times out of ten I cannot find the > right section. The topical grouping of the options would be the job of the > more extensive documentation elsewhere I mentioned above. > > I think Postfix has arranged this nicely: > http://www.postfix.org/documentation.html -- You have various sections > explaining how to configure for various jobs, and one big list of all > parameters explained. > > -- > Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org) > To make changes to your subscription: > http://www.postgresql.org/mailpref/pgsql-docs > -- http://sql-info.de/index.html
(Whoops, apologies for the blank mail, I clicked on "send" by accident) Ian Barwick