Skip to end of metadata
Go to start of metadata

Controlling operation via command line parameters

To start up a WildFly managed domain, execute the $JBOSS_HOME/bin/domain.sh script. To start up a standalone server, execute the $JBOSS_HOME/bin/standalone.sh. With no arguments, the default configuration is used. You can override the default configuration by providing arguments on the command line, or in your calling script.

System properties

To set a system property, pass its new value using the standard jvm -Dkey=value options:

This command starts up a standalone server instance using a non-standard AS home directory and a custom configuration directory. For specific information about system properties, refer to the definitions below.

Instead of passing the parameters directly, you can put them into a properties file, and pass the properties file to the script, as in the two examples below.

Note however, that properties set this way are not processed as part of JVM launch. They are processed early in the boot process, but this mechanism should not be used for setting properties that control JVM behavior (e.g. java.net.perferIPv4Stack) or the behavior of the JBoss Modules classloading system.

The syntax for passing in parameters and properties files is the same regardless of whether you are running the domain.sh, standalone.sh, or the Microsoft Windows scriptsdomain.bat or standalone.bat.

The properties file is a standard Java property file containing key=value pairs:

System properties can also be set via the xml configuration files. Note however that for a standalone server properties set this way will not be set until the xml configuration is parsed and the commands created by the parser have been executed. So this mechanism should not be used for setting properties whose value needs to be set before this point.

Controlling filesystem locations with system properties

The standalone and the managed domain modes each use a default configuration which expects various files and writable directories to exist in standard locations. Each of these standard locations is associated with a system property, which has a default value. To override a system property, pass its new value using the one of the mechanisms above. The locations which can be controlled via system property are:

Standalone
Property name Usage Default value
java.ext.dirs The JDK extension directory paths null
jboss.home.dir The root directory of the WildFly installation. Set by standalone.sh to $JBOSS_HOME
jboss.server.base.dir The base directory for server content. jboss.home.dir/standalone
jboss.server.config.dir The base configuration directory. jboss.server.base.dir/configuration
jboss.server.data.dir The directory used for persistent data file storage. jboss.server.base.dir/data
jboss.server.log.dir The directory containing the server.log file. jboss.server.base.dir/log
jboss.server.temp.dir The directory used for temporary file storage. jboss.server.base.dir/tmp
jboss.server.deploy.dir The directory used to store deployed content jboss.server.data.dir/content

Managed Domain
Property name Usage Default value
jboss.home.dir The root directory of the WildFly installation. Set by domain.sh to $JBOSS_HOME
jboss.domain.base.dir The base directory for domain content. jboss.home.dir/domain
jboss.domain.config.dir The base configuration directory jboss.domain.base.dir/configuration
jboss.domain.data.dir The directory used for persistent data file storage. jboss.domain.base.dir/data
jboss.domain.log.dir The directory containing the host-controller.log and process-controller.log files jboss.domain.base.dir/log
jboss.domain.temp.dir The directory used for temporary file storage jboss.domain.base.dir/tmp
jboss.domain.deployment.dir The directory used to store deployed content jboss.domain.base.dir/content
jboss.domain.servers.dir The directory containing the output for the managed server instances jboss.domain.base.dir/servers

Other command line parameters

The first acceptable format for command line arguments to the WildFly launch scripts is

For example:

If the parameter name is a single character, it is prefixed by a single '-' instead of two. Some parameters have both a long and short option.

For example:

For some command line arguments frequently used in previous major releases of WildFly, replacing the "=" in the above examples with a space is supported, for compatibility.

If possible, use the -x=value syntax. New parameters will always support this syntax.

The sections below describe the command line parameter names that are available in standalone and domain mode.

Standalone

Name Default if absent Value
--admin-only - Set the server's running type to ADMIN_ONLY causing it to open administrative interfaces and accept management requests but not start other runtime services or
accept end user requests.
--server-config
-c
standalone.xml A relative path which is interpreted to be relative to jboss.server.config.dir. The name of the configuration file to use.
--read-only-server-config - A relative path which is interpreted to be relative to jboss.server.config.dir. This is similar to --server-config but if this alternative is specified the server will
not overwrite the file when the management model is changed. However a full versioned history is maintained of the file.

