Chapter 2. Starting and Stopping JBoss EAP


2.1. Starting and stopping JBoss EAP

The method for starting JBoss EAP depends on whether you are running JBoss EAP as a standalone server or on servers in a managed domain.

The method for stopping JBoss EAP depends on whether you are running an interactive or background instance of JBoss EAP.

2.1.1. Starting JBoss EAP as a standalone server

You can run JBoss EAP as a standalone server to manage a single instance of JBoss EAP.

The server starts in a suspended state and does not accept requests until all required services start. After required services start, the server transitions into a normal running state and can start accepting requests.

This startup script uses the EAP_HOME/bin/standalone.conf file, or standalone.conf.bat for Windows Server, to set default preferences, such as JVM options. You can customize the settings in this file.

Note

To see a list of startup script arguments in your terminal, use the --help argument.

JBoss EAP uses the standalone.xml configuration file by default, but you can start it using a different one.

Prerequisites

  • Install JBoss EAP.

Procedure

  1. Open a terminal.
  2. Start JBoss EAP as a standalone server by using the following script:

    $ EAP_HOME/bin/standalone.sh
    1. For Windows Server, use the EAP_HOME\bin\standalone.bat script.

2.1.2. Starting JBoss EAP for servers in a managed domain

You can run JBoss EAP in a managed domain operating mode to manage several JBoss EAP instances using a single domain controller.

Servers start in a suspended state and do not accept requests until all required services start. After required services start, the servers transition into a normal running state and start accepting requests.

You must start the domain controller before the servers in any of the server groups in the domain.

Prerequisites

  • Install JBoss EAP.

Procedure

  1. Open a terminal.
  2. Start the domain controller first and then start each associated host controller by using the following script:

    $ 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 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 you can start it using a different configuration file.

When setting up a managed domain, you must pass additional arguments into the startup script.

Note

For a complete listing of all available startup script arguments and their purposes, use the --help argument.

2.1.3. Stopping an interactive instance of JBoss EAP

You can stop an interactive instance of a standalone server or a domain controller from the terminal where you started it.

Prerequisites

  • Have a running instance of JBoss EAP.

Procedure

  • Press Ctrl+C in the terminal where you started JBoss EAP.

2.1.4. Stopping a background instance of JBoss EAP

You can connect to the management CLI to shut down a running instance of a standalone server or servers in a managed domain.

Prerequisites

  • Have a running instance of JBoss EAP running in a terminal.

Procedure

  1. Start the management CLI by using the following script:

    $ EAP_HOME/bin/jboss-cli.sh --connect
  2. Issue the shutdown command:

    shutdown

When running an instance of JBoss EAP on servers in a managed domain, you must specify the host name to shut down by using the --host argument with the shutdown command.

2.2. Running JBoss EAP in admin-only mode

JBoss EAP can start in admin-only mode. This mode enables JBoss EAP to run and accept management requests without starting other runtime services or handling end user requests. Admin-only mode is available in both standalone servers as well as managed domains.

2.2.1. Running a standalone server in admin-only mode

You can run a JBoss EAP instance in admin-only mode using a standalone server.

Prerequisites

  • JBoss EAP is installed.

Procedure

  1. Open your terminal.
  2. 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
    1. 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"
      }
      Note

      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)
    2. 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.

      1. To reload the server in admin-only mode:

        reload --start-mode=admin-only
      2. To reload the server in normal mode:

        reload --start-mode=normal
        Note

        If the server was started in admin-only mode and no --start-mode argument is specified in the reload command, the server will be started in normal mode.

2.2.2. 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 secondary host controllers. A host controller started in admin-only mode will not start servers.

Prerequisites

  • JBoss EAP is installed.

Procedure

  1. Open your terminal.
  2. Pass in the --admin-only runtime argument to start a host controller in admin-only mode.

    $ EAP_HOME/bin/domain.sh --admin-only
    1. 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"
      }
    2. 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.

      1. To reload the host controller in admin-only mode:

        reload --host=HOST_NAME --admin-only=true
      2. To reload a host controller in normal mode:

        reload --host=HOST_NAME --admin-only=false
        Note

        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.3. 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 the suspend or shut down operation will wait for active requests to complete. While the server is suspended, management requests are still processed.

Suspend and graceful shutdown is coordinated server-wide, focusing on the entry points where requests enter the server. The following subsystems support suspend and 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 the PRE_SUSPEND phase.
Jakarta Enterprise Beans
The ejb3 subsystem will wait for all remote session bean requests and MDB message deliveries to finish. Delivery to MDBs is stopped during the PRE_SUSPEND phase. Jakarta Enterprise Bean 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 can continue until they complete or the timeout period expires. For example, the server will accept incoming remote calls that are related to an active transaction at the suspending server.

This also applies to web service requests associated with an XTS transaction.

If you initiate a transaction before graceful shutdown and it fails (for example, a necessary database is unavailable), the transaction will not be recovered automatically as the Recovery Manager may not be functional due to the graceful shutdown proceedings. You will need to resume your JBoss EAP instance to utilize the Recovery Manager and complete the failed transaction.

By default, transaction graceful shutdown is disabled for the ejb3 subsystem. You must enable transaction graceful shutdown if you want the server to wait for Jakarta Enterprise Beans-related transactions to complete before suspending. For example:

/subsystem=ejb3:write-attribute(name=enable-graceful-txn-shutdown,value=true)

