[[CLI_Recipes]]
= CLI Recipes

ifdef::env-github[]
:tip-caption: :bulb:
:note-caption: :information_source:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:
endif::[]

== Properties

[[adding-reading-and-removing-system-property-using-cli]]
=== Adding, reading and removing system property using CLI

For standalone mode:

[source,options="nowrap"]
----
$ ./bin/jboss-cli.sh --connect controller=IP_ADDRESS
[standalone@IP_ADDRESS:9990 /] /system-property=foo:add(value=bar)
[standalone@IP_ADDRESS:9990 /] /system-property=foo:read-resource
{
    "outcome" => "success",
    "result" => {"value" => "bar"}
}
[standalone@IP_ADDRESS:9990 /] /system-property=foo:remove
{"outcome" => "success"}
----

For domain mode the same commands are used, you can add/read/remove
system properties for: +
All hosts and server instances in domain

[source,options="nowrap"]
----
[domain@IP_ADDRESS:9990 /] /system-property=foo:add(value=bar)
[domain@IP_ADDRESS:9990 /] /system-property=foo:read-resource
[domain@IP_ADDRESS:9990 /] /system-property=foo:remove
----

Host and its server instances

[source,options="nowrap"]
----
[domain@IP_ADDRESS:9990 /] /host=primary/system-property=foo:add(value=bar)
[domain@IP_ADDRESS:9990 /] /host=primary/system-property=foo:read-resource
[domain@IP_ADDRESS:9990 /] /host=primary/system-property=foo:remove
----

Just one server instance

[source,options="nowrap"]
----
[domain@IP_ADDRESS:9990 /] /host=primary/server-config=server-one/system-property=foo:add(value=bar)
[domain@IP_ADDRESS:9990 /] /host=primary/server-config=server-one/system-property=foo:read-resource
[domain@IP_ADDRESS:9990 /] /host=primary/server-config=server-one/system-property=foo:remove
----

[[overview-of-all-system-properties]]
=== Overview of all system properties

Overview of all system properties in WildFly including OS system
properties and properties specified on command line using -D, -P or
--properties arguments.

Standalone

[source,options="nowrap"]
----
[standalone@IP_ADDRESS:9990 /] /core-service=platform-mbean/type=runtime:read-attribute(name=system-properties)
----

Domain

[source,options="nowrap"]
----
[domain@IP_ADDRESS:9990 /] /host=primary/core-service=platform-mbean/type=runtime:read-attribute(name=system-properties)
[domain@IP_ADDRESS:9990 /] /host=primary/server=server-one/core-service=platform-mbean/type=runtime:read-attribute(name=system-properties)
----

== Configuration

[[list-subsystems]]
=== List Subsystems

[source,options="nowrap"]
----
[standalone@localhost:9990 /] /:read-children-names(child-type=subsystem)
{
    "outcome" => "success",
    "result" => [
        "batch",
        "datasources",
        "deployment-scanner",
        "ee",
        "ejb3",
        "infinispan",
        "io",
        "jaxrs",
        "jca",
        "jdr",
        "jmx",
        "jpa",
        "jsf",
        "logging",
        "mail",
        "naming",
        "pojo",
        "remoting",
        "resource-adapters",
        "sar",
        "security",
        "threads",
        "transactions",
        "undertow",
        "webservices",
        "weld"
    ]
}
----

[[list-description-of-available-attributes-and-childs]]
=== List description of available attributes and childs

Descriptions, possible attribute type and values, permission and whether
expressions ( _$\{ ... }_ ) are allowed from the underlying model are
shown by the read-resource-description command.