Managed Domain

Name Default if absent Value
--admin-only - Set the server's running type to ADMIN_ONLY causing it to open administrative interfaces and accept management requests but not start servers or, if this host controller
is the master for the domain, accept incoming connections from slave host controllers.
--domain-config
-c
domain.xml A relative path which is interpreted to be relative to jboss.domain.config.dir. The name of the domain wide configuration file to use.
--read-only-domain-config - A relative path which is interpreted to be relative to jboss.domain.config.dir. This is similar to --domain-config but if this alternative is specified the host controller
will not overwrite the file when the management model is changed. However a full versioned history is maintained of the file.
--host-config host.xml A relative path which is interpreted to be relative to jboss.domain.config.dir. The name of the host-specific configuration file to use.
--read-only-host-config - A relative path which is interpreted to be relative to jboss.domain.config.dir. This is similar to --host-config but if this alternative is specified the host controller will
not overwrite the file when the management model is changed. However a full versioned history is maintained of the file.

The following parameters take no value and are only usable on slave host controllers (i.e. hosts configured to connect to a remote domain controller.)

Name Function
--backup Causes the slave host controller to create and maintain a local copy (domain.cached-remote.xml) of the domain configuration. If ignore-unused-configuration is unset in host.xml,
a complete copy of the domain configuration will be stored locally, otherwise the configured value of ignore-unused-configuration in host.xml will be used. (See ignore-unused-configuration for more details.)
--cached-dc If the slave host controller is unable to contact the master domain controller to get its configuration at boot, this option will allow the slave host controller to boot and become
operational using a previously cached copy of the domain configuration (domain.cached-remote.xml.) If the cached configuration is not present, this boot will fail. This file is created using using one of
the following methods:

  - A previously successful connection to the master domain controller using --backup or --cached-dc.
  - Copying the domain configuration from an alternative host to domain/configuration/domain.cached-remote.xml.

The unavailable master domain controller will be polled periodically for availability, and once becoming available, the slave host controller will reconnect to the master host controller and synchronize the domain 
configuration. During the interval the master domain controller is unavailable, the slave host controller will not be able make any modifications to the domain configuration, but it may launch servers and handle  
requests to deployed applications etc.
   

Common parameters

These parameters apply in both standalone or managed domain mode:

Name Function
-b=<value> Sets system property jboss.bind.address to <value>. See Controlling the Bind Address with -b for further details.
-b<name>=<value> Sets system property jboss.bind.address.<name> to <value> where name can vary. See Controlling the Bind Address with -b for further details.
-u=<value> Sets system property jboss.default.multicast.address to <value>. See Controlling the Default Multicast Address with -u for further details.
--version
-v
-V
Prints the version of WildFly to standard output and exits the JVM.
--help
-h
Prints a help message explaining the options and exits the JVM.

Controlling the Bind Address with -b

WildFly binds sockets to the IP addresses and interfaces contained in the <interfaces> elements in standalone.xml, domain.xml and host.xml. (See Interfaces and Socket Bindings for further information on these elements.) The standard configurations that ship with WildFly includes two interface configurations:

Those configurations use the values of system properties jboss.bind.address.management and jboss.bind.address if they are set. If they are not set, 127.0.0.1 is used for each value.

As noted in Common Parameters, the AS supports the -b and -b<name> command line switches. The only function of these switches is to set system properties jboss.bind.address and jboss.bind.address.<name> respectively. However, because of the way the standard WildFly configuration files are set up, using the -b switches can indirectly control how the AS binds sockets.

If your interface configurations match those shown above, using this as your launch command causes all sockets associated with interface named "public"  to be bound to 192.168.100.10.

In the standard config files, public interfaces are those not associated with server management. Public interfaces handle normal end-user requests.

Interface names
The interface named "public" is not inherently special. It is provided as a convenience. You can name your interfaces to suit your environment.

To bind the public interfaces to all IPv4 addresses (the IPv4 wildcard address), use the following syntax:

You can also bind the management interfaces, as follows:

In the standard config files, management interfaces are those sockets associated with server management, such as the socket used by the CLI, the HTTP socket used by the admin console, and the JMX connector socket.

