Merge pull request wildfly#17826 from bstansberry/admin_guide

[WFLY-19178][WFLY-19179][WFLY-19249][WFLY-19250] Admin guide improvements
rhusar · Apr 19, 2024 · 323dabe · 323dabe
2 parents 4cc8401 + bed2c2f
commit 323dabe
Show file tree

Hide file tree

Showing 36 changed files with 81 additions and 98 deletions.
diff --git a/docs/src/main/asciidoc/Admin_Guide.adoc b/docs/src/main/asciidoc/Admin_Guide.adoc
@@ -68,7 +68,7 @@ include::_admin-guide/Domain_Setup.adoc[]
 
 include::_admin-guide/Management_tasks.adoc[]
 
-include::_admin-guide/Management_API_reference.adoc[]
-
 include::_admin-guide/CLI_Recipes.adoc[]
 
+include::_admin-guide/Management_API_reference.adoc[]
+
diff --git a/docs/src/main/asciidoc/_admin-guide/Command_Line_Interface.adoc b/docs/src/main/asciidoc/_admin-guide/Command_Line_Interface.adoc
@@ -270,22 +270,6 @@ configuration value sets the timeout to its default value (0 seconds).
 [standalone@localhost:9990 /] command-timeout reset default
 ----
 
-[[default-native-management-interface-security]]
-== Default Native Management Interface Security
-
-The native interface shares the same security configuration as the http
-interface, however we also support a local authentication mechanism
-which means that the CLI can authenticate against the local WildFly
-instance without prompting the user for a username and password. This
-mechanism only works if the user running the CLI has read access to the
-standalone/tmp/auth folder or domain/tmp/auth folder under the
-respective WildFly installation - if the local mechanism fails then the
-CLI will fallback to prompting for a username and password for a user
-configured as in <<Default_HTTP_Interface_Security,Default HTTP Interface Security>>.
-
-Establishing a CLI connection to a remote server will require a username
-and password by default.
-
 [[operation-requests]]
 == Operation Requests
 

diff --git a/docs/src/main/asciidoc/_admin-guide/Management_Clients.adoc b/docs/src/main/asciidoc/_admin-guide/Management_Clients.adoc
@@ -216,6 +216,7 @@ standard variants:
 
 [cols=",",options="header"]
 |=======================================================================
+| Configuration file               | Use
 |host-primary.xml |A configuration that specifies the Host Controller
 should become the primary Host Controller, aka the Domain Controller.
 No servers will be started by this Host Controller, which is a recommended

diff --git a/docs/src/main/asciidoc/_admin-guide/Subsystem_configuration.adoc b/docs/src/main/asciidoc/_admin-guide/Subsystem_configuration.adoc
@@ -1,6 +1,6 @@
 [[Subsystem_configuration]]
 = Subsystem configuration
-Subsystem configuration reference
+
 :author: tcerar@redhat.com
 :icons: font
 :source-highlighter: coderay
@@ -17,80 +17,80 @@ endif::[]
 
 ifdef::basebackend-html[toc::[]]
 
-The following chapters will focus on the high level management use cases
+The following chapters will focus on the high level subsystem management use cases
 that are available through the CLI and the web interface. For a detailed
 description of each subsystem configuration property, please consult the
 respective component reference.
 
-Schema Location
 
-TIP: The configuration schemas can found in `$JBOSS_HOME/docs/schema`.
+TIP: The configuration schemas can found in the `$JBOSS_HOME/docs/schema` directory.
 
 :leveloffset: +1
 
-include::subsystem-configuration/EE.adoc[]
+include::subsystem-configuration/Datasources_Agroal.adoc[]
+
+include::subsystem-configuration/Core_Management.adoc[]
 
-include::subsystem-configuration/Naming.adoc[]
 
 include::subsystem-configuration/DataSource.adoc[]
 
-include::subsystem-configuration/Datasources_Agroal.adoc[]
+include::subsystem-configuration/Deployment_Scanner.adoc[]
 