[source,options="nowrap"]
----
/subsystem=datasources/data-source=ExampleDS:read-resource-description
{
    "outcome" => "success",
    "result" => {
        "description" => "A JDBC data-source configuration",
        "head-comment-allowed" => true,
        "tail-comment-allowed" => true,
        "attributes" => {
            "connection-url" => {
                "type" => STRING,
                "description" => "The JDBC driver connection URL",
                "expressions-allowed" => true,
                "nillable" => false,
                "min-length" => 1L,
                "max-length" => 2147483647L,
                "access-type" => "read-write",
                "storage" => "configuration",
                "restart-required" => "no-services"
            },
            "driver-class" => {
                "type" => STRING,
                "description" => "The fully qualified name of the JDBC driver class",
                "expressions-allowed" => true,
                "nillable" => true,
                "min-length" => 1L,
                "max-length" => 2147483647L,
                "access-type" => "read-write",
                "storage" => "configuration",
                "restart-required" => "no-services"
            },
            "datasource-class" => {
                "type" => STRING,
                "description" => "The fully qualified name of the JDBC datasource class",
                "expressions-allowed" => true,
                "nillable" => true,
                "min-length" => 1L,
                "max-length" => 2147483647L,
                "access-type" => "read-write",
                "storage" => "configuration",
                "restart-required" => "no-services"
            },
            "jndi-name" => {
                "type" => STRING,
                "description" => "Specifies the JNDI name for the datasource",
                "expressions-allowed" => true,
                "nillable" => false,
                "access-type" => "read-write",
                "storage" => "configuration",
                "restart-required" => "no-services"
            },
           ...
----

[[view-configuration-as-xml-for-domain-model-or-host-model]]
=== View configuration as XML for domain model or host model

Assume you have a host that is called "primary"

[source,options="nowrap"]
----
[domain@localhost:9990 /] attachment display --operation=/host=primary:read-config-as-xml-file
----

If you want to get the configuration of the server "main-one" hosted on "primary":

[source,options="nowrap"]
----
[domain@localhost:9990 /] attachment display --operation=/host=primary/server=main-one:read-config-as-xml-file
----

Just for the domain or standalone

[source,options="nowrap"]
----
[domain@localhost:9990 /] attachment display --operation=:read-config-as-xml-file
----

If you want to save the file you can use:
----
[standalone@localhost:9990 /] attachment save --operation=:read-config-as-xml-file --file=/home/wildfly/tmp/standalone-runtime.xml
----

Please note that the operation "read-config-as-xml" that used to return the XML as a String has been deprecated.


[[take-a-snapshot-of-what-the-current-domain-is]]
=== Take a snapshot of what the current domain is

[source,options="nowrap"]
----
[domain@localhost:9990 /] :take-snapshot()
{
    "outcome" => "success",
    "result" => {
        "domain-results" => {"step-1" => {"name" => "JBOSS_HOME/domain/configuration/domain_xml_history/snapshot/20110908-165222603domain.xml"}},
        "server-operations" => undefined
    }
}
----


[[take-the-latest-snapshot-of-the-host.xml-for-a-particular-host]]
=== Take the latest snapshot of the host.xml for a particular host

Assume you have a host that is called "primary"

[source,options="nowrap"]
----
[domain@localhost:9990 /]  /host=primary:take-snapshot
{
    "outcome" => "success",
    "result" => {
        "domain-results" => {"step-1" => {"name" => "JBOSS_HOME/domain/configuration/host_xml_history/snapshot/20110908-165640215host.xml"}},
        "server-operations" => undefined
    }
}
----

[[how-to-get-interface-address]]
=== How to get interface address

The attribute for interface is named "resolved-address". It's a runtime
attribute so it does not show up in :read-resource by default. You have
to add the "include-runtime" parameter.

[source,options="nowrap"]
----
./jboss-cli.sh --connect
Connected to standalone controller at localhost:9990
[standalone@localhost:9990 /] cd interface=public
[standalone@localhost:9990 interface=public] :read-resource(include-runtime=true)
{
     "outcome" => "success",
     "result" => {
         "any" => undefined,
         "any-address" => undefined,
         "any-ipv4-address" => undefined,
         "any-ipv6-address" => undefined,
         "criteria" => [("inet-address" => expression "${jboss.bind.address:127.0.0.1}")],
         "inet-address" => expression "${jboss.bind.address:127.0.0.1}",
         "link-local-address" => undefined,
         "loopback" => undefined,
         "loopback-address" => undefined,
         "multicast" => undefined,
         "name" => "public",
         "nic" => undefined,
         "nic-match" => undefined,
         "not" => undefined,
         "point-to-point" => undefined,
         "public-address" => undefined,
         "resolved-address" => "127.0.0.1",
         "site-local-address" => undefined,
         "subnet-match" => undefined,
         "up" => undefined,
         "virtual" => undefined
     }
}
[standalone@localhost:9990 interface=public] :read-attribute(name=resolved-address)
{
     "outcome" => "success",
     "result" => "127.0.0.1"
}
----

It's similar for domain, just specify path to server instance:

[source,options="nowrap"]
----
[domain@localhost:9990 /] /host=primary/server=server-one/interface=public:read-attribute(name=resolved-address)
{
    "outcome" => "success",
    "result" => "127.0.0.1"
}
----

[[runtime]]
== Runtime

[[get-all-configuration-and-runtime-details-from-cli]]
=== Get all configuration and runtime details from CLI

[source,options="nowrap"]
----
./bin/jboss-cli.sh -c command=":read-resource(include-runtime=true, recursive=true, recursive-depth=10)"
----

[[scripting]]
== Scripting

[[windows-and-press-any-key-to-continue-...-issue]]
=== Windows and "Press any key to continue ..." issue

WildFly scripts for Windows end with "Press any key to continue ...".
This behavior is useful when script is executed by double clicking the
script but not when you need to invoke several commands from custom
script (e.g. 'bin/jboss-admin.bat --connect command=:shutdown').

To avoid "Press any key to continue ..." message you need to specify
NOPAUSE variable. Call 'set NOPAUSE=true' in command line before running
any WildFly {wildflyVersion} .bat script or include it in your custom script before
invoking scripts from WildFly.

[[statistics]]
== Statistics

[[read-statistics-of-active-datasources]]
=== Read statistics of active datasources

[source,options="nowrap"]
----
/subsystem=datasources/data-source=ExampleDS/statistics=pool:read-resource(include-runtime=true)
/subsystem=datasources/data-source=ExampleDS/statistics=jdbc:read-resource(include-runtime=true)
----

or

[source,options="nowrap"]
----
/subsystem=datasources/data-source=ExampleDS:read-resource(include-runtime=true,recursive=true)
----

[[cli_deployment]]
== Deployment

[[cli-deployment-command]]
=== CLI _deployment_ command

In addition to the legacy _deploy_, _undeploy_ and _deployment-info_ commands,
that stay un-changed, the CLI offers a _deployment_ command that properly
separates the various use cases encountered when managing deployments. This command
offers a simpler interface and should be the way to go when managing deployments.
New features will be added thanks to the _deployment_ command, legacy commands will not evolve.
This document contains a summary of the capabilities of this command, type _help deployment_
to display the list of all available actions and _help deployment <action>_ for the detailed
description of an action.

Actions to deploy some content:

* _deployment deploy-file_: To deploy a file located on the file system.

* _deployment deploy-url_: To deploy content referenced by an URL.

* _deployment deploy-cli-achive_: To deploy some content thanks to a CLI archive
(.cli file) located on the file system.

Actions to enable some deployments:

* _deployment enable_: To enable a given disabled deployment.

* _deployment enable-all_: To enable all disabled deployments.

Actions to disable some deployments:

* _deployment disable_: To disable a given enabled deployment.

* _deployment disable-all_: To disable all enabled deployments.

Actions to undeploy some deployments:

* _deployment undeploy_: To undeploy a given deployment and remove its content
from the repository.

* _deployment undeploy-cli-archive_: To undeploy some content using a CLI archive
(.cli file) located on the file system.

Actions to get information on some deployments:

* _deployment info_: To display information about single or multiple deployments.

* _deployment list_: To display all the existing deployments.

[[incremental-deployment-with-the-cli]]
=== Incremental deployment with the CLI

It can be desirable to incrementally create and(or) update a WildFly
deployment. This chapter details how this can be achieved using the
WildFly CLI tool.

Steps to create an empty deployment and add an index html file.

1.  Create an empty deployment named my app:
+
[source,options="nowrap"]
----
[standalone@localhost:9990 /] /deployment=myapp:add(content=[{empty=true}])
----
2.  Add an index.html to my app:
+
[source,options="nowrap"]
----
[standalone@localhost:9990 /] /deployment=myapp:add-content(content=[{input-stream-index=<press TAB>
----
+
Then use completion to navigate to your index.html file.
3.  Provide a target name for index.html inside the deployment and
execute the operation:
+
[source,options="nowrap"]
----
[standalone@localhost:9990 /] /deployment=myapp:add-content(content=[{input-stream-index=./index.html, target-path=index.xhtml}]
----
4.  Your content has been added, you can browse the content of a
deployment using the browse-content operation:
+
[source,options="nowrap"]
----
[standalone@localhost:9990 /] /deployment=myapp:browse-content(path=./)
----
5.  You can display (or save) the content of a deployed file using the
_attachement_ command:
+
[source,options="nowrap"]
----
attachment display --operation=/deployment=myapp:read-content(path=index.xhtml)
----
6.  You can remove content from a deployment:
+
[source,options="nowrap"]
----
/deployment=myapp:remove-content(paths=[./index.xhtml])
----

Tips

[TIP]

* _add-content_ operation allows you to add more than one file (
_content_ argument is a list of complex types).
* CLI offers completion for __browse-conten__t's _path_ and
_remove-content_'s _paths_ argument.
* You can safely use operations that are using attached streams in batch
operations. In the case of batch operations, streams are attached to the
composite operation.

[WARNING]

On Windows, path separator '\' needs to be escaped, this is a limitation
of CLI handling complex types. The file path completion is automatically
escaping the paths it is proposing.

[[notes-for-server-side-operation-handler-implementors]]
==== Notes for server side operation Handler implementors

In order to benefit from CLI support for attached file streams and file
system completion, you need to properly structure your operation
arguments. Steps to create an operation that receives a list of file
streams attached to the operation:

1.  Define your operation argument as a _LIST_ of _INT_ (The _LIST_
_value-type_ must be of type _INT_).
2.  In the description of your argument, add the 2 following boolean
descriptors: _filesystem-path_ and _attached-streams_

When your operation is called from the CLI, file system completion will
be automatically proposed for your argument. At execution time, the file
system paths will be automatically converted onto the index of the
attached streams.

[[downloading-files-with-the-cli]]
== Downloading files with the CLI

Some management resources are exposing the content of files in the
matter of _streams_. Streams returned by a management operation are
attached to the headers of the management response. The CLI command
_attachment_ (see CLI help for a detailed description of this command)
allows to display or save the content of the attached streams.

* Displaying the content of server.log file:
+
[source,options="nowrap"]
----
attachment display --operation=/subsystem=logging/log-file=server.log:read-resource(include-runtime)
----
* Saving locally the server.log file:
+
[source,options="nowrap"]
----
attachment save --operation=/subsystem=logging/log-file=server.log:read-resource(include-runtime) --file=./server.log
----
* Displaying the content of a deployed file:
+
[source,options="nowrap"]
----
attachment display --operation=/deployment=myapp:read-content(path=index.xhtml)
----

[TIP]

* By default existing files will be preserved. Use the option
_--overwrite_ to overwrite existing file.
* _attachment_ can be used in batch mode.

[[iteration-of-collections]]
== Iteration of Collections

The command _for_ allows to iterate the content of an operation result. As an
example, this command can be used to display the content of the Manifest files
present in all deployed applications. For example:

[source,options="nowrap"]
----
for deployed in :read-children-names(child-type=deployment)
 echo $deployed Manifest content
 attachment display --operation=/deployment=$deployed:read-content(path=META-INF/MANIFEST.MF)
done
----
When this _for_ block is executed, the content of all Manifest files is displayed in the CLI console.

Tips

[TIP]

* The scope of the defined variable is limited to the _for_ block.
* If a variable with the same name already exists, the _for_ command will print an error.
* If the operation doesn't return a list, the _for_ command will print an error.
* _for_ block can be discarded and not execute by adding the option _--discard_ to _done_.

[[cli-security-commands]]
== Security Commands

CLi offers a _security_ command to group all security related management actions
under a single command.

* _security enable-ssl-management_: To enable SSL (elytron SSLContext) for the
management interfaces. Type _help security enable-ssl-management_ for a
complete description of the command.

Among other ways to configure SSL, this command offers an interactive wizard to
help you configure SSL by generating a self-signed certificate.
Example of wizard usage:

[source,options="nowrap"]
----
security enable-ssl-management --interactive
Please provide required pieces of information to enable SSL:
Key-store file name (default management.keystore):
Password (blank generated):
What is your first and last name? [Unknown]:
What is the name of your organizational unit? [Unknown]:
What is the name of your organization? [Unknown]:
What is the name of your City or Locality? [Unknown]:
What is the name of your State or Province? [Unknown]:
What is the two-letter country code for this unit? [Unknown]:
Is CN=Unknown, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown correct y/n [y]?
Validity (in days, blank default):
Alias (blank generated):
Enable SSL Mutual Authentication y/n (blank n):n

SSL options:
key store file: management.keystore
distinguished name: CN=Unknown, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown
password: KRzne5s1
validity: default
alias: alias-265e6c6d-ff4e-4b8c-8f10-f015d678eb29
Server keystore file management.keystore, certificate signing request management.csr and
certificate file management.keystore.pem will be generated in server configuration directory.
Do you confirm y/n :y
----
NB: Once the command is executed, the CLI will reload the server and reconnect to it.

This command can also obtain the certificates from the Let's Encrypt certificate authority
by use of the --lets-encrypt parameter.
Besides the mentioned workflow the user will be prompted to specify more information
(eg: account key store, certificate authority account) to obtain the certificate from Let's Encrypt.

* _security disable-ssl-management_: To disable SSL (elytron SSLContext) for the
management interfaces. Type _help security disable-ssl-management_ for
a complete description of the command.

* _security enable-ssl-http-server_: To enable SSL (elytron SSLContext) for the
_undertow_ server. The same wizard as the _enable-ssl-management_ action is available.
Type _help security enable-ssl-http-server_ for a complete description of the command.

This command can also obtain the certificates from the Let's Encrypt certificate authority
by use of the --lets-encrypt parameter.
Besides the mentioned workflow the user will be prompted to specify more information
(eg: account key store, certificate authority account) to obtain the certificate from Let's Encrypt.

* _security disable-ssl-http-server_: To disable SSL (elytron SSLContext) for the
_undertow_ server. Type _help security disable-ssl-http-server_ for a complete
description of the command.

* _security enable-sasl-management_: To enable SASL authentication (elytron SASL factory) for the
management interfaces. Calling this command without any option will have the
effect to associate the out of the box SASL factory to the http-interface.
Type _help security enable-sasl-management_ for a complete description of the command.

This command supports a subset of SASL mechanisms such as: EXTERNAL, DIGEST-MD5,
JBOSS-LOCAL-USER, SCRAM-*, ... The CLI completer proposes the set of mechanisms that
can be properly configured using this command. Each mechanism can be associated
to a property file realm, a file-system realm or a trust-store realm according to its nature.

NB: Once the command is executed, the CLI will reload the server and reconnect to it.

* _security disable-sasl-management_: To disable SASL for the
management interfaces. If a mechanism is provided, this mechanism will be removed
from the factory, the factory will stay associated to the interface. Without mechanism, the
factory is no more active on the management interface. Type _help security disable-sasl-management_
for a complete description of the command.

* _security reorder-sasl-management_: To re-order the list of SASL mechanisms present
in the factory. Order of mechanisms is of importance, the first in the list is sent to the client.
Type _help security reorder-sasl-management_ for a complete description of the command.

* _security enable-http-auth-management_: To enable HTTP authentication (elytron HTTP factory) for the
management http-interface. Calling this command without any option will have the
effect to associate the out of the box HTTP Authentication factory to the http-interface.
Type _help security enable-http-auth-management_ for a complete description of the command.

This command supports a subset of HTTP mechanisms such as: BASIC, CLIENT_CERT, DIGEST, ...
The CLI completer proposes the set of mechanisms that can be properly configured
using this command. Each mechanism can be associated to a property file realm,
a file-system realm or a trust-store realm according to its nature.

NB: Once the command is executed, the CLI will reload the server and reconnect to it.

* _security disable-http-auth-management_: To disable HTTP Authentication for the
http management interface. If a mechanism is provided, this mechanism will be removed
from the factory, the factory will stay associated to the interface. Without mechanism, the
factory is no more active on the management interface. Type _help security disable-http-auth-management_
for a complete description of the command.

* _security enable-http-auth-http-server_: To enable HTTP authentication (elytron HTTP factory) for the
given undertow security domain.
Type _help security enable-http-auth-http-server_ for a complete description of the command.

This command supports a subset of HTTP mechanisms such as: BASIC, CLIENT_CERT, DIGEST, ...
The CLI completer proposes the set of mechanisms that can be properly configured
using this command. Each mechanism can be associated to a property file realm,
a file-system realm or a trust-store realm according to its nature.

NB: Once the command is executed, the CLI will reload the server and reconnect to it.

* _security disable-http-auth-http-server_: To disable HTTP Authentication for the
given undertow security domain. If a mechanism is provided, this mechanism will be removed
from the factory, the factory will stay associated to the security domain. Without mechanism, the
factory is no more active on the security-domain. Type _help security disable-http-auth-http-server_
for a complete description of the command.

[[mp-cli-script]]
== Evolving standard configurations with support for MicroProfile

The CLI script _JBOSS_HOME/docs/examples/enable-microprofile.cli_ can be applied to a default standalone configuration
to add support for MicroProfile.

Impact on updated configuration:

* Addition of MicroProfile subsystems. 
* Removal of _security_ subsystem.
* Removal of _ManagementRealm_.
* Elytron security used for management and application entry points.
 
By default the script updates _standalone.xml_ configuration. 
Thanks to the _config=<config name>_ system property, the script can be applied to another standalone configuration.

NB: this script has to be applied _offline_ with no server running. 

* To update _standalone.xml_ server configuration:
** _./bin/jboss-cli.sh --file=docs/examples/enable-microprofile.cli_
* To update other standalone server configurations:
** _./bin/jboss-cli.sh --file=docs/examples/enable-microprofile.cli 
-Dconfig=<standalone-full.xml|standalone-ha.xml|standalone-full-ha.xml>_