Be Careful
The -b switch only controls the interface bindings because the standard config files that ship with WildFly sets things up that way. If you change the <interfaces> section in your configuration to no longer use the system properties controlled by -b, then setting -b in your launch command will have no effect.

For example, this perfectly valid setting for the "public" interface causes  -b to have no effect on the "public" interface:

The key point is the contents of the configuration files determine the configuration. Settings like -b are not overrides of the configuration files. They only provide a shorter syntax for setting a system properties that may or may not be referenced in the configuration files. They are provided as a convenience, and you can choose to modify your configuration to ignore them.

Controlling the Default Multicast Address with -u

WildFly may use multicast communication for some services, particularly those involving high availability clustering. The multicast addresses and ports used are configured using the socket-binding elements in standalone.xml and domain.xml. (See Socket Bindings for further information on these elements.) The standard HA configurations that ship with WildFly include two socket binding configurations that use a default multicast address:

Those configurations use the values of system property jboss.default.multicast.address if it is set. If it is not set, 230.0.0.4 is used for each value. (The configuration may include other socket bindings for multicast-based services that are not meant to use the default multicast address; e.g. a binding the mod-cluster services use to communicate on a separate address/port with Apache httpd servers.)

As noted in Common Parameters, the AS supports the -u command line switch. The only function of this switch is to set system property jboss.default.multicast.address. However, because of the way the standard AS configuration files are set up, using the -u switches can indirectly control how the AS uses multicast.

If your socket binding configurations match those shown above, using this as your launch command causes the service using those sockets configurations to be communicate over multicast address 230.0.1.2.

Be Careful
As with the -b switch, the -u switch only controls the multicast address used because the standard config files that ship with WildFly sets things up that way. If you change the <socket-binding> sections in your configuration to no longer use the system properties controlled by -u, then setting -u in your launch command will have no effect.

Suspend, resume and graceful shutdown

Core Concepts