-include::subsystem-configuration/Logging.adoc[]
+include::subsystem-configuration/EE.adoc[]
+
+include::subsystem-configuration/Elytron_OIDC_Client.adoc[]
+
+include::subsystem-configuration/Health.adoc[]
+
+include::subsystem-configuration/Jakarta_Batch.adoc[]
 
 include::subsystem-configuration/Jakarta_Enterprise_Beans_3.adoc[]
 
-include::subsystem-configuration/Undertow.adoc[]
+include::subsystem-configuration/Jakarta_Faces.adoc[]
 
-include::subsystem-configuration/Messaging.adoc[]
+include::subsystem-configuration/Jakarta_MVC.adoc[]
 
-include::subsystem-configuration/Transactions.adoc[]
+include::subsystem-configuration/Jakarta_RESTful_Web_Services.adoc[]
 
-include::subsystem-configuration/Metrics.adoc[]
+include::subsystem-configuration/JMX.adoc[]
 
-include::subsystem-configuration/Micrometer.adoc[]
+include::subsystem-configuration/Logging.adoc[]
 
-include::subsystem-configuration/Observability_Tracing.adoc[]
+include::subsystem-configuration/Messaging.adoc[]
 
-include::subsystem-configuration/Health.adoc[]
+include::subsystem-configuration/Metrics.adoc[]
+
+include::subsystem-configuration/Micrometer.adoc[]
 
 include::subsystem-configuration/MicroProfile_Config_SmallRye.adoc[]
 
+include::subsystem-configuration/MicroProfile_Fault_Tolerance_SmallRye.adoc[]
+
 include::subsystem-configuration/MicroProfile_Health.adoc[]
 
 include::subsystem-configuration/MicroProfile_JWT.adoc[]
 
+include::subsystem-configuration/MicroProfile_LRA.adoc[]
+
 include::subsystem-configuration/MicroProfile_OpenAPI.adoc[]
 
-include::subsystem-configuration/MicroProfile_Fault_Tolerance_SmallRye.adoc[]
+include::subsystem-configuration/MicroProfile_Reactive_Messsaging_SmallRye.adoc[]
 
 include::subsystem-configuration/MicroProfile_Reactive_Streams_Operators_SmallRye.adoc[]
 
-include::subsystem-configuration/MicroProfile_Reactive_Messsaging_SmallRye.adoc[]
-
 include::subsystem-configuration/MicroProfile_Telemetry.adoc[]
 
-include::subsystem-configuration/MicroProfile_LRA.adoc[]
+include::subsystem-configuration/Observability_Tracing.adoc[]
 
-include::subsystem-configuration/Web_services.adoc[]
+include::subsystem-configuration/Naming.adoc[]
 
 include::subsystem-configuration/Resource_adapters.adoc[]
 
-include::subsystem-configuration/Jakarta_Batch.adoc[]
-
-include::subsystem-configuration/Jakarta_Faces.adoc[]
-
-include::subsystem-configuration/Jakarta_MVC.adoc[]
-
-include::subsystem-configuration/JMX.adoc[]
-
-include::subsystem-configuration/Deployment_Scanner.adoc[]
-
-include::subsystem-configuration/Core_Management.adoc[]
+include::subsystem-configuration/Transactions.adoc[]
 
-include::subsystem-configuration/Jakarta_RESTful_Web_Services.adoc[]
+include::subsystem-configuration/Undertow.adoc[]
 
-include::subsystem-configuration/Elytron_OIDC_Client.adoc[]
+include::subsystem-configuration/Web_services.adoc[]
 
 include::subsystem-configuration/Simple_configuration_subsystems.adoc[]
 

diff --git a/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/Core_Management.adoc b/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/Core_Management.adoc
@@ -1,5 +1,5 @@
 [[Core_Management]]
-= Core Management Subsystem Configuration
+= Core Management Subsystem
 
 ifdef::env-github[]
 :tip-caption: :bulb:
@@ -9,7 +9,7 @@ ifdef::env-github[]
 :warning-caption: :warning:
 endif::[]
 
-The core management subsystem is composed services used to manage the
+The core management subsystem is composed of services used to manage the
 server or monitor its status. +
 The core management subsystem configuration may be used to:
 

diff --git a/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/DataSource.adoc b/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/DataSource.adoc
@@ -1,5 +1,5 @@
 [[DataSource]]
-= DataSource configuration
+= DataSource Subsystem
 
 ifdef::env-github[]
 :tip-caption: :bulb:

diff --git a/.../src/main/asciidoc/_admin-guide/subsystem-configuration/Datasources_Agroal.adoc b/.../src/main/asciidoc/_admin-guide/subsystem-configuration/Datasources_Agroal.adoc
@@ -1,5 +1,5 @@
 [[agroal]]
-= Agroal configuration
+= Agroal Subsystem
 
 ifdef::env-github[]
 :tip-caption: :bulb:

diff --git a/.../src/main/asciidoc/_admin-guide/subsystem-configuration/Deployment_Scanner.adoc b/.../src/main/asciidoc/_admin-guide/subsystem-configuration/Deployment_Scanner.adoc
@@ -1,5 +1,5 @@
 [[Deployment_Scanner]]
-= Deployment Scanner configuration
+= Deployment Scanner Subsystem
 
 ifdef::env-github[]
 :tip-caption: :bulb:

diff --git a/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/EE.adoc b/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/EE.adoc
@@ -1,5 +1,5 @@
 [[EE]]
-= EE Subsystem Configuration
+= EE Subsystem
 :leveloffset: +1
 
 ifdef::env-github[]
@@ -10,19 +10,19 @@ ifdef::env-github[]
 :warning-caption: :warning:
 endif::[]
 
-The EE subsystem provides common functionality in the Jakarta EE platform,
+The `ee` subsystem provides common functionality in the Jakarta EE platform,
 such as the EE Concurrency Utilities (JSR 236) and `@Resource`
 injection. The subsystem is also responsible for managing the lifecycle
 of Jakarta EE application's deployments, that is, `.ear` files and configuration of global directories to share common libraries across all deployed applications.
 
-The EE subsystem configuration may be used to:
+The `ee` subsystem configuration may be used to:
 
 * customise the deployment of Jakarta EE applications
 * create EE Concurrency Utilities instances
-* define the default bindings
+* define the spec-mandated default JNDI bindings for services that must be made available via JNDI to applications.
 
-The subsystem name is ee and this document covers EE subsystem version
-`5.0`, which XML namespace within WildFly XML configurations is
+This document covers EE subsystem version
+`5.0`, whose XML namespace within WildFly XML configurations is
 `urn:jboss:domain:ee:5.0`. The path for the subsystem's XML schema,
 within WildFly's distribution, is `docs/schema/jboss-as-ee_5_0.xsd`.
 

diff --git a/...src/main/asciidoc/_admin-guide/subsystem-configuration/Elytron_OIDC_Client.adoc b/...src/main/asciidoc/_admin-guide/subsystem-configuration/Elytron_OIDC_Client.adoc
@@ -1,5 +1,5 @@
 [[Elytron_OIDC_Client]]
-= Elytron OpenID Connect Client Subsystem Configuration
+= Elytron OpenID Connect Client Subsystem
 
 ifdef::env-github[]
 :tip-caption: :bulb:

diff --git a/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/Health.adoc b/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/Health.adoc
@@ -1,5 +1,5 @@
 [[Health]]
-= Health Subsystem Configuration
+= Health Subsystem
 
 ifdef::env-github[]
 :tip-caption: :bulb:

diff --git a/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/JMX.adoc b/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/JMX.adoc
@@ -1,5 +1,5 @@
 [[JMX]]
-= JMX subsystem configuration
+= JMX Subsystem
 
 ifdef::env-github[]
 :tip-caption: :bulb:

