Chapter 2. Starting and Stopping JBoss EAP
2.1. Starting JBoss EAP
JBoss EAP is supported on Red Hat Enterprise Linux, Windows Server, Oracle Solaris, and Hewlett-Packard HP-UX, and runs in either a standalone server or managed domain operating mode. The specific command to start JBoss EAP depends on the underlying platform and the desired operating mode.
Servers are initially started in a suspended state and will not accept any requests until all required services have started, at which time the servers are placed into a normal running state and can start accepting requests.
Start JBoss EAP as a Standalone Server
$ EAP_HOME/bin/standalone.sh
For Windows Server, use the EAP_HOME\bin\standalone.bat
script.
This startup script uses the EAP_HOME/bin/standalone.conf
file, or standalone.conf.bat
for Windows Server, to set some default preferences, such as JVM options. You can customize the settings in this file.
JBoss EAP uses the standalone.xml
configuration file by default, but can be started using a different one. For details on the available standalone configuration files and how to use them, see the Standalone Server Configuration Files section.
For a complete listing of all available startup script arguments and their purposes, use the --help
argument or see the Server Runtime Arguments section.
Start JBoss EAP in a Managed Domain
The domain controller must be started before the servers in any of the server groups in the domain. Use this script to first start the domain controller, and then for each associated host controller.
$ EAP_HOME/bin/domain.sh
For Windows Server, use the EAP_HOME\bin\domain.bat
script.
This startup script uses the EAP_HOME/bin/domain.conf
file, or domain.conf.bat
for Windows Server, to set some default preferences, such as JVM options. You can customize the settings in this file.
JBoss EAP uses the host.xml
host configuration file by default, but can be started using a different one. For details on the available managed domain configuration files and how to use them, see the Managed Domain Configuration Files section.
When setting up a managed domain, additional arguments will need to be passed into the startup script. For a complete listing of all available startup script arguments and their purposes, use the --help
argument or see the Server Runtime Arguments section.
2.2. Stopping JBoss EAP
The way that you stop JBoss EAP depends on how it was started.
Stop an Interactive Instance of JBoss EAP
Press Ctrl+C
in the terminal where JBoss EAP was started.
Stop a Background Instance of JBoss EAP
Use the management CLI to connect to the running instance and shut down the server.
Launch the management CLI.
$ EAP_HOME/bin/jboss-cli.sh --connect
Issue the
shutdown
command.shutdown
When running in a managed domain, you must specify the host name to shut down by using the --host
argument with the shutdown
command.
2.3. Running JBoss EAP in Admin-only Mode
JBoss EAP has the ability to be started in admin-only mode. This enables JBoss EAP to run and accept management requests but not start other runtime services or accept end user requests. Admin-only mode is available in both standalone servers as well as managed domains.
Running a Standalone Server in Admin-only Mode
Start the Server in Admin-only Mode
To start a JBoss EAP instance in admin-only mode, use the --start-mode=admin-only
runtime argument when starting the JBoss EAP instance.
$ EAP_HOME/bin/standalone.sh --start-mode=admin-only
Check If the Server is Running in Admin-only Mode
Use the following command to check the running mode of the server. The result will be ADMIN_ONLY
if the server is running in admin-only mode.
:read-attribute(name=running-mode) { "outcome" => "success", "result" => "ADMIN_ONLY" }
Additionally, you can check the initial running mode in which JBoss EAP was launched by using the following command.
/core-service=server-environment:read-attribute(name=initial-running-mode)
Reload in a Different Mode from the Management CLI
In addition to stopping and starting a JBoss EAP instance with a different runtime switch, the management CLI may also be used to reload it in a different mode.
To reload the server in admin-only mode:
reload --start-mode=admin-only
To reload the server in normal mode:
reload --start-mode=normal
Note that if the server was started in admin-only mode and no --start-mode
argument is specified to the reload
command, the server will be started in normal mode.
Running a Managed Domain in Admin-only Mode
In a managed domain, if a domain controller is started in admin-only mode, it will not accept incoming connections from slave host controllers.
Start a Host Controller in Admin-only Mode
Pass in the --admin-only
runtime argument to start a host controller in admin-only mode.
$ EAP_HOME/bin/domain.sh --admin-only
Check If a Host Controller is Running in Admin-only Mode
Use the following command to check the running mode of a host controller. The result will be ADMIN_ONLY
if the host controller is running in admin-only mode.
/host=HOST_NAME:read-attribute(name=running-mode)
{
"outcome" => "success",
"result" => "ADMIN_ONLY"
}
Reload in a Different Mode from the Management CLI
In addition to stopping and starting a host controller with a different runtime switch, the management CLI may also be used to reload it in a different mode.
To reload the host controller in admin-only mode:
reload --host=HOST_NAME --admin-only=true
To reload a host controller in normal mode:
reload --host=HOST_NAME --admin-only=false
Note that if the host controller was started in admin-only mode and no --admin-only
argument is specified to the reload
command, the host controller will be started in normal mode.
2.4. Suspend and Shut Down JBoss EAP Gracefully
JBoss EAP can be suspended or shut down gracefully. This allows active requests to complete normally, without accepting any new requests. A timeout value specifies how long that the suspend or shut down operation will wait for active requests to complete. While the server is suspended, management requests are still processed.
Graceful shutdown is coordinated at a server-wide level, mostly focused on the entry points at which a request enters the server. The following subsystems support graceful shutdown:
- Undertow
-
The
undertow
subsystem will wait for all requests to finish. - mod_cluster
-
The
modcluster
subsystem will notify the load balancer that the server is suspending in thePRE_SUSPEND
phase. - EJB
-
The
ejb3
subsystem will wait for all remote EJB requests and MDB message deliveries to finish. Delivery to MDBs is stopped in thePRE_SUSPEND
phase. EJB timers are suspended, and missed timers will be activated when the server is resumed. - Transactions
Once suspended, the server will not accept new requests, but in-flight transactions and requests are allowed to continue until they complete or until the timeout period expires. This also applies for web service requests associated with an XTS transaction.
NoteBy default, transaction graceful shutdown is disabled for the
ejb
subsystem. You must enable transaction graceful shutdown if you want the server to wait for EJB-related transactions to complete before suspending. For example:/subsystem=ejb3:write-attribute(name=enable-graceful-txn-shutdown,value=true)
- EE Concurrency
The server will wait for all active jobs to finish. All queued jobs will be skipped. Currently, since EE Concurrency does not have persistence, those queued jobs that were skipped will be lost.
While the server is in a suspended state, scheduled tasks will continue to execute at their scheduled times but will throw a
java.lang.IllegalStateException
. Once the server is resumed, scheduled tasks will continue to execute normally, and in most cases tasks will not need to be rescheduled.- Batch
- The server will stop all running jobs within the timeout period and defer all scheduled jobs.
Graceful shutdown currently will not reject new inbound JMS messages. EE batch jobs and EE concurrency tasks scheduled by in-flight activity are currently allowed to proceed; however, EE concurrency tasks submitted that pass the timeout window currently error when executed.
Requests are tracked by the request-controller
subsystem. Without this subsystem, suspend and resume capabilities are limited and the server will not wait for requests to complete before suspending or shutting down; however, if you do not need this capability, the request-controller
subsystem can be removed for a small performance improvement.
2.4.1. Suspend Servers
JBoss EAP 7 introduced a suspend mode, which suspends server operations gracefully. This allows all active requests to complete normally, but will not accept any new requests. Once the server has been suspended, it can be shut down, returned back to a running state, or left in a suspended state to perform maintenance.
The management interfaces are not impacted by suspending the server.
The server can be suspended and resumed using the management console or the management CLI.
Check the Server Suspend State
The server suspend state can be viewed using the following management CLI commands. The resulting value will be one of RUNNING
, PRE_SUSPEND
, SUSPENDING
, or SUSPENDED
.
Check the suspend state for a standalone server.
:read-attribute(name=suspend-state)
Check the suspend state for a server in a managed domain.
/host=master/server=server-one:read-attribute(name=suspend-state)
Suspend
Use the following management CLI commands to suspend the server, specifying the timeout value, in seconds, for the server to wait for active requests to complete. The default is 0
, which will suspend immediately. A value of -1
will cause the server to wait indefinitely for all active requests to complete.
Each example waits up to 60 seconds for requests to complete before suspending.
Suspend a standalone server.
:suspend(timeout=60)
Suspend all servers in a managed domain.
:suspend-servers(timeout=60)
Suspend a single server in a managed domain.
/host=master/server-config=server-one:suspend(timeout=60)
Suspend all servers in a server group.
/server-group=main-server-group:suspend-servers(timeout=60)
Resume
The server can be returned back to a normal running state to accept new requests by using the resume
command at the appropriate level (server, server group, entire domain). For example:
:resume
Start a Server in a Suspended State
You can start a server in a suspended state so that no requests are accepted by the server until it is resumed.
To start a standalone server in a suspended state, use the
--start-mode=suspend
runtime argument when starting the JBoss EAP instance.$ EAP_HOME/bin/standalone.sh --start-mode=suspend
To start a managed domain server in a suspended state, pass the
start-mode=suspend
argument to thestart
operation in the management CLI command./host=HOST_NAME/server-config=SERVER_NAME:start(start-mode=suspend)
NoteYou can also pass the
start-mode
argument to thereload
andrestart
operations for a server.To start all servers in a managed domain server group in a suspended state, pass the
start-mode=suspend
argument to thestart-servers
operation in the management CLI command./server-group=SERVER_GROUP_NAME:start-servers(start-mode=suspend)
NoteYou can also pass the
start-mode
argument to thereload-servers
andrestart-servers
operations for a server group.
2.4.2. Shut Down Servers Gracefully
A server will be shut down gracefully if an appropriate timeout value is specified when stopping the server. Once the command is issued, the server will be suspended and will wait up to the specified timeout for all requests to finish before shutting down.
Use the following management CLI commands to shut down the server gracefully. Specify the timeout value, in seconds, for the server to wait for active requests to complete. The default is 0
, which will shut down the server immediately. A value of -1
will cause the server to wait indefinitely for all active requests to complete before shutting down.
Each example waits up to 60 seconds for requests to complete before shutting down.
Shut down a standalone server gracefully.
:shutdown(timeout=60)
Stop all servers in a managed domain gracefully.
:stop-servers(timeout=60)
Stop a single server in a managed domain gracefully.
/host=master/server-config=server-one:stop(timeout=60)
Stop all servers in a server group gracefully.
/server-group=main-server-group:stop-servers(timeout=60)
2.5. Starting and Stopping JBoss EAP (RPM Installation)
Starting and stopping JBoss EAP is different for an RPM installation compared to a ZIP or installer installation.
2.5.1. Starting JBoss EAP (RPM Installation)
The command for starting an RPM installation of JBoss EAP depends on which operating mode you want to start, a standalone server or a managed domain, and which Red Hat Enterprise Linux version you are running.
Start JBoss EAP as a Standalone Server (RPM Installation)
For Red Hat Enterprise Linux 6:
$ service eap7-standalone start
For Red Hat Enterprise Linux 7:
$ systemctl start eap7-standalone.service
This will start JBoss EAP using the standalone.xml
configuration file by default. You can start JBoss EAP with a different standalone server configuration file by setting a property in the RPM service configuration file. For more information, see the Configure RPM Service Properties section below.
Start JBoss EAP in a Managed Domain (RPM Installation)
For Red Hat Enterprise Linux 6:
$ service eap7-domain start
For Red Hat Enterprise Linux 7:
$ systemctl start eap7-domain.service
This will start JBoss EAP using the host.xml
configuration file by default. You can start JBoss EAP with a different managed domain configuration file by setting a property in the RPM service configuration file. For more information, see the Configure RPM Service Properties section below.
Configure RPM Service Properties
This section shows you how to configure the RPM service properties and other startup options for your JBoss EAP installation. Note that it is recommended to back up your configuration files before making modifications.
For a listing of all available startup options for an RPM installation, see the RPM Service Configuration Properties section.
For Red Hat Enterprise Linux 7, RPM service configuration files are loaded using systemd
, so variable expressions are not expanded.
Specify the server configuration file.
When starting a standalone server, the
standalone.xml
file is used by default. When running in a managed domain, thehost.xml
file is used by default. You can start JBoss EAP with a different configuration file by setting theWILDFLY_SERVER_CONFIG
property in the appropriate RPM configuration file, for example,eap7-standalone.conf
.WILDFLY_SERVER_CONFIG=standalone-full.xml
Bind to a specific IP address.
By default, a JBoss EAP RPM installation binds to
0.0.0.0
. You can bind JBoss EAP to a specific IP address by setting theWILDFLY_BIND
property in the appropriate RPM configuration file, for example,eap7-standalone.conf
.WILDFLY_BIND=192.168.0.1
NoteIf you want to bind the management interfaces to a specific IP address, this can be configured in the JBoss EAP startup configuration file as shown in the next example.
Set JVM options or Java properties.
You can specify JVM options or Java properties to pass into the JBoss EAP startup script by editing the startup configuration file. This file is
EAP_HOME/bin/standalone.conf
for a standalone server orEAP_HOME/bin/domain.conf
for a managed domain. The below example configures the heap size and binds the JBoss EAP management interfaces to an IP address.JAVA_OPTS="$JAVA_OPTS -Xms2048m -Xmx2048m" JAVA_OPTS="$JAVA_OPTS -Djboss.bind.address.management=192.168.0.1"
NoteIf required, the JBoss EAP bind address must be configured using the
WILDFLY_BIND
property and not using thejboss.bind.address
standard property here.
If a property has the same name in both the RPM service configuration file, such as /etc/sysconfig/eap7-standalone
, and in the JBoss EAP startup configuration file, such as EAP_HOME/bin/standalone.conf
, the value that takes precedence is the one in the JBoss EAP startup configuration file. One such property is JAVA_HOME
.
2.5.2. Stopping JBoss EAP (RPM Installation)
The command for stopping an RPM installation of JBoss EAP depends on which operating mode that was started, a standalone server or a managed domain, and which Red Hat Enterprise Linux version you are running.
Stop JBoss EAP as a Standalone Server (RPM Installation)
For Red Hat Enterprise Linux 6:
$ service eap7-standalone stop
For Red Hat Enterprise Linux 7:
$ systemctl stop eap7-standalone.service
Stop JBoss EAP in a Managed Domain (RPM Installation)
For Red Hat Enterprise Linux 6:
$ service eap7-domain stop
For Red Hat Enterprise Linux 7:
$ systemctl stop eap7-domain.service
For a listing of all available startup options for an RPM installation, see the RPM Service Configuration Files section.
2.6. PowerShell Scripts (Windows Server)
The collection of PowerShell scripts is provided as Technology Preview only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.
See Technology Preview Features Support Scope on the Red Hat Customer Portal for information about the support scope for Technology Preview features.
JBoss EAP includes PowerShell script equivalents for most of the JBoss EAP management scripts. This includes a PowerShell script to start JBoss EAP on Microsoft Windows Server.
The JBoss EAP PowerShell scripts are designed to work with PowerShell version 2 and newer running on tested versions of Windows Server.
The JBoss EAP PowerShell scripts are located in EAP_HOME\bin
, and are used in mostly the same way as the JBoss EAP batch scripts.
For example, to start a standalone JBoss EAP server with the standalone-full.xml
configuration file, use the following PowerShell command:
.\standalone.ps1 "-c=standalone-full.xml"
Arguments of the JBoss EAP PowerShell scripts must be in quotes.