Wildfly introduces the ability to suspend and resume servers. This can be combined with shutdown to enable the server to gracefully finish processing all active requests and then shut down. When a server is suspended it will immediately stop accepting new requests, but wait for existing request to complete. A suspended server can be resumed at any point, and will begin processing requests immediately. Suspending and resuming has no effect on deployment state (e.g. if a server is suspended singleton EJB's will not be destroyed). As of Wildfly 11 it is also possible to start a server in suspended mode which means it will not accept requests until it has been resumed, servers will also be suspended during the boot process, so no requests will be accepted until the startup process is 100% complete.

Suspend/Resume has no effect on management operations, management operations can still be performed while a server is suspended. If you wish to perform a management operation that will affect the operation of the server (e.g. changing a datasource) you can suspend the server, perform the operation, then resume the server. This allows all requests to finish, and makes sure that no requests are running while the management changes are taking place.

When a server is suspending it goes through four different phases:

  • RUNNING - The normal state, the server is accepting requests and running normally
  • PRE_SUSPEND - In PRE_SUSPEND the server will notify external parties that it is about to suspend, for example mod_cluster will notify the load balancer that the deployment is suspending. Requests are still accepted in this phase.
  • SUSPENDING - All new requests are rejected, and the server is waiting for all active requests to finish. If there are no active requests at suspend time this phase will be skipped.
  • SUSPENDED - All requests have completed, and the server is suspended.

Starting Suspended

In order to start into suspended mode when using a standalone server you need to add --start-mode=suspend to the command line. It is also possible to specify the start-mode in the reload operation to cause the server to reload into suspended mode (other possible values for start-mode are normal and admin-only).

In domain mode servers can be started in suspended mode by passing the suspend=true parameter to any command that causes a server to start, restart or reload (e.g. :start-servers(suspend=true)).

The Request Controller Subsystem

Wildfly introduces a new subsystem called the Request Controller Subsystem. This optional subsystem tracks all requests at their entry point, which how the graceful shutdown mechanism know when all requests are done (it also allows you to provide a global limit on the total number of running requests). 

If this subsystem is not present suspend/resume will be limited, in general things that happen in the PRE_SUSPEND phase will work as normal (stopping message delivery, notifying the load balancer), however the server will not wait for all requests to complete and instead move straight to SUSPENDED mode.

There is a small performance penalty associated with the request controller subsystem (about on par with enabling statistics), so if you do not require the suspend/resume functionality this subsystem can be removed to get a small performance boost.

Subsystem Integrations

Suspend/Resume is a service provided by the Wildfly platform that any subsystem may choose to integrate with. Some subsystems integrate directly with the suspend controller, while others integrate through the request controller subsystem.

The following subsystems support graceful shutdown. Note that only subsystems that provide an external entry point to the server need graceful shutdown support, for example the JAX-RS subsystem does not require suspend/resume support as all access to JAX-RS is through the web connector.

  • Undertow - Undertow will wait for all requests to finish
  • mod_cluster - The mod_cluster subsystem will notify the load balancer that the server is suspending in the PRE_SUSPEND phase.
  • EJB - EJB will wait for all remote EJB requests and MDB message deliveries to finish. Delivery to MDB's is stopped in the PRE_SUSPEND phase. EJB timers are suspended, and missed timers will be activated when the server is resumed. 
  • Batch - Batch jobs will be stopped at a checkpoint while the server is suspending. They will be restarted from that checkpoint when the server returns to running mode.
  • EE Concurrency - The server will wait for all active jobs to finish. All jobs that have already been queued will be skipped.
  • Transactions - transaction subsystem waits for all running transactions to finish while server is suspending. During that time server refuses to start any new transaction. But any in-flight transaction will be serviced - e.g. it means that server accepts any incoming remote call which carries context of the transaction already started at the suspending server.
    When you work with EJBs you have to enable the graceful shutdown functionality by setting attribute enable-graceful-txn-shutdown to true.
    (at the ejb3 subsystem xml, for example):
    <enable-graceful-txn-shutdown value="false"/>
    By default graceful shutdown it's disabled for ejb subsystem.
    The reason is that the behavior might be unwelcome in cluster environments, as the server notifies remote clients that the node is no longer available for remote calls only after the transactions are finished. During that brief window of time, the client of a cluster may send a new request to a node that is shutting down and will refuse the request because it is not related to an existing transaction.
    If this attribute enable-graceful-txn-shutdown is set to false, we disable the graceful behavior and EJB clients will not attempt to invoke the node when it suspends, regardless of active transactions.

Standalone Mode

Suspend/Resume can be controlled via the following CLI operations in standalone mode:

:suspend(timeout=z)

Suspends the server. If the timeout is specified it will wait up to the specified number of seconds for all requests to finish. If there is no timeout specified or the value is less than zero it will wait indefinitely. 

:resume

Resumes a previously suspended server. The server should be able to begin serving requests immediately. 

:read-attribute(name=suspend-state)

Returns the current suspend state of the server.

:shutdown(timeout=x)

If a timeout parameter is passed to the shutdown command then a graceful shutdown will be performed. The server will be suspended, and will wait up to the specified number of seconds for all requests to finish before shutting down. A timeout value of less than zero means it will wait indefinitely. 

Domain Mode

Domain mode has similar commands as standalone mode, however they can be applied at both the global and server group levels:

Whole Domain

:suspend-servers(timeout=x)

:resume-servers

:stop-servers(timeout=x)

Server Group

/server-group=main-server-group:suspend-servers(timeout=x)

/server-group=main-server-group:resume-servers

/server-group=main-server-group:stop-servers(timeout=x)

Server 

/host=master/server-config=server-one:suspend(timeout=x)

/host=master/server-config=server-one:resume

/host=master/server-config=server-one:stop(timeout=x)

Starting & stopping Servers in a Managed Domain

Starting a standalone server is done through the bin/standalone.sh script. However in a managed domain server instances are managed by the domain controller and need to be started through the management layer:

First of all, get to know which servers are configured on a particular host:

Now that we know, that there are two servers configured on host "local", we can go ahead and check their status:

You can change the server state through the "start" and "stop" operations

Navigating through the domain topology is much more simple when you use the web interface.

Controlling JVM settings

Configuration of the JVM settings is different for a managed domain and a standalone server. In a managed domain, the domain controller components are responsible for starting and stoping server processes and hence determine the JVM settings. For a standalone server, it's the responsibility of the process that started the server (e.g. passing them as command line arguments).

Managed Domain

In a managed domain the JVM settings can be declared at different scopes: For a specific server group, for a host or for a particular server. If not declared, the settings are inherited from the parent scope. This allows you to customize or extend the JVM settings within every layer.

Let's take a look at the JVM declaration for a server group:

(See domain/configuration/domain.xml)

In this example the server group "main-server-group" declares a heap size of 64m and a maximum heap size of 512m. Any server that belongs to this group will inherit these settings. You can change these settings for the group as a whole, or a specific server or host:

(See domain/configuration/host.xml)

In this case, server-two, belongs to the main-server-group and inherits the JVM settings named default, but declares a lower maximum heap size.

Standalone Server

For a standalone sever you have to pass in the JVM settings either as command line arguments when executing the $JBOSS_HOME/bin/standalone.sh script, or by declaring them in $JBOSS_HOME/bin/standalone.conf. (For Windows users, the script to execute is %JBOSS_HOME%/bin/standalone.bat while the JVM settings can be declared in %JBOSS_HOME%/bin/standalone.conf.bat.)

Administrative audit logging

WildFly comes with audit logging built in for management operations affecting the management model. By default it is turned off. The information is output as JSON records.

The default configuration of audit logging in standalone.xml looks as follows:

Looking at this via the CLI it looks like

To enable it via CLI you need just

Audit data are stored in standalone/data/audit-log.log.

The audit logging subsystem has a lot of internal dependencies, and it logs operations changing, enabling and disabling its components. When configuring or changing things at runtime it is a good idea to make these changes as part of a CLI batch. For example if you are adding a syslog handler you need to add the handler and its information as one step. Similarly if you are using a file handler, and want to change its path and relative-to attributes, that needs to happen as one step.

JSON Formatter

The first thing that needs configuring is the formatter, we currently support outputting log records as JSON. You can define several formatters, for use with different handlers. A log record has the following format, and it is the formatter's job to format the data presented:

It includes an optional timestamp and then the following information in the json record

Field name Description
type This can have the values core, meaning it is a management operation, or jmx meaning it comes from the jmx subsystem (see the jmx subsystem for configuration of the jmx subsystem's audit logging)
r/o true if the operation does not change the management model, false otherwise
booting true if the operation was executed during the bootup process, false if it was executed once the server is up and running
version The version number of the WildFly instance
user The username of the authenticated user. In this case the operation has been logged via the CLI on the same machine as the running server, so the special $local user is used
domainUUID An ID to link together all operations as they are propagated from the Doman Controller to it servers, slave Host Controllers, and slave Host Controller servers
access This can have one of the following values:
*NATIVE - The operation came in through the native management interface, for example the CLI
*HTTP - The operation came in through the domain HTTP interface, for example the admin console
*JMX - The operation came in through the JMX subsystem. See JMX for how to configure audit logging for JMX.
remote-address The address of the client executing this operation
success true if the operation succeeded, false if it was rolled back
ops The operations being executed. This is a list of the operations serialized to JSON. At boot this will be all the operations resulting from parsing the xml. Once booted the list will typically just contain a single entry

The json formatter resource has the following attributes:

Attribute Description
include-date Boolan toggling whether or not to include the timestamp in the formatted log records
date-separator A string containing characters to separate the date and the rest of the formatted log message. Will be ignored if include-date=false
date-format The date format to use for the timestamp as understood by java.text.SimpleDateFormat. Will be ignored if include-date=false
compact If true will format the JSON on one line. There may still be values containing new lines, so if having the whole record on one line is important, set escape-new-line or escape-control-characters to true
escape-control-characters If true it will escape all control characters (ascii entries with a decimal value < 32) with the ascii code in octal, e.g. a new line becomes '#012'. If this is true, it will override escape-new-line=false
escape-new-line If true it will escape all new lines with the ascii code in octal, e.g. "#012".

Handlers

A handler is responsible for taking the formatted data and logging it to a location. There are currently two types of handlers, File and Syslog. You can configure several of each type of handler and use them to log information.

File handler

The file handlers log the audit log records to a file on the server. The attributes for the file handler are

Attribute Description Read Only
formatter The name of a JSON formatter to use to format the log records false
path The path of the audit log file false
relative-to The name of another previously named path, or of one of the standard paths provided by the system. If relative-to is provided, the value of the path attribute is treated as relative to the path specified by this attribute false
failure-count The number of logging failures since the handler was initialized true
max-failure-count The maximum number of logging failures before disabling this handler false
disabled-due-to-failure true if this handler was disabled due to logging failures true

In our standard configuration path=audit-log.log and relative-to=jboss.server.data.dir, typically this will be $JBOSS_HOME/standalone/data/audit-log.log

Syslog handler

The default configuration does not have syslog audit logging set up. Syslog is a better choice for audit logging since you can log to a remote syslog server, and secure the authentication to happen over TLS with client certificate authentication. Syslog servers vary a lot in their capabilities so not all settings in this section apply to all syslog servers. We have tested with rsyslog.

The address for the syslog handler is /core-service=management/access=audit/syslog-handler=* and just like file handlers you can add as many syslog entries as you like. The syslog handler resources reference the main RFC's for syslog a fair bit, for reference they can be found at:
*http://www.ietf.org/rfc/rfc3164.txt
*http://www.ietf.org/rfc/rfc5424.txt
*http://www.ietf.org/rfc/rfc6587.txt

The syslog handler resource has the following attributes:

formatter The name of a JSON formatter to use to format the log records false
failure-count The number of logging failures since the handler was initialized true
max-failure-count The maximum number of logging failures before disabling this handler false
disabled-due-to-failure true if this handler was disabled due to logging failures true
syslog-format Whether to set the syslog format to the one specified in RFC-5424 or RFC-3164 false
max-length The maximum length in bytes a log message, including the header, is allowed to be. If undefined, it will default to 1024 bytes if the syslog-format is RFC3164, or 2048 bytes if the syslog-format is RFC5424. false
truncate Whether or not a message, including the header, should truncate the message if the length in bytes is greater than the maximum length. If set to false messages will be split and sent with the same header values false

When adding a syslog handler you also need to add the protocol it will use to communicate with the syslog server. The valid choices for protocol are UDP,TCP and TLS. The protocol must be added at the same time as you add the syslog handler, or it will fail. Also, you can only add one protocol for the handler.

UDP

Configures the handler to use UDP to communicate with the syslog server. The address of the UDP resource is /core-service=management/access=audit/syslog-handler=*/protocol=udp. The attributes of the UDP resource are:

Attribute Description
host The host of the syslog server for the udp requests
port The port of the syslog server listening for the udp requests
TCP

Configures the handler to use TCP to communicate with the syslog server. The address of the TCP resource is /core-service=management/access=audit/syslog-handler=*/protocol=tcp. The attributes of the TCP resource are:

Attribute Description
host The host of the syslog server for the tcp requests
port The port of the syslog server listening for the tcp requests
message-transfer The message transfer setting as described in section 3.4 of RFC-6587. This can either be OCTET_COUNTING as described in section 3.4.1 of RFC-6587, or NON_TRANSPARENT_FRAMING as described in section 3.4.1 of RFC-6587
TLS

Configures the handler to use TLC to communicate securely with the syslog server. The address of the TLS resource is /core-service=management/access=audit/syslog-handler=*/protocol=tls. The attributes of the TLS resource are the same as for TCP:

Attribute Description
host The host of the syslog server for the tls requests
port The port of the syslog server listening for the tls requests
message-transfer The message transfer setting as described in section 3.4 of RFC-6587. This can either be OCTET_COUNTING as described in section 3.4.1 of RFC-6587, or NON_TRANSPARENT_FRAMING as described in section 3.4.1 of RFC-6587

If the syslog server's TLS certificate is not signed by a certificate signing authority, you will need to set up a truststore to trust the certificate. The resource for the trust store is a child of the TLS resource, and the full address is /core-service=management/access=audit/syslog-handler=*/protocol=tls/authentication=truststore. The attributes of the truststore resource are:

Attribute Description
keystore-password The password for the truststore
keystore-path The path of the truststore
keystore-relative-to The name of another previously named path, or of one of the standard paths provided by the system. If keystore-relative-to is provided, the value of the keystore-path attribute is treated as relative to the path specified by this attribute
TLS with Client certificate authentication.

If you have set up the syslog server to require client certificate authentication, when creating your handler you will also need to set up a client certificate store containing the certificate to be presented to the syslog server. The address of the client certificate store resource is /core-service=management/access=audit/syslog-handler=*/protocol=tls/authentication=client-certificate-store and its attributes are:

Attribute Description
keystore-password The password for the keystore
key-password The password for the keystore key
keystore-path The path of the keystore
keystore-relative-to The name of another previously named path, or of one of the standard paths provided by the system. If keystore-relative-to is provided, the value of the keystore-path attribute is treated as relative to the path specified by this attribute

Logger configuration

The final part that needs configuring is the logger for the management operations. This references one or more handlers and is configured at /core-service=management/access=audit/logger=audit-log. The attributes for this resource are:

Attribute Description
enabled true to enable logging of the management operations
log-boot true to log the management operations when booting the server, false otherwise
log-read-only If true all operations will be audit logged, if false only operations that change the model will be logged

Then which handlers are used to log the management operations are configured as handler=* children of the logger.

Domain Mode (host specific configuration)

In domain mode audit logging is configured for each host in its host.xml file. This means that when connecting to the DC, the configuration of the audit logging is under the host's entry, e.g. here is the default configuration:

We now have two file handlers, one called host-file used to configure the file to log management operations on the host, and one called server-file used to log management operations executed on the servers. Then logger=audit-log is used to configure the logger for the host controller, referencing the host-file handler. server-logger=audit-log is used to configure the logger for the managed servers, referencing the server-file handler. The attributes for server-logger=audit-log are the same as for server-logger=audit-log in the previous section. Having the host controller and server loggers configured independently means we can control audit logging for managed servers and the host controller independently. 

Canceling management operations

WildFly includes the ability to use the CLI to cancel management requests that are not proceeding normally.

The cancel-non-progressing-operation operation

The cancel-non-progressing-operation operation instructs the target process to find any operation that isn't proceeding normally and cancel it.

On a standalone server:

The result value is an internal identification number for the operation that was cancelled.

On a managed domain host controller, the equivalent resource is in the host=<hostname> portion of the management resource tree:

An operation can be cancelled on an individual managed domain server as well:

An operation is considered to be not proceeding normally if it has been executing with the exclusive operation lock held for longer than 15 seconds. Read-only operations do not acquire the exclusive operation lock, so this operation will not cancel read-only operations. Operations blocking waiting for another operation to release the exclusive lock will also not be cancelled.

If there isn't any operation that is failing to proceed normally, there will be a failure response:

The find-non-progressing-operation operation

To simply learn the id of an operation that isn't proceeding normally, but not cancel it, use the find-non-progressing-operation operation:

If there is no non-progressing operation, the outcome will still be success but the result will be undefined.

Once the id of the operation is known, the management resource for the operation can be examined to learn more about its status.

Examining the status of an active operation

There is a management resource for any currently executing operation that can be queried:

The response includes the following attributes:

Field Meaning
access-mechanism The mechanism used to submit a request to the server. NATIVE, JMX, HTTP
address The address of the resource targeted by the operation. The value in the final element of the address will be '<hidden>' if the caller is not authorized to address the operation's target resource.
caller-thread The name of the thread that is executing the operation.
cancelled Whether the operation has been cancelled.
exclusive-running-time Amount of time in nanoseconds the operation has been executing with the exclusive operation execution lock held, or -1 if the operation does not hold the exclusive execution lock.
execution-status The current activity of the operation. See below for details.
operation The name of the operation, or '<hidden>' if the caller is not authorized to address the operation's target resource.
running-time Amount of time the operation has been executing, in nanoseconds.

The following are the values for the execution-status attribute:

Value Meaning
executing The caller thread is actively executing
awaiting-other-operation The caller thread is blocking waiting for another operation to release the exclusive execution lock
awaiting-stability The caller thread has made changes to the service container and is waiting for the service container to stabilize
completing The operation is committed and is completing execution
rolling-back The operation is rolling back

All currently executing operations can be viewed in one request using the read-children-resources operation:

Canceling a specific operation

The cancel-non-progressing-operation operation is a convenience operation for identifying and canceling an operation. However, an administrator can examine the active-operation resources to identify any operation, and then directly cancel it by invoking the cancel operation on the resource for the desired operation.

Controlling operation blocking time

As an operation executes, the execution thread may block at various points, particularly while waiting for the service container to stabilize following any changes. Since an operation may be holding the exclusive execution lock while blocking, in WildFly execution behavior was changed to ensure that blocking will eventually time out, resulting in roll back of the operation.

The default blocking timeout is 300 seconds. This is intentionally long, as the idea is to only trigger a timeout when something has definitely gone wrong with the operation, without any false positives.

An administrator can control the blocking timeout for an individual operation by using the blocking-timeout operation header. For example, if a particular deployment is known to take an extremely long time to deploy, the default 300 second timeout could be increased:

Note the blocking timeout is not a guaranteed maximum execution time for an operation. If it only a timeout that will be enforced at various points during operation execution.

Configuration file history

The management operations may modify the model. When this occurs the xml backing the model is written out again reflecting the latest changes. In addition a full history of the file is maintained. The history of the file goes in a separate directory under the configuration directory.

As mentioned in Command line parameters#parameters the default configuration file can be selected using a command-line parameter. For a standalone server instance the history of the active standalone.xml is kept in jboss.server.config.dir/standalone_xml_history (See Command line parameters#standalone_system_properties for more details). For a domain the active domain.xml and host.xml histories are kept in jboss.domain.config.dir/domain_xml_history and jboss.domain.config.dir/host_xml_history.

The rest of this section will only discuss the history for standalone.xml. The concepts are exactly the same for domain.xml and host.xml.

Within standalone_xml_history itself following a successful first time boot we end up with three new files:

  • standalone.initial.xml - This contains the original configuration that was used the first time we successfully booted. This file will never be overwritten. You may of course delete the history directory and any files in it at any stage.
  • standalone.boot.xml - This contains the original configuration that was used for the last successful boot of the server. This gets overwritten every time we boot the server successfully.
  • standalone.last.xml - At this stage the contents will be identical to standalone.boot.xml. This file gets overwritten each time the server successfully writes the configuration, if there was an unexpected failure writing the configuration this file is the last known successful write.

standalone_xml_history contains a directory called current which should be empty. Now if we execute a management operation that modifies the model, for example adding a new system property using the CLI:

What happens is:

  • The original configuration file is backed up to standalone_xml_history/current/standalone.v1.xml. The next change to the model would result in a file called standalone.v2.xml etc. The 100 most recent of these files are kept.
  • The change is applied to the original configuration file
  • The changed original configuration file is copied to standalone.last.xml

When restarting the server, any existing standalone_xml_history/current directory is moved to a new timestamped folder within the standalone_xml_history, and a new current folder is created. These timestamped folders are kept for 30 days.

Snapshots

In addition to the backups taken by the server as described above you can manually take take snapshots which will be stored in the snapshot folder under the _xml_history folder, the automatic backups described above are subject to automatic house keeping so will eventually be automatically removed, the snapshots on the other hand can be entirely managed by the administrator.

You may also take your own snapshots using the CLI:

You can also use the CLI to list all the snapshots

 To delete a particular snapshot:

and to delete all snapshots:

In domain mode executing the snapshot operations against the root node will work against the domain model. To do this for a host model you need to navigate to the host in question:

Subsequent Starts

For subsequent server starts it may be desirable to take the state of the server back to one of the previously known states, for a number of items an abbreviated reverence to the file can be used:

Abreviation
Parameter
Description
initial
--server-config=initial
This will start the server using the initial configuration first used to start the server.
boot
--server-config=boot
This will use the configuration from the last successful boot of the server.
last
--server-config=last
This will start the server using the configuration backed up from the last successful save.
v?
--server-config=v?
This will server the _xml_history/current folder for the configuration where ? is the number of the backup to use.
-?
--server-config=-? The server will be started after searching the snapshot folder for the configuration which matches this prefix.

In addition to this the --server-config parameter can always be used to specify a configuration relative to the jboss.server.config.dir and finally if no matching configuration is found an attempt to locate the configuration as an absolute path will be made.

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.