Este contenido no está disponible en el idioma seleccionado.
Chapter 3. 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:
/NODE_TYPE=NODE_NAME:OPERATION_NAME(PARAMETER_NAME=PARAMETER_VALUE)
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
, orhost.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./subsystem=datasources/data-source=ExampleDS
-
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./subsystem=datasources/data-source=ExampleDS:write-attribute
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 itsenabled
attribute tofalse
./subsystem=datasources/data-source=ExampleDS:write-attribute(name=enabled,value=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.
{ "outcome" => "success", "response-headers" => { "operation-requires-reload" => true, "process-state" => "reload-required" } }
You can use the read-attribute
operation to read the value of the ExampleDS
datasource’s enabled
attribute.
/subsystem=datasources/data-source=ExampleDS:read-attribute(name=enabled)
The following response shows that the operation was successful and that the value of enabled
is false
.
{ "outcome" => "success", "result" => false, }
3.1. Display Resource Values
You can use the read-resource
operation to view a resource’s attribute values.
:read-resource
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.
/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 } } }
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.
/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 } } }
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.
/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} } } }
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.
/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 "${jboss.node.name}", "statistics-enabled" => false, "buffer-cache" => {"default" => undefined}, "configuration" => { "filter" => undefined, "handler" => undefined }, "server" => {"default-server" => undefined}, "servlet-container" => {"default" => undefined} } }
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.
/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} } }
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 ${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 (${jboss.node.name}
).
/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} } }
3.2. Display Resource Descriptions
You can use the read-resource-description
operation to a description about a resource and its attributes.
:read-resource-description
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.
/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" => {} } }
See Resource Attribute Details to learn more about the fields returned for attributes.
3.3. Display an Attribute Value
You can use the read-attribute
operation to view the current value of a single attribute.
:read-attribute(name=ATTRIBUTE_NAME)
The following example displays the log level for the root logger by reading the level
attribute.
/subsystem=logging/root-logger=ROOT:read-attribute(name=level) { "outcome" => "success", "result" => "INFO" }
One advantage of using the read-attribute
operation is the ability to expose the current runtime value of an attribute.
/interface=public:read-attribute(name=resolved-address) { "outcome" => "success", "result" => "127.0.0.1" }
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.
3.4. Update an Attribute
You can use the write-attribute
operation to update the value of an attribute for a resource.
:write-attribute(name=ATTRIBUTE_NAME, value=ATTRIBUTE_VALUE)
The following example disables the deployment scanner by setting the scan-enabled
attribute to false
.
/subsystem=deployment-scanner/scanner=default:write-attribute(name=scan-enabled,value=false) {"outcome" => "success"}
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
.
/subsystem=deployment-scanner/scanner=default:read-attribute(name=scan-enabled) { "outcome" => "success", "result" => false }
3.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.
/subsystem=logging/root-logger=ROOT:undefine-attribute(name=level)
The default value for the level
attribute is ALL
. You can see that this default is used when performing the read-resource
operation.
/subsystem=logging/root-logger=ROOT:read-resource { "outcome" => "success", "result" => { "filter" => undefined, "filter-spec" => undefined, "handlers" => [ "CONSOLE", "FILE" ], "level" => "ALL" } }
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
.
/subsystem=logging/root-logger=ROOT:read-resource(include-defaults=false) { "outcome" => "success", "result" => { "filter" => undefined, "filter-spec" => undefined, "handlers" => [ "CONSOLE", "FILE" ], "level" => undefined } }
3.6. Display Operation Names
You can use the read-operation-names
list the available operations for a given resource.
:read-operation-names
The following example lists the available operations to perform on a deployment.
/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"
]
}
Use the read-operation-description
operation to display an operation description.
3.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.
:read-operation-description(name=OPERATION_NAME)
The following example provides the description and parameter information for the add
operation on a system property.
/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
}
}
3.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
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 (\
).
/system-property=test1:add(value="Hello World") /system-property=test2:add(value={Hello World}) /system-property=test3:add(value=Hello\ World)
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
.
/system-property=test1:add(value="server's") /system-property=test2:add(value=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"
.
/system-property=test1:add(value="\"quote\"")
Commas
You can use a comma (,
) in a value by enclosing the value in double quotes (""
).
/system-property=test:add(value="Last,First")
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 (\
).
/system-property=test1:add(value="one(1)") /system-property=test2:add(value={one(1)}) /system-property=test3:add(value=one\(1\))
This will set the value to one(1)
.
Braces
You can include braces ({}
) in a value by enclosing the value in double quotes (""
).
/system-property=test:add(value="{braces}")
This will set the value to {braces}
.
Brackets
You can include brackets ([]
) in a value by enclosing the value in double quotes (""
).
/system-property=test:add(value="[brackets]")
This will set the value to [brackets]
.
Diacritic Marks
Diacritic marks, such as ñ
, ř
, or ý
, can be used when adding a value using the management CLI.
/system-property=test1:add(value=Año)
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 (\
).
/system-property=test2:add(value={Dos años}) /system-property=test3:add(value=Dos\ años)
This will set the value to Dos años
.
3.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
.WarningUsing 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
deploy /path/to/deployment.war --headers={allow-resource-service-restart=true}
Example: Remove a Resource Using an Operation Header
/subsystem=infinispan/cache-container=test:remove() {allow-resource-service-restart=true}
Use a semicolon (;
) to separate multiple operation headers.
3.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.
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 (
||
)
-
and (
Comparison operators
-
equal to (
==
) -
not equal to (
!=
) -
greater than (
>
) -
greater than or equal to (
>=
) -
less than (
<
) -
less than or equal to (
<=
) -
match regular expression (
~=
)
-
equal to (
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
.
if (result ~= ".*jgroups.*") of /:resolve-expression(expression=${features}) echo Configuring JGroups end-if
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
.
if (outcome != success) of /system-property=test:read-resource /system-property=test:add(value=true) end-if
The condition above uses outcome
, which is returned when the CLI command after the of
keyword is executed, as shown below:
/system-property=test:read-resource { "outcome" => "failed", "failure-description" => "JBAS014807: Management resource '[(\"system-property\" => \"test\")]' not found", "rolled-back" => true }
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
).
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
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.
$ EAP_HOME/bin/jboss-cli.sh --connect --file=CLI_FILE
3.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 thetry
batch. Thetry
batch continues until one ofcatch
orfinally
command is encountered. -
catch
command marks the end of thetry
batch. Thetry
batch is then held back and thecatch
batch is started. -
finally
command marks the end of thecatch
batch or thetry
batch and starts thefinally
batch. -
end-try
is the command that ends either thecatch
orfinally
batch and runs the try-catch-finally control flow.
The following example either creates or re-creates a datasource and enables it:
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
3.12. 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:
/deployment=jboss-modules.jar:query(select=["name","enabled"])
The following response shows that the operation was successful. The name
and enabled
attributes are listed for the jboss-modules.jar
deployment.
{ "outcome" => "success", "result" => { "name" => "jboss-modules.jar", "enabled" => true } }
You can also query across multiple resources, for example, list the name
and enabled
attributes of all deployments, using a wildcard:
/deployment=*:query(select=["name","enabled"])
The following response shows that the operation was successful. The name
and enabled
attributes of all deployments are listed.
{ "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 } } ] }
The :query
operation also filters relevant objects. For example, to view the name
and enabled
attribute values for deployments with enabled
as true
.
/deployment=*:query(select=["name","enabled"],where=["enabled","true"])
The following response shows that the operation was successful. The name
and enabled
attribute values for deployments with enabled
as true
are listed.
{ "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 } } ] }