mirror of
https://github.com/ansible-collections/community.general.git
synced 2024-09-14 20:13:21 +02:00
postgresql_user: improve documentation (#872)
* postgresql_user: improve documentation * fix * Update plugins/modules/database/postgresql/postgresql_user.py Co-authored-by: Sandra McCann <samccann@redhat.com> * Update plugins/modules/database/postgresql/postgresql_user.py Co-authored-by: Sandra McCann <samccann@redhat.com> * Update plugins/modules/database/postgresql/postgresql_user.py Co-authored-by: Sandra McCann <samccann@redhat.com> * add suggested * fix * misc fix Co-authored-by: Sandra McCann <samccann@redhat.com>
This commit is contained in:
Andrew Klychkov
GitHub
parent
2b0879cdc4
commit
4c33e2ccb8
1 changed files with 41 additions and 43 deletions
|
|
@ -10,23 +10,17 @@ __metaclass__ = type
|
|||
DOCUMENTATION = r'''
|
||||
---
|
||||
module: postgresql_user
|
||||
short_description: Add or remove a user (role) from a PostgreSQL server instance
|
||||
short_description: Create, alter, or remove a user (role) from a PostgreSQL server instance
|
||||
description:
|
||||
- Adds or removes a user (role) from a PostgreSQL server instance
|
||||
- Creates, alters, or removes a user (role) from a PostgreSQL server instance
|
||||
("cluster" in PostgreSQL terminology) and, optionally,
|
||||
grants the user access to an existing database or tables.
|
||||
- A user is a role with login privilege.
|
||||
- The fundamental function of the module is to create, or delete, users from
|
||||
a PostgreSQL instances. Privilege assignment, or removal, is an optional
|
||||
step, which works on one database at a time. This allows for the module to
|
||||
be called several times in the same module to modify the permissions on
|
||||
different databases, or to grant permissions to already existing users.
|
||||
- A user cannot be removed until all the privileges have been stripped from
|
||||
the user. In such situation, if the module tries to remove the user it
|
||||
will fail. To avoid this from happening the fail_on_user option signals
|
||||
the module to try to remove the user, but if not possible keep going; the
|
||||
module will report if changes happened and separately if the user was
|
||||
removed or not.
|
||||
- You can also use it to grant or revoke user's privileges in a particular database.
|
||||
- You cannot remove a user while it still has any privileges granted to it in any database.
|
||||
- Set I(fail_on_user) to C(no) to make the module ignore failures when trying to remove a user.
|
||||
In this case, the module reports if changes happened as usual and separately reports
|
||||
whether the user has been removed or not.
|
||||
options:
|
||||
name:
|
||||
description:
|
||||
|
|
@ -39,33 +33,33 @@ options:
|
|||
description:
|
||||
- Set the user's password, before 1.4 this was required.
|
||||
- Password can be passed unhashed or hashed (MD5-hashed).
|
||||
- Unhashed password will automatically be hashed when saved into the
|
||||
database if C(encrypted) parameter is set, otherwise it will be save in
|
||||
- An unhashed password is automatically hashed when saved into the
|
||||
database if I(encrypted) is set, otherwise it is saved in
|
||||
plain text format.
|
||||
- When passing an MD5-hashed password it must be generated with the format
|
||||
- When passing an MD5-hashed password, you must generate it with the format
|
||||
C('str["md5"] + md5[ password + username ]'), resulting in a total of
|
||||
35 characters. An easy way to do this is C(echo "md5$(echo -n
|
||||
'verysecretpasswordJOE' | md5sum | awk '{print $1}')").
|
||||
- Note that if the provided password string is already in MD5-hashed
|
||||
format, then it is used as-is, regardless of C(encrypted) parameter.
|
||||
format, then it is used as-is, regardless of I(encrypted) option.
|
||||
type: str
|
||||
db:
|
||||
description:
|
||||
- Name of database to connect to and where user's permissions will be granted.
|
||||
- Name of database to connect to and where user's permissions are granted.
|
||||
type: str
|
||||
aliases:
|
||||
- login_db
|
||||
fail_on_user:
|
||||
description:
|
||||
- If C(yes), fail when user (role) can't be removed. Otherwise just log and continue.
|
||||
default: 'yes'
|
||||
- If C(yes), fails when the user (role) cannot be removed. Otherwise just log and continue.
|
||||
default: yes
|
||||
type: bool
|
||||
aliases:
|
||||
- fail_on_role
|
||||
priv:
|
||||
description:
|
||||
- "Slash-separated PostgreSQL privileges string: C(priv1/priv2), where
|
||||
privileges can be defined for database ( allowed options - 'CREATE',
|
||||
you can define the user's privileges for the database ( allowed options - 'CREATE',
|
||||
'CONNECT', 'TEMPORARY', 'TEMP', 'ALL'. For example C(CONNECT) ) or
|
||||
for table ( allowed options - 'SELECT', 'INSERT', 'UPDATE', 'DELETE',
|
||||
'TRUNCATE', 'REFERENCES', 'TRIGGER', 'ALL'. For example
|
||||
|
|
@ -82,9 +76,10 @@ options:
|
|||
'[NO]INHERIT', '[NO]LOGIN', '[NO]REPLICATION', '[NO]BYPASSRLS' ]
|
||||
session_role:
|
||||
description:
|
||||
- Switch to session_role after connecting.
|
||||
- The specified session_role must be a role that the current login_user is a member of.
|
||||
- Permissions checking for SQL commands is carried out as though the session_role were the one that had logged in originally.
|
||||
- Switch to session role after connecting.
|
||||
- The specified session role must be a role that the current login_user is a member of.
|
||||
- Permissions checking for SQL commands is carried out as though the session role
|
||||
were the one that had logged in originally.
|
||||
type: str
|
||||
state:
|
||||
description:
|
||||
|
|
@ -95,24 +90,26 @@ options:
|
|||
encrypted:
|
||||
description:
|
||||
- Whether the password is stored hashed in the database.
|
||||
- Passwords can be passed already hashed or unhashed, and postgresql
|
||||
ensures the stored password is hashed when C(encrypted) is set.
|
||||
- "Note: Postgresql 10 and newer doesn't support unhashed passwords."
|
||||
- You can specify an unhashed password, and PostgreSQL ensures
|
||||
the stored password is hashed when I(encrypted=yes) is set.
|
||||
If you specify a hashed password, the module uses it as-is,
|
||||
regardless of the setting of I(encrypted).
|
||||
- "Note: Postgresql 10 and newer does not support unhashed passwords."
|
||||
- Previous to Ansible 2.6, this was C(no) by default.
|
||||
default: 'yes'
|
||||
default: yes
|
||||
type: bool
|
||||
expires:
|
||||
description:
|
||||
- The date at which the user's password is to expire.
|
||||
- If set to C('infinity'), user's password never expire.
|
||||
- Note that this value should be a valid SQL date and time type.
|
||||
- If set to C('infinity'), user's password never expires.
|
||||
- Note that this value must be a valid SQL date and time type.
|
||||
type: str
|
||||
no_password_changes:
|
||||
description:
|
||||
- If C(yes), don't inspect database for password changes. Effective when
|
||||
C(pg_authid) is not accessible (such as AWS RDS). Otherwise, make
|
||||
password changes as necessary.
|
||||
default: 'no'
|
||||
- If C(yes), does not inspect the database for password changes.
|
||||
Useful when C(pg_authid) is not accessible (such as in AWS RDS).
|
||||
Otherwise, makes password changes as necessary.
|
||||
default: no
|
||||
type: bool
|
||||
conn_limit:
|
||||
description:
|
||||
|
|
@ -120,7 +117,7 @@ options:
|
|||
type: int
|
||||
ssl_mode:
|
||||
description:
|
||||
- Determines whether or with what priority a secure SSL TCP/IP connection will be negotiated with the server.
|
||||
- Determines how an SSL session is negotiated with the server.
|
||||
- See U(https://www.postgresql.org/docs/current/static/libpq-ssl.html) for more information on the modes.
|
||||
- Default of C(prefer) matches libpq default.
|
||||
type: str
|
||||
|
|
@ -129,36 +126,37 @@ options:
|
|||
ca_cert:
|
||||
description:
|
||||
- Specifies the name of a file containing SSL certificate authority (CA) certificate(s).
|
||||
- If the file exists, the server's certificate will be verified to be signed by one of these authorities.
|
||||
- If the file exists, verifies that the server's certificate is signed by one of these authorities.
|
||||
type: str
|
||||
aliases: [ ssl_rootcert ]
|
||||
groups:
|
||||
description:
|
||||
- The list of groups (roles) that need to be granted to the user.
|
||||
- The list of groups (roles) that you want to grant to the user.
|
||||
type: list
|
||||
elements: str
|
||||
comment:
|
||||
description:
|
||||
- Add a comment on the user (equal to the COMMENT ON ROLE statement result).
|
||||
- Adds a comment on the user (equivalent to the C(COMMENT ON ROLE) statement).
|
||||
type: str
|
||||
version_added: '0.2.0'
|
||||
trust_input:
|
||||
description:
|
||||
- If C(no), check whether values of parameters I(name), I(password), I(privs), I(expires),
|
||||
- If C(no), checks whether values of options I(name), I(password), I(privs), I(expires),
|
||||
I(role_attr_flags), I(groups), I(comment), I(session_role) are potentially dangerous.
|
||||
- It makes sense to use C(yes) only when SQL injections via the parameters are possible.
|
||||
- It makes sense to use C(yes) only when SQL injections through the options are possible.
|
||||
type: bool
|
||||
default: yes
|
||||
version_added: '0.2.0'
|
||||
notes:
|
||||
- The module creates a user (role) with login privilege by default.
|
||||
Use NOLOGIN role_attr_flags to change this behaviour.
|
||||
- If you specify PUBLIC as the user (role), then the privilege changes will apply to all users (roles).
|
||||
You may not specify password or role_attr_flags when the PUBLIC user is specified.
|
||||
Use C(NOLOGIN) I(role_attr_flags) to change this behaviour.
|
||||
- If you specify C(PUBLIC) as the user (role), then the privilege changes apply to all users (roles).
|
||||
You may not specify password or role_attr_flags when the C(PUBLIC) user is specified.
|
||||
- SCRAM-SHA-256-hashed passwords (SASL Authentication) require PostgreSQL version 10 or newer.
|
||||
On the previous versions the whole hashed string is used as a password.
|
||||
- 'Working with SCRAM-SHA-256-hashed passwords, be sure you use the I(environment:) variable
|
||||
C(PGOPTIONS: "-c password_encryption=scram-sha-256") (see the provided example).'
|
||||
- Supports ``check_mode``.
|
||||
seealso:
|
||||
- module: community.general.postgresql_privs
|
||||
- module: community.general.postgresql_membership
|
||||
|
|
|
|||
Loading…
Reference in a new issue