This behavior is disabled by default because it can cause Jakarta Enterprise Beans clients to invoke cluster nodes during graceful shutdown. In cluster environments, the server notifies remote clients after transactions are completed that the node is no longer available for remote calls. If the client sends a new request during this window of time (before transactions are complete) to a node that is shutting down, the node will refuse the request.

Jakarta Concurrency

The server will wait for all active jobs to finish. All queued jobs will be skipped. Since Jakarta Concurrency does not have persistence, any queued jobs that are 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 resumes, 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.
Note

Graceful shutdown will not currently reject new inbound Jakarta Messaging messages. Jakarta Batch jobs and Jakarta Concurrency tasks scheduled by in-flight activity are currently allowed to proceed; however, Jakarta 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. If you do not need this capability, you can remove the request-controller subsystem for a slight performance improvement.

2.3.1. Suspend servers

JBoss EAP 8.0 provides a suspend mode that gracefully suspends server operations. 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.

Note

The management interfaces are not affected 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=primary/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(suspend-timeout=60)
  • Suspend all servers in a managed domain.

    :suspend-servers(suspend-timeout=60)
  • Suspend a single server in a managed domain.

    /host=primary/server-config=server-one:suspend(suspend-timeout=60)
  • Suspend all servers in a server group.

    /server-group=main-server-group:suspend-servers(suspend-timeout=60)
  • Suspend all servers managed by a particular Host Controller.

    /host=primary:suspend-servers(suspend-timeout=60)

Resume

The resume command returns the server to a normal running state to accept new requests. You can initiate the command at the host, server, server group, or domain level. 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 the start operation in the management CLI command.

    /host=HOST_NAME/server-config=SERVER_NAME:start(start-mode=suspend)
    Note

    You can also pass the start-mode argument to the reload and restart 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 the start-servers operation in the management CLI command.

    /server-group=SERVER_GROUP_NAME:start-servers(start-mode=suspend)
    Note

    You can also pass the start-mode argument to the reload-servers and restart-servers operations for a server group.

2.3.2. Shut down servers gracefully using the management CLI

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 shuts 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 --suspend-timeout=60
  • Stop all servers in a managed domain gracefully.

    :stop-servers(suspend-timeout=60)
  • Stop a single server in a managed domain gracefully.

    /host=primary/server-config=server-one:stop(suspend-timeout=60)
  • Stop all servers in a server group gracefully.

    /server-group=main-server-group:stop-servers(suspend-timeout=60)
  • Shut down the host controller and all the servers it manages.

    /host=primary:shutdown(suspend-timeout=60)

The suspend-timeout attribute is only applied to the servers managed by the host controller, not the host controller itself.

Shut down servers gracefully using an OS signal

A server can be shut down gracefully by setting org.wildfly.sigterm.suspend.timeout system property and then sending an OS TERM signal, such as kill -15 PID. By default, this behavior is identical to the management CLI’s shutdown --suspend-timeout=0 command, resulting in immediate termination of any currently processing requests. The timeout can be configured by the org.wildfly.sigterm.suspend.timeout system property, indicating the maximum number of seconds to wait for requests to complete before the server shuts down. A value of -1 indicates that the server will wait indefinitely.

Important

In a managed domain, OS signals should not be used to shut down servers. Instead, servers should be shut down using the management CLIor the management console, through the managing Host Controller.

Graceful shutdown using an OS signal will not work if the JVM is configured to disable signal handling, such as when the -Xrs java argument is passed to the JVM options, or if the signal sent is not one the process can respond to, such as if a KILL signal is sent.

2.4. 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.4.1. Starting an RPM installation of JBoss EAP

You can use a command to start an RPM installation of JBoss EAP in either standalone server or managed domain operating modes. Note that the following commands are only compatible with Red Hat Enterprise Linux (RHEL) 8 and later versions.

Start JBoss EAP as a standalone server (RPM installation)

$ systemctl start eap8-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)

$ systemctl start eap8-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.

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

Important

For Red Hat Enterprise Linux 7 and later, 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, the host.xml file is used by default. You can start JBoss EAP with a different configuration file by setting the WILDFLY_SERVER_CONFIG property in the appropriate RPM configuration file, for example, eap8-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 the WILDFLY_BIND property in the appropriate RPM configuration file, for example, eap8-standalone.conf.

    WILDFLY_BIND=192.168.0.1
    Note

    If 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 or EAP_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"
    Note

    If required, the JBoss EAP bind address must be configured using the WILDFLY_BIND property and not using the jboss.bind.address standard property here.

Note

If a property has the same name in both the RPM service configuration file, such as /usr/lib/systemd/system/eap8-standalone.service:, 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.4.3. Stopping an RPM installation of JBoss EAP

You can use a command to stop an RPM installation of JBoss EAP in either standalone server or managed domain operating modes. Note that the following commands are only compatible with Red Hat Enterprise Linux (RHEL) 8 and later versions.

Stop JBoss EAP as a standalone server (RPM installation)

$ systemctl stop eap8-standalone.service

Stop JBoss EAP in a managed domain (RPM installation)

$ systemctl stop eap8-domain.service

For a list of all available startup options for an RPM installation, see the RPM Service Configuration Files section.

2.5. PowerShell scripts for Windows Server

Important

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 using 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"
Note

Arguments of the JBoss EAP PowerShell scripts must be in quotes.

Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.