Chapter 4. Creating and Executing Requests JBoss EAP configuration is presented as a hierarchical tree of addressable resources, each offering their own set of operations. Management CLI operation requests allow for low-level interaction with the management model and provide a controlled way to edit server configurations. Operation requests use the following format: An operation request consists of three parts: address The address specifies the resource node on which to perform the operation. NODE_TYPE maps to an element name and NODE_NAME maps to that element's name attribute in the configuration XML. Each level of the resource tree is separated by a slash ( / ). operation name The operation to perform on the resource node. It is prefixed with a colon ( : ). parameters The set of required or optional parameters that vary depending on the operation. They are contained within parentheses ( () ). Construct an Operation Request Determine the address You can reference the XML configuration files ( standalone.xml , domain.xml , or host.xml ) to assist in determining the required address. You can also use tab completion to view the available resources. Below are several common addresses for resources at the root ( / ) level. /deployment= DEPLOYMENT_NAME - Deployment configurations. /socket-binding-group= SOCKET_BINDING_GROUP_NAME - Socket binding configurations. /interface= INTERFACE_NAME - Interface configurations. /subsystem= SUBSYSTEM_NAME - Subsystem configuration when running as a standalone server. /profile= PROFILE_NAME /subsystem= SUBSYSTEM_NAME - Subsystem configuration for the selected profile when running in a managed domain. /host= HOST_NAME - Server configuration for the selected host when running in a managed domain. The below address is for the ExampleDS datasource. Determine the operation The available operations differ for each type of resource node. You can use the :read-operation-names operation on a resource address to view the available operations. You can also use tab completion. Use the :read-operation-description operation to get information on a particular operation for a resource. The below operation (once the appropriate parameters are included) will set the value of an attribute for the ExampleDS datasource. Determine the parameters Each operation has its own set of available parameters. If you attempt to perform an operation without a required parameter, you will receive an error message that the parameter cannot be null . Multiple parameters are separated by commas ( , ). If an operation does not have any parameters, then the parentheses are optional. Use the :read-operation-description operation on a resource, passing in the operation name, to determine the required parameters for that operation. You can also use tab completion to list the available parameters. The below operation disables the ExampleDS datasource by setting its enabled attribute to false . Once entered, the management interface will perform the operation request on the server configuration. Depending on the operation request, you will receive output to the terminal that contains the outcome and the result or response of the operation. The following response from disabling the ExampleDS datasource shows that the operation was successful and requires a reload of the server in order to take effect. You can use the read-attribute operation to read the value of the ExampleDS datasource's enabled attribute. The following response shows that the operation was successful and that the value of enabled is false . 4.1. Display Resource Values You can use the read-resource operation to view a resource's attribute values. You can specify parameters to provide complete information about child resources, recursively. You can also specify parameters to include runtime attributes, resolve expressions, and include aliases. Use read-operation-description(name=read-resource) to see the description of all available parameters for read-resource . The following example reads the attributes for a deployment. It includes details such as the deployment name, whether it is enabled, and the last time it was enabled. Include Runtime Attributes The include-runtime parameter can be used to retrieve runtime attributes. The following example reads the attributes for a deployment. In addition to persistent attributes, it also includes runtime attributes, such as the deployment status and the last time it was disabled. You can also use the not operator ( ! ) when passing in boolean parameters. For example: :read-resource(include-runtime=false) can be entered as :read-resource(!include-runtime) :read-resource(include-runtime=true) can be entered as :read-resource(include-runtime) Read Child Resources Recursively The recursive parameter can be used to retrieve attributes recursively from child resources. The following example reads the attributes for a deployment. In addition to the resource's own attributes, it recursively returns the attributes for its child resources, such as the undertow subsystem configuration. Exclude Default Values The include-defaults parameter can be used to show or hide default values when reading attributes for a resource. This is true by default, meaning that default values will be shown when using the read-resource operation. The following example uses the read-resource operation on the undertow subsystem. The following example also uses the read-resource operation on the undertow subsystem, but sets the include-defaults parameter to false . Several attributes, such as statistics-enabled and default-server , now display undefined as their value instead of the default value. Resolve Expressions The resolve-expressions parameter can be used to resolve the expressions of the returned attributes to their value on the server. Attributes with expressions as their values use the format USD{ PARAMETER : DEFAULT_VALUE } . See Property Replacement in the Configuration Guide for more information. The following example reads the attributes for a deployment. The instance-id attribute shows its resolved value ( test-name ) instead of the expression ( USD{jboss.node.name} ). 4.2. Display Resource Descriptions You can use the read-resource-description operation to a description about a resource and its attributes. You can specify parameters to provide complete descriptions about child resources, recursively. You can also specify parameters to include details of the resource's operations and notifications. Use read-operation-description(name=read-resource-description) to see the description of all available parameters for read-resource-description . The following example displays the attribute details for a buffer cache. See Resource Attribute Details to learn more about the fields returned for attributes. 4.3. Display an Attribute Value You can use the read-attribute operation to view the current value of a single attribute. The following example displays the log level for the root logger by reading the level attribute. One advantage of using the read-attribute operation is the ability to expose the current runtime value of an attribute. The resolved-address attribute is a runtime attribute. This attribute is not displayed when using the read-resource operation on the public interface unless you pass in the include-runtime parameter. And even then, it is displayed with the rest of the resource's other attributes. You can also use the include-defaults and resolve-expressions parameters. See Display Resource Values for details on these parameters. 4.4. Update an Attribute You can use the write-attribute operation to update the value of an attribute for a resource. The following example disables the deployment scanner by setting the scan-enabled attribute to false . The response from the operation request shows that it was successful. You can also confirm the result by using the read-attribute operation to read the scan-enabled attribute, which now shows as false . 4.5. Undefine an Attribute You can set the value of an attribute to undefined . If this attribute has a default value, that will be used. The following example undefines the level attribute for the root logger. The default value for the level attribute is ALL . You can see that this default is used when performing the read-resource operation. To view the resource without the default values being read, you must use set the include-defaults parameter to false . You can now see that the value of level is undefined . 4.6. Display Operation Names You can use the read-operation-names list the available operations for a given resource. The following example lists the available operations to perform on a deployment. Use the read-operation-description operation to display an operation description . 4.7. Display an Operation Description You can use the read-operation-description operation to display a description of a certain operation for a resource. This also includes parameter descriptions and which parameters are required. The following example provides the description and parameter information for the add operation on a system property. 4.8. Add a Value with Special Characters Occasionally when creating management CLI requests, you may need to add a value that contains special characters. Certain special characters, such as those used in the syntax of a management CLI request, must be entered in a particular manner. In many cases, but not all, enclosing the value in double quotes ( "" ) is sufficient. If you are unsure whether your special character was accepted properly, be sure to read the attribute or resource after adding the value to verify that it was saved correctly. See the sections below for information on how to process the following special characters. Whitespace Quotation Marks Commas Parentheses Braces Brackets Diacritic Marks Whitespace By default, whitespace is trimmed from values added through the management CLI. You can include a space in a value by enclosing the value in double quotes ( "" ) or braces ( {} ), or by escaping it using a backslash ( \ ). This will set the value to Hello World . Quotation Marks You can use a single quotation mark ( ' ) in a value by enclosing the value in double quotes ( "" ) or by escaping it using a backslash ( \ ). The following examples set the value of system properties to server's . You can use a double quotation mark ( " ) in a value by escaping it using a backslash ( \ ). Depending on the location of the quotation mark in the value, you might also need to enclose the value in double quotes ( "" ). The following example sets the value of a system property to "quote" . Commas You can use a comma ( , ) in a value by enclosing the value in double quotes ( "" ). This will set the value to Last,First . Parentheses You can include parentheses ( () ) in a value by enclosing the value in double quotes ( "" ) or braces ( {} ), or by escaping the parenthesis using a backslash ( \ ). This will set the value to one(1) . Braces You can include braces ( {} ) in a value by enclosing the value in double quotes ( "" ). This will set the value to {braces} . Brackets You can include brackets ( [] ) in a value by enclosing the value in double quotes ( "" ). This will set the value to [brackets] . Diacritic Marks Diacritic marks, such as n , r , or y , can be used when adding a value using the management CLI. However, do not enclose the value in double quotes ( "" ). This can cause the diacritic mark to be replaced with a question mark ( ? ). If the value has whitespace that needs to be maintained, instead enclose the value in braces ( {} ) or escape the space with a backslash ( \ ). This will set the value to Dos anos . 4.9. Specify Operation Headers You can specify operation headers to control certain aspects of how an operation executes. The following operation headers are available: allow-resource-service-restart Whether to restart runtime services that require a restart in order for the operation's changes take effect. This defaults to false . Warning Using the allow-resource-service-restart=true header can disrupt end-user request handling until the required services have been restarted. blocking-timeout The maximum time in seconds that the operation should block at any one point in its completion process before the operation is rolled back. This defaults to 300 seconds. roles The list of RBAC roles that should be used when making access control decisions instead of those from the roles normally associated with the user invoking the operation. Note that this can only be used to reduce permissions for a caller, not to increase permissions. rollback-on-runtime-failure Whether persistent configuration changes should be reverted if applying the changes to runtime services fails. This defaults to true . rollout The rollout plan for a managed domain deployment. For more information, see the Using Rollout Plans section of the JBoss EAP Configuration Guide . Example: Deploy an Application Using an Operation Header Example: Remove a Resource Using an Operation Header Use a semicolon ( ; ) to separate multiple operation headers. 4.10. Use if-else Control Flow The management CLI supports if - else control flow, which allows you to choose which set of commands and operations to execute based on a condition. The if condition is a boolean expression which evaluates the response of the management command or operation specified after the of keyword. Note The use of nested if - else statements is not supported. Expressions can contain any of the following items: Parentheses to group and prioritize expressions Conditional operators and ( && ) or ( || ) Comparison operators equal to ( == ) not equal to ( != ) greater than ( > ) greater than or equal to ( >= ) less than ( < ) less than or equal to ( <= ) match regular expression ( ~= ) Important The match regular expression ( ~= ) operator is provided as Technology Preview only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. See Technology Preview Features Support Scope on the Red Hat Customer Portal for information about the support scope for Technology Preview features. The below example uses the match regular expression ( ~= ) operator to check whether the value of the features system property contains jgroups . The below example attempts to read the system property test . If outcome is not success (meaning that the property does not exist), then the system property will be added and set to true . The condition above uses outcome , which is returned when the CLI command after the of keyword is executed, as shown below: The below example issues the appropriate management CLI command to enable the ExampleDS datasource by checking the launch type of the server process ( STANDALONE or DOMAIN ). Management CLI commands with if - else control flow can be specified in a file, with each command on a separate line in the file. You can then pass the file to the jboss-cli script to be executed non-interactively using the --file parameter. 4.11. Use try-catch-finally Control Flow The management CLI provides a simplified try-catch-finally control flow. It consists of three sets of operations and commands corresponding to the try , catch , and finally blocks. The catch and finally blocks are optional, but at least one of them should be present and only one catch block can be specified. The control flow begins with execution of the try batch. If the try batch completes successfully, then the catch batch is skipped and the finally batch is executed. If the try batch fails, for example, java.io.IOException , the try-catch-finally control flow will terminate immediately, and the catch batch if it is available will be executed. The finally batch will always execute at the end of the control flow whether the try and catch batches succeeds or fails to execute. There are four commands that define the try-catch-finally control flow: try command starts the try batch. The try batch continues until one of catch or finally command is encountered. catch command marks the end of the try batch. The try batch is then held back and the catch batch is started. finally command marks the end of the catch batch or the try batch and starts the finally batch. end-try is the command that ends either the catch or finally batch and runs the try-catch-finally control flow. The following example either creates or re-creates a datasource and enables it: 4.12. Use for-done Control Flow The management CLI supports for-done control flow, which allows you to iterate over a collection returned from an operation and execute commands on each item in the collection. You can use for-done statements with the management CLI in interactive or non-interactive mode. for-done statements use the following syntax: The VARIABLE_NAME can be used in the COMMANDS_TO_EXECUTE using the syntax USD VARIABLE_NAME . The OPERATION must return a collection. The COMMANDS_TO_EXECUTE is a list of commands to execute, with each command on a separate line. The following example iterates over all deployments and displays whether each is enabled or disabled. Enter done --discard if you want to discard the current for block without executing the commands. Note The use of for-done statements while in batch mode, or nesting them inside other for-done statements, is not supported. 4.13. Query a Resource The JBoss EAP management CLI provides the query operation to query a resource. You can use the :read-resource operation to read all attributes for a resource. If you want to list only selected attributes, you can use the :query operation. For example, to see the list of name and enabled attributes, use the following command: The following response shows that the operation was successful. The name and enabled attributes are listed for the jboss-modules.jar deployment. You can also query across multiple resources, for example, list the name and enabled attributes of all deployments, using a wildcard: The following response shows that the operation was successful. The name and enabled attributes of all deployments are listed. The :query operation also filters relevant objects. For example, to view the name and enabled attribute values for deployments with enabled as true . The following response shows that the operation was successful. The name and enabled attribute values for deployments with enabled as true are listed. 4.14. Redirect Output Instead of printing output from a management CLI operation to the terminal, you can redirect the output to a file or to another command . Redirect Output to a File Use the > operator to redirect output from a management CLI operation to a file on the file system. Example: Write read-resource Output to a File Use the >> operator to redirect output from a management CLI operation and append it to a file on the file system. Example: Append read-resource Output to a File Redirect Output to a Command Use the | operator to redirect output from a management CLI operation to the grep command to search output for a regular expression match. Currently, grep is the only supported command for the | operator. Example: Search Output from the server.log File Note It is not supported to use the grep command more than once in the same command.

Commands:
/ NODE_TYPE = NODE_NAME : OPERATION_NAME ( PARAMETER_NAME = PARAMETER_VALUE )
/subsystem=datasources/data-source=ExampleDS
/subsystem=datasources/data-source=ExampleDS:write-attribute
/subsystem=datasources/data-source=ExampleDS:write-attribute(name=enabled,value=false)
{ "outcome" => "success", "response-headers" => { "operation-requires-reload" => true, "process-state" => "reload-required" } }
/subsystem=datasources/data-source=ExampleDS:read-attribute(name=enabled)
{ "outcome" => "success", "result" => false, }
:read-resource
/deployment= DEPLOYMENT_NAME :read-resource { "outcome" => "success", "result" => { "enabled" => true, "enabled-time" => 1453929902598L, "enabled-timestamp" => "2016-01-27 16:25:02,598 EST", "name" => " DEPLOYMENT_NAME ", "owner" => undefined, "persistent" => true, "runtime-name" => " DEPLOYMENT_NAME ", "subdeployment" => undefined, "subsystem" => { "undertow" => undefined, "logging" => undefined } } }
/deployment= DEPLOYMENT_NAME :read-resource(include-runtime=true) { "outcome" => "success", "result" => { "disabled-time" => undefined, "disabled-timestamp" => undefined, "enabled" => true, "enabled-time" => 1453929902598L, "enabled-timestamp" => "2016-01-27 16:25:02,598 EST", "name" => " DEPLOYMENT_NAME ", "owner" => undefined, "persistent" => true, "runtime-name" => " DEPLOYMENT_NAME ", "status" => "OK", "subdeployment" => undefined, "subsystem" => { "undertow" => undefined, "logging" => undefined } } }
/deployment= DEPLOYMENT_NAME :read-resource(recursive=true) { "outcome" => "success", "result" => { "enabled" => true, "enabled-time" => 1453929902598L, "enabled-timestamp" => "2016-01-27 16:25:02,598 EST", "name" => " DEPLOYMENT_NAME ", "owner" => undefined, "persistent" => true, "runtime-name" => " DEPLOYMENT_NAME ", "subdeployment" => undefined, "subsystem" => { "undertow" => { "context-root" => "/test", "server" => "default-server", "virtual-host" => "default-host", "servlet" => undefined, "websocket" => undefined }, "logging" => {"configuration" => undefined} } } }
/subsystem=undertow:read-resource { "outcome" => "success", "result" => { "default-security-domain" => "other", "default-server" => "default-server", "default-servlet-container" => "default", "default-virtual-host" => "default-host", "instance-id" => expression "USD{jboss.node.name}", "statistics-enabled" => false, "buffer-cache" => {"default" => undefined}, "configuration" => { "filter" => undefined, "handler" => undefined }, "server" => {"default-server" => undefined}, "servlet-container" => {"default" => undefined} } }
/subsystem=undertow:read-resource(include-defaults=false) { "outcome" => "success", "result" => { "default-security-domain" => undefined, "default-server" => undefined, "default-servlet-container" => undefined, "default-virtual-host" => undefined, "instance-id" => undefined, "statistics-enabled" => undefined, "buffer-cache" => {"default" => undefined}, "configuration" => { "filter" => undefined, "handler" => undefined }, "server" => {"default-server" => undefined}, "servlet-container" => {"default" => undefined} } }
/subsystem=undertow:read-resource(resolve-expressions=true) { "outcome" => "success", "result" => { "default-security-domain" => "other", "default-server" => "default-server", "default-servlet-container" => "default", "default-virtual-host" => "default-host", "instance-id" => "test-name", "statistics-enabled" => false, "buffer-cache" => {"default" => undefined}, "configuration" => { "filter" => undefined, "handler" => undefined }, "server" => {"default-server" => undefined}, "servlet-container" => {"default" => undefined} } }
:read-resource-description
/subsystem=undertow/buffer-cache=default:read-resource-description { "outcome" => "success", "result" => { "description" => "The buffer cache used to cache static content", "attributes" => { "buffer-size" => { "type" => INT, "description" => "The size of an individual buffer", "expressions-allowed" => true, "nillable" => true, "default" => 1024, "min" => 0L, "max" => 2147483647L, "access-type" => "read-write", "storage" => "configuration", "restart-required" => "resource-services" }, "buffers-per-region" => { "type" => INT, "description" => "The numbers of buffers in a region", "expressions-allowed" => true, "nillable" => true, "default" => 1024, "min" => 0L, "max" => 2147483647L, "access-type" => "read-write", "storage" => "configuration", "restart-required" => "resource-services" }, "max-regions" => { "type" => INT, "description" => "The maximum number of regions", "expressions-allowed" => true, "nillable" => true, "default" => 10, "min" => 0L, "max" => 2147483647L, "access-type" => "read-write", "storage" => "configuration", "restart-required" => "resource-services" } }, "operations" => undefined, "notifications" => undefined, "children" => {} } }
:read-attribute(name= ATTRIBUTE_NAME )
/subsystem=logging/root-logger=ROOT:read-attribute(name=level) { "outcome" => "success", "result" => "INFO" }
/interface=public:read-attribute(name=resolved-address) { "outcome" => "success", "result" => "127.0.0.1" }
:write-attribute(name= ATTRIBUTE_NAME , value= ATTRIBUTE_VALUE )
/subsystem=deployment-scanner/scanner=default:write-attribute(name=scan-enabled,value=false) {"outcome" => "success"}
/subsystem=deployment-scanner/scanner=default:read-attribute(name=scan-enabled) { "outcome" => "success", "result" => false }
/subsystem=logging/root-logger=ROOT:undefine-attribute(name=level)
/subsystem=logging/root-logger=ROOT:read-resource { "outcome" => "success", "result" => { "filter" => undefined, "filter-spec" => undefined, "handlers" => [ "CONSOLE", "FILE" ], "level" => "ALL" } }
/subsystem=logging/root-logger=ROOT:read-resource(include-defaults=false) { "outcome" => "success", "result" => { "filter" => undefined, "filter-spec" => undefined, "handlers" => [ "CONSOLE", "FILE" ], "level" => undefined } }
:read-operation-names
/deployment= DEPLOYMENT_NAME :read-operation-names { "outcome" => "success", "result" => [ "add", "deploy", "list-add", "list-clear", "list-get", "list-remove", "map-clear", "map-get", "map-put", "map-remove", "query", "read-attribute", "read-attribute-group", "read-attribute-group-names", "read-children-names", "read-children-resources", "read-children-types", "read-operation-description", "read-operation-names", "read-resource", "read-resource-description", "redeploy", "remove", "undefine-attribute", "undeploy", "whoami", "write-attribute" ] }
:read-operation-description(name= OPERATION_NAME )
/system-property= SYSTEM_PROPERTY :read-operation-description(name=add) { "outcome" => "success", "result" => { "operation-name" => "add", "description" => "Adds a system property or updates an existing one.", "request-properties" => {"value" => { "type" => STRING, "description" => "The value of the system property.", "expressions-allowed" => true, "required" => false, "nillable" => true, "min-length" => 0L, "max-length" => 2147483647L }}, "reply-properties" => {}, "read-only" => false, "runtime-only" => false } }
/system-property=test1:add(value="Hello World") /system-property=test2:add(value={Hello World}) /system-property=test3:add(value=Hello\ World)
/system-property=test1:add(value="server's") /system-property=test2:add(value=server\'s)
/system-property=test1:add(value="\"quote\"")
/system-property=test:add(value="Last,First")
/system-property=test1:add(value="one(1)") /system-property=test2:add(value={one(1)}) /system-property=test3:add(value=one\(1\))
/system-property=test:add(value="{braces}")
/system-property=test:add(value="[brackets]")
/system-property=test1:add(value=Ano)
/system-property=test2:add(value={Dos anos}) /system-property=test3:add(value=Dos\ anos)
deployment deploy-file /path/to/DEPLOYMENT.war --headers={allow-resource-service-restart=true}
/subsystem=infinispan/cache-container=test:remove() {allow-resource-service-restart=true}
if (result ~= ".*jgroups.*") of /:resolve-expression(expression=USD{features}) echo Configuring JGroups end-if
if (outcome != success) of /system-property=test:read-resource /system-property=test:add(value=true) end-if
/system-property=test:read-resource { "outcome" => "failed", "failure-description" => "JBAS014807: Management resource '[(\"system-property\" => \"test\")]' not found", "rolled-back" => true }
if (result == STANDALONE) of /:read-attribute(name=launch-type) /subsystem=datasources/data-source=ExampleDS:write-attribute(name=enabled, value=true) else /profile=full/subsystem=datasources/data-source=ExampleDS:write-attribute(name=enabled, value=true) end-if
EAP_HOME /bin/jboss-cli.sh --connect --file= CLI_FILE
try /subsystem=datasources/data-source=myds:add(connection-url= CONNECTION_URL ,jndi-name=java:/myds,driver-name=h2) catch /subsystem=datasources/data-source=myds:remove /subsystem=datasources/data-source=myds:add(connection-url= CONNECTION_URL ,jndi-name=java:/myds,driver-name=h2) finally /subsystem=datasources/data-source=myds:enable end-try
for VARIABLE_NAME in OPERATION COMMANDS_TO_EXECUTE done
for deploymentName in :read-children-names(child-type=deployment) if (result == true) of /deployment=USDdeploymentName:read-attribute(name=enabled) echo USDdeploymentName is enabled. else echo USDdeploymentName is disabled. end-if done
/deployment=jboss-modules.jar:query(select=["name","enabled"])
{ "outcome" => "success", "result" => { "name" => "jboss-modules.jar", "enabled" => true } }
/deployment=*:query(select=["name","enabled"])
{ "outcome" => "success", "result" => [ { "address" => [("deployment" => "helloworld.war")], "outcome" => "success", "result" => { "name" => "helloworld.war", "enabled" => true } }, { "address" => [("deployment" => "kitchensink.war")], "outcome" => "success", "result" => { "name" => "kitchensink.war", "enabled" => true } }, { "address" => [("deployment" => "xyz.jar")], "outcome" => "success", "result" => { "name" => "xyz.jar", "enabled" => false } } ] }
/deployment=*:query(select=["name","enabled"],where=["enabled","true"])
{ "outcome" => "success", "result" => [ { "address" => [("deployment" => "helloworld.war")], "outcome" => "success", "result" => { "name" => "helloworld.war", "enabled" => true } }, { "address" => [("deployment" => "kitchensink.war")], "outcome" => "success", "result" => { "name" => "kitchensink.war", "enabled" => true } } ] }
:read-resource > myfile.txt
:read-resource >> myfile.txt
/subsystem=logging/log-file=server.log:read-log-file | grep Deployed "2018-03-06 09:48:02,389 INFO [org.jboss.as.server] (management-handler-thread - 5) WFLYSRV0010: Deployed \"jboss-helloworld.war\" (runtime-name : \"jboss-helloworld.war\")",