Document changes in default access control

docs/src/main/sphinx/admin/graceful-shutdown.rst

@@ -23,9 +23,12 @@ Keep the following aspects in mind:
 * If you have TLS/HTTPS enabled, you have to ensure the worker certificate is
   CA signed, or trusted by the server calling the shut down endpoint.
   Otherwise, you can make the call ``--insecure``, but that isn't recommended.
-* If :ref:`system information rules <system-file-auth-system_information>` are
-  configured, then the user in the HTTP request must have read and write
-  permissions in the system information rules.
+* The ``default`` :doc:`/security/built-in-system-access-control` does not allow
+  graceful shutdowns. You can use the ``allow-all`` system access control, or
+  configure :ref:`system information rules
+  <system-file-auth-system_information>` with the ``file`` system access
+  control. These configuration must be present on all workers.
+
 
 Shutdown behavior
 -----------------

docs/src/main/sphinx/release/release-414.md

@@ -20,10 +20,11 @@
 
 ## Security
 
-* Disallow writing system information with the `default` system access control.
-  System information writes can be re-enabled by setting the
-  `access-control.name` configuration property to `allow-all`, or by configuring
-  [system information rules](system-file-auth-system_information). ({issue}`17105`)
+* Disallow [graceful shutdown](/admin/graceful-shutdown) with the `default`
+  [system access control](/security/built-in-system-access-control). Shutdowns
+  can be re-enabled by using the `allow-all` system access control, or by
+  configuring [system information rules](system-file-auth-system_information)
+  with the `file` system access control. ({issue}`17105`)
 
 ## Delta Lake connector
 

docs/src/main/sphinx/security/built-in-system-access-control.rst

@@ -7,31 +7,48 @@ before any connector level authorization. You can use one of the built-in
 implementations in Trino, or provide your own by following the guidelines in
 :doc:`/develop/system-access-control`.
 
+To use a system access control, add an ``etc/access-control.properties`` file
+with the following content and the desired system access control name on all
+cluster nodes:
+
+.. code-block:: text
+
+   access-control.name=allow-all
+
 Multiple system access control implementations may be configured at once
 using the ``access-control.config-files`` configuration property. It should
 contain a comma separated list of the access control property files to use
 (rather than the default ``etc/access-control.properties``).
 
-Trino offers the following built-in implementations:
-
-================================================== =================================================================
-System access control name                         Description
-================================================== =================================================================
-``default``                                        All operations are permitted, except for user impersonation.
-                                                   This is the default access control if none are configured.
+Trino offers the following built-in system access control implementations:
 
-``allow-all``                                      All operations are permitted.
+.. list-table::
+  :widths: 20, 80
+  :header-rows: 1
 
-``read-only``                                      Operations that read data or metadata are permitted, but
-                                                   none of the operations that write data or metadata are allowed.
+  * - Name
+    - Description
+  * - ``default``
+    - All operations are permitted, except for user impersonation and triggering
+      :doc:`/admin/graceful-shutdown`.
 
-``file``                                           Authorization rules are specified in a config file.
-                                                   See :doc:`file-system-access-control`.
-================================================== =================================================================
+      This is the default access control if none are configured.
+  * - ``allow-all``
+    - All operations are permitted.
+  * - ``read-only``
+    - Operations that read data or metadata are permitted, but none of the
+      operations that write data or metadata are allowed.
+  * - ``file``
+    - Authorization rules are specified in a config file. See
+      :doc:`file-system-access-control`.
 
 If you want to limit access on a system level in any other way than the ones
 listed above, you must implement a custom :doc:`/develop/system-access-control`.
 
+Access control must be configured on the coordinator. Authorization for
+operations on specific worker nodes, such a triggering
+:doc:`/admin/graceful-shutdown`, must also be configured on all workers.
+
 Read only system access control
 ===============================
 

docs/src/main/sphinx/security/file-system-access-control.rst

@@ -684,23 +684,37 @@ System information rules
 ------------------------
 
 These rules specify which users can access the system information management
-interface. The user is granted or denied access, based on the first matching
+interface. System information access includes the following aspects:
+
+* Read access to details such as Trino version, uptime of the node, and others
+  from the ``/v1/info`` and ``/v1/status`` REST endpoints.
+* Read access with the :doc:`system information functions </functions/system>`.
+* Read access with the :doc:`/connector/system`.
+* Write access to trigger :doc:`/admin/graceful-shutdown`.
+
+The user is granted or denied access based on the first matching
 rule read from top to bottom. If no rules are specified, all access to system
 information is denied. If no rule matches, system access is denied. Each rule is
 composed of the following fields:
 
+* ``role`` (optional): regex to match against role. If matched, it
+  grants or denies the authorization based on the value of ``allow``.
 * ``user`` (optional): regex to match against user name. If matched, it
   grants or denies the authorization based on the value of ``allow``.
 * ``allow`` (required): set of access permissions granted to user. Values:
   ``read``, ``write``
 
-For example, if you want to allow only the role ``admin`` to read and write
-system information, allow ``alice`` to read system information, and deny all
-other access, you can use the following rules:
+The following configuration provides and example:
 
 .. literalinclude:: system-information-access.json
     :language: json
 
+* All users with the ``admin`` role have read and write access to system
+  information. This includes the ability to trigger
+  :doc:`/admin/graceful-shutdown`.
+* The user ``alice`` can read system information.
+* All other users and roles are denied access to system information.
+
 A fixed user can be set for management interfaces using the ``management.user``
 configuration property.  When this is configured, system information rules must
 still be set to authorize this user to read or write to management information.