From c0f753dd214f96d461344a06e8d7ab4fd1a70bee Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Fri, 18 Sep 2020 06:11:50 +0200 Subject: [PATCH] postgresql_user: improve documentation (#872) (#928) * postgresql_user: improve documentation * fix * Update plugins/modules/database/postgresql/postgresql_user.py Co-authored-by: Sandra McCann * Update plugins/modules/database/postgresql/postgresql_user.py Co-authored-by: Sandra McCann * Update plugins/modules/database/postgresql/postgresql_user.py Co-authored-by: Sandra McCann * add suggested * fix * misc fix Co-authored-by: Sandra McCann (cherry picked from commit 4c33e2ccb84a0f82dd733b761aac667514af4554) Co-authored-by: Andrew Klychkov --- .../database/postgresql/postgresql_user.py | 84 +++++++++---------- 1 file changed, 41 insertions(+), 43 deletions(-) diff --git a/plugins/modules/database/postgresql/postgresql_user.py b/plugins/modules/database/postgresql/postgresql_user.py index b0ca7368d1..f6d753b290 100644 --- a/plugins/modules/database/postgresql/postgresql_user.py +++ b/plugins/modules/database/postgresql/postgresql_user.py @@ -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