diff --git a/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/Jakarta_Batch.adoc b/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/Jakarta_Batch.adoc
@@ -1,5 +1,5 @@
 [[Jakarta_Batch]]
-= Jakarta Batch Subsystem Configuration
+= Jakarta Batch Subsystem
 
 ifdef::env-github[]
 :tip-caption: :bulb:
@@ -13,7 +13,7 @@ endif::[]
 
 The batch subsystem is used to configure an environment for running
 batch applications. http://wildfly.org[WildFly] uses
-https://github.com/jberet/jsr352[JBeret] for it's batch implementation.
+https://github.com/jberet/jsr352[JBeret] for its Jakarta Batch implementation.
 Specific information about JBeret can be found in the
 http://jberet.gitbooks.io/jberet-user-guide/content/[user guide]. The
 resource path, in <<CLI_Recipes,CLI notation>>, for the subsystem

diff --git a/...n/asciidoc/_admin-guide/subsystem-configuration/Jakarta_Enterprise_Beans_3.adoc b/...n/asciidoc/_admin-guide/subsystem-configuration/Jakarta_Enterprise_Beans_3.adoc
@@ -1,5 +1,5 @@
 [[EJB3]]
-= EJB3 subsystem configuration guide
+= Jakarta Enterprise Beans Subsystem
 
 ifdef::env-github[]
 :tip-caption: :bulb:
@@ -9,11 +9,11 @@ ifdef::env-github[]
 :warning-caption: :warning:
 endif::[]
 
-This page lists the options that are available for configuring the EJB
+The `ejb3` subsystem provides support for Jakarta Enterprise Beans. This page lists the options that are available for configuring the `ejb3`
 subsystem.
 
 A complete example of the config is shown below, with a full explanation
-of each
+of each item.
 
 [source,xml,options="nowrap"]
 ----

diff --git a/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/Jakarta_Faces.adoc b/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/Jakarta_Faces.adoc
@@ -1,7 +1,7 @@
 :module-url: https://raw.githubusercontent.com/wildfly/wildfly/main/jsf/multi-jsf-installer/src/main/resources
 
 [[Jakarta_Faces]]
-= Jakarta Faces Configuration
+= Jakarta Faces Subsystem
 
 Jakarta Faces configuration is handled by the `jsf` subsystem. The `jsf` subsystem
 allows multiple Jakarta Faces implementations to be installed on the same WildFly server. In particular, any

diff --git a/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/Jakarta_MVC.adoc b/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/Jakarta_MVC.adoc
@@ -1,5 +1,5 @@
 [[Jakarta_MVC]]
-= Jakarta MVC Subsystem Configuration
+= Jakarta MVC Subsystem
 
 ifdef::env-github[]
 :tip-caption: :bulb:

diff --git a/...asciidoc/_admin-guide/subsystem-configuration/Jakarta_RESTful_Web_Services.adoc b/...asciidoc/_admin-guide/subsystem-configuration/Jakarta_RESTful_Web_Services.adoc
@@ -1,5 +1,5 @@
 [[JAXRS]]
-== JAXRS Subsystem Configuration
+== Jakarta RESTful Web Services Subsystem
 
 ifdef::env-github[]
 :tip-caption: :bulb:

diff --git a/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/Logging.adoc b/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/Logging.adoc
@@ -1,5 +1,5 @@
 [[Logging]]
-= Logging Configuration
+= Logging Subsystem
 
 ifdef::env-github[]
 :tip-caption: :bulb:
@@ -9,12 +9,10 @@ ifdef::env-github[]
 :warning-caption: :warning:
 endif::[]
 
-[abstract]
-
 The overall server logging configuration is represented by the logging
 subsystem. It consists of four notable parts: `handler` configurations,
