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

  1. 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.

    /subsystem=datasources/data-source=ExampleDS
  2. 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
  3. 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.

    /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
        }
    }
}

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.

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}.

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.

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

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.

Expressions can contain any of the following items:

  • Conditional operators (&&, ||)
  • Comparison operators (>, >=, <, <=, ==, !=)
  • Parentheses to group and prioritize expressions
Note

The use of nested if-else statements is not supported.

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 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:

try
/subsystem=datasources/data-source=myds:add(connection-url=xxx,jndi-name=java:/myds,driver-name=h2)

catch
/subsystem=datasources/data-source=myds:remove
/subsystem=datasources/data-source=myds:add(connection-url=xxx,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 about 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" => "jboss-helloworld.war")],
             "outcome" => "success",
             "result" => {
                 "name" => "jboss-helloworld.war",
                 "enabled" => true
             }
         },
         {
             "address" => [("deployment" => "jboss-kitchensink.war")],
             "outcome" => "success",
             "result" => {
                 "name" => "jboss-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" => "jboss-helloworld.war")],
             "outcome" => "success",
             "result" => {
                 "name" => "jboss-helloworld.war",
                 "enabled" => true
             }
         },
         {
             "address" => [("deployment" => "jboss-kitchensink.war")],
             "outcome" => "success",
             "result" => {
                 "name" => "jboss-kitchensink.war",
                 "enabled" => true
             }
         }
     ]
 }