From 07580692f55b9bac50538cd0b765d40faa20fed7 Mon Sep 17 00:00:00 2001 From: Pepe Barbe Date: Mon, 27 Aug 2012 10:53:01 -0500 Subject: [PATCH] Update documentation for postgresql_user --- rst/modules/postgresql_user.rst | 31 +++++++++++++++++++++++++++---- 1 file changed, 27 insertions(+), 4 deletions(-) diff --git a/rst/modules/postgresql_user.rst b/rst/modules/postgresql_user.rst index 0733418c828..2e0e24524ea 100644 --- a/rst/modules/postgresql_user.rst +++ b/rst/modules/postgresql_user.rst @@ -5,8 +5,8 @@ postgresql_user .. versionadded:: 0.6 -Add or remove PostgreSQL users (roles) from a remote host, and grant the users -access to an existing database. +Add or remove PostgreSQL users (roles) from a remote host and, optionally, grant the users +access to an existing database or tables. The default authentication assumes that you are either logging in as or sudo'ing to the postgres account on the host. @@ -25,7 +25,11 @@ host before using this module. +--------------------+----------+----------+----------------------------------------------------------------------------+ | password | yes | | set the user's password | +--------------------+----------+----------+----------------------------------------------------------------------------+ -| db | yes | | name of an existing database to grant user access to | +| db | no | | name of database where permissions will be granted | ++--------------------+----------+----------+----------------------------------------------------------------------------+ +| priv | no | | PostgreSQL privileges string in the format: table:priv1,priv2 | ++--------------------+----------+----------+----------------------------------------------------------------------------+ +| fail_on_user | no | yes | if yes, fail when user can't be removed. Otherwise just log and continue | +--------------------+----------+----------+----------------------------------------------------------------------------+ | login_user | no | postgres | user (role) used to authenticate with PostgreSQL | +--------------------+----------+----------+----------------------------------------------------------------------------+ @@ -36,7 +40,26 @@ host before using this module. | state | | present | 'absent' or 'present' | +--------------------+----------+----------+----------------------------------------------------------------------------+ +The fundamental function of the module is to create, or delete, roles from a PostgreSQL cluster. +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 untill 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. + +Example privileges string format: + + INSERT,UPDATE/table:SELECT/anothertable:ALL Example action from Ansible :doc:`playbooks`:: - postgresql_user db=acme user=django password=ceec4eif7ya + - name: Create django user and grant access to database and products table + postgresql_user db=acme user=django password=ceec4eif7ya privs=CONNECT/products:ALL + + - name: Remove test user privileges from acme + postgresql_user db=acme user=test privs=ALL/products:ALL state=absent fail_on_user=no + - name: Remove test user from test database and the cluster + postgresql_user db=test user=test privs=ALL state=absent