-`logger`, the `root logger` declarations (aka log categories) and
-logging profiles. Each logger does reference a handler (or set of
+`logger` and the `root logger` declarations (aka log categories) and
+logging profiles. Each logger references a handler (or set of
 handlers). Each handler declares the log format and output:
 
 [source,xml,options="nowrap"]

diff --git a/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/Messaging.adoc b/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/Messaging.adoc
@@ -1,5 +1,5 @@
 [[Messaging]]
-= Messaging configuration
+= Messaging Subsystem
 
 ifdef::env-github[]
 :tip-caption: :bulb:
@@ -9,7 +9,7 @@ ifdef::env-github[]
 :warning-caption: :warning:
 endif::[]
 
-The Jakarta Messaging server configuration is done through the _messaging-activemq_
+Support for an embedded messaging broker or integration with a remote broker, including support for the Jakarta Messaging specification, is done through the _messaging-activemq_
 subsystem. In this chapter we are going outline the frequently used
 configuration options. For a more detailed explanation please consult
 the Artemis user guide (See "Component Reference").

diff --git a/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/Metrics.adoc b/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/Metrics.adoc
@@ -1,5 +1,5 @@
 [[MicroProfile_Metrics_SmallRye]]
-= Metrics Subsystem Configuration
+= Metrics Subsystem
 
 ifdef::env-github[]
 :tip-caption: :bulb:

diff --git a/...asciidoc/_admin-guide/subsystem-configuration/MicroProfile_Config_SmallRye.adoc b/...asciidoc/_admin-guide/subsystem-configuration/MicroProfile_Config_SmallRye.adoc
@@ -1,5 +1,5 @@
 [[MicroProfile_Config_SmallRye]]
-= MicroProfile Config Subsystem Configuration
+= MicroProfile Config Subsystem
 
 ifdef::env-github[]
 :tip-caption: :bulb:

diff --git a/...src/main/asciidoc/_admin-guide/subsystem-configuration/MicroProfile_Health.adoc b/...src/main/asciidoc/_admin-guide/subsystem-configuration/MicroProfile_Health.adoc
@@ -1,5 +1,5 @@
 [[MicroProfile_Health_SmallRye]]
-= MicroProfile Health Subsystem Configuration
+= MicroProfile Health Subsystem
 
 ifdef::env-github[]
 :tip-caption: :bulb:

diff --git a/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/MicroProfile_JWT.adoc b/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/MicroProfile_JWT.adoc
@@ -1,5 +1,5 @@
 [[MicroProfile_JWT_SmallRye]]
-= MicroProfile JWT Subsystem Configuration
+= MicroProfile JWT Subsystem
 
 ifdef::env-github[]
 :tip-caption: :bulb:

diff --git a/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/MicroProfile_LRA.adoc b/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/MicroProfile_LRA.adoc
@@ -1,5 +1,5 @@
 [[MicroProfile_LRA]]
-= MicroProfile LRA Subsystems Configuration
+= MicroProfile LRA Subsystems
 ----
 :narayana-version: 6.0.0.Final
 :eclipse-mp-lra-api-version: 2.0

diff --git a/...rc/main/asciidoc/_admin-guide/subsystem-configuration/MicroProfile_OpenAPI.adoc b/...rc/main/asciidoc/_admin-guide/subsystem-configuration/MicroProfile_OpenAPI.adoc
@@ -1,5 +1,5 @@
 [[MicroProfile_OpenAPI_SmallRye]]
-= MicroProfile OpenAPI Subsystem Configuration
+= MicroProfile OpenAPI Subsystem
 
 ifdef::env-github[]
 :tip-caption: :bulb:

diff --git a/...in-guide/subsystem-configuration/MicroProfile_Reactive_Messsaging_SmallRye.adoc b/...in-guide/subsystem-configuration/MicroProfile_Reactive_Messsaging_SmallRye.adoc
@@ -1,5 +1,5 @@
 [[MicroProfile_Reactive_Messaging_SmallRye]]
-= MicroProfile Reactive Messaging Subsystem Configuration
+= MicroProfile Reactive Messaging Subsystem
 ----
 :smallrye-reactive-messaging-version:       4.5.0
 :smallrye-reactive-messaging-tag:           {smallrye-reactive-messaging-version}