Red Hat Training

A Red Hat training course is available for Red Hat JBoss Enterprise Application Platform

2.2. Start and Stop JBoss EAP 6

2.2.1. Start JBoss EAP 6

JBoss EAP runs in one of two modes, Standalone Server or Managed Domain, and is supported on two platforms, Red Hat Enterprise Linux and Microsoft Windows Server. The specific command to start JBoss EAP depends on the underlying platform and the desired mode.

Table 2.1. Commands to start JBoss EAP

Operating System Standalone Server Managed Domain
Red Hat Enterprise Linux EAP_HOME/bin/standalone.sh EAP_HOME/bin/domain.sh
Microsoft Windows Server EAP_HOME\bin\standalone.bat EAP_HOME\bin\domain.bat

2.2.2. Start JBoss EAP 6 as a Standalone Server

Summary

This topic covers the steps to start JBoss EAP 6 as a Standalone Server.

Procedure 2.1. Start the Platform Service as a Standalone Server

  1. For Red Hat Enterprise Linux.

    Run the command: EAP_HOME/bin/standalone.sh
  2. For Microsoft Windows Server.

    Run the command: EAP_HOME\bin\standalone.bat
  3. Optional: Specify additional parameters.

    To list all available parameters for the start-up scripts, use the -h parameter.
Result

The JBoss EAP 6 Standalone Server instance starts.

2.2.3. Running Multiple JBoss EAP Standalone Servers on a Single Machine

Summary

This topic describes the steps for running multiple JBoss EAP Standalone servers on a single machine.

Procedure 2.2. Run multiple instances of JBoss EAP standalone servers on a single machine

  1. Create a copy of the EAP_HOME/standalone/ directory directly under EAP_HOME/ for each standalone server. For example, to create a directory for standalone servers node1 and node2, type the following commands.
    $ cd EAP_HOME
    $ cp -a ./standalone ./node1 
    $ cp -a ./standalone ./node2
  2. Start each JBoss EAP standalone instance by specifying the node name, IP address, server directory, optional server configuration file, and optional port offset. The command uses the following syntax:
    $ ./bin/standalone.sh -Djboss.node.name=UNIQUE_NODENAME -Djboss.server.base.dir=EAP_HOME/NODE_DIRECTORY -b IP_ADDRESS -bmanagement MGMT_IP_ADDRESS --server-config=SERVER_CONFIGURATION_FILE -Djboss.socket.binding.port-offset=PORT_OFFSET
    1. This example starts node1
      $ cd EAP_HOME
      $ ./bin/standalone.sh -Djboss.node.name=node1 -Djboss.server.base.dir=EAP_HOME/node1 -b 10.10.10.10 -bmanagement 127.0.0.1
      
    2. This example to start node2 depends on whether the machine supports multiple IP addresses.
      • If the machine supports multiple IP addresses, the following command is to be used.
        $ cd EAP_HOME
        $ ./bin/standalone.sh -Djboss.node.name=node2 -Djboss.server.base.dir=EAP_HOME/node2 -b 10.10.10.40 -bmanagement 127.0.0.40
        
      • If the machine does not support multiple IP addresses, you must specify a jboss.socket.binding.port-offset property to avoid a port conflict.
        $ cd EAP_HOME
        $ ./bin/standalone.sh -Djboss.node.name=node2 -Djboss.server.base.dir=EAP_HOME/node2 -b 10.10.10.10 -bmanagement 127.0.0.1 -Djboss.socket.binding.port-offset=100
        

Note

If you would like to manage two nodes at once or two nodes that have the same configuration, you are recommended to run them in a managed domain instead of running a standalone server.

2.2.4. Start JBoss EAP 6 as a Managed Domain

Order of Operations

The domain controller must be started before any slave servers in any server groups in the domain. Use this procedure first on the domain controller, and then on each associated host controller and each other host associated with the domain.

Procedure 2.3. Start the Platform Service as a Managed Domain

  1. For Red Hat Enterprise Linux.

    Run the command: EAP_HOME/bin/domain.sh
  2. For Microsoft Windows Server.

    Run the command: EAP_HOME\bin\domain.bat
  3. Optional: Pass additional parameters to the start-up script.

    To list all available parameters for the start-up scripts, use the -h parameter.
Result

The JBoss EAP 6 Managed Domain instance starts.

2.2.5. Configure the Name of a Host in a Managed Domain

Summary

Every host running in a managed domain must have a unique host name. To ease administration and allow for the use of the same host configuration files on multiple hosts, the server uses the following precedence for determining the host name.

  1. If set, the host element name attribute in the host.xml configuration file.
  2. The value of the jboss.host.name system property.
  3. The value that follows the final period (".") character in the jboss.qualified.host.name system property, or the entire value if there is no final period (".") character.
  4. The value that follows the period (".") character in the HOSTNAME environment variable for POSIX-based operating systems, the COMPUTERNAME environment variable for Microsoft Windows, or the entire value if there is no final period (".") character.

For information about how to set environment variables, see the documentation for your operating system. For information about how to set system properties, see Section 3.5.11, “Configure System Properties Using the Management CLI”.
This topic describes how set the name of the host in the configuration file, using either a system property or a hard-coded name.

Procedure 2.4. Configure the Host Name Using a System Property

  1. Open the host configuration file for editing, for example, host.xml.
  2. Find the host element in the file, for example:
    <host name="master" xmlns="urn:jboss:domain:1.6">
  3. If it is present, remove the name="HOST_NAME" attribute declaration. The host element should now look like the following example.
    <host xmlns="urn:jboss:domain:1.6">
  4. Start the server passing the -Djboss.host.name argument, for example:
    -Djboss.host.name=HOST_NAME

Procedure 2.5. Configure the Host Name Using a Specific Name

  1. Start the JBoss EAP slave host using the following syntax:
    bin/domain.sh --host-config=HOST_FILE_NAME
    For example:
    bin/domain.sh --host-config=host-slave01.xml
  2. Launch the Management CLI.
  3. Use the following syntax to replace the host name:
    /host=EXISTING_HOST_NAME:write-attribute(name="name",value=UNIQUE_HOST_NAME)
    For example:
    /host=master:write-attribute(name="name",value="host-slave01")
    You should see the following result.
     "outcome" => "success"
    This modifies the host name attribute in the host-slave01.xml file as follows:
    <host name="host-slave01" xmlns="urn:jboss:domain:1.6">
  4. You must reload the server configuration using the old host name to complete the process
    reload --host=EXISTING_HOST_NAME
    For example:
    reload --host=master

2.2.6. Create Managed Domain on Two Machines

Note

You may need to configure your firewall to run this example.
You can create managed domain on two machines, wherein one machine is a domain controller and the other machine is a host. For more information, see Section 1.6, “About the Domain Controller”.
  • IP1 = IP address of the domain controller (Machine 1)
  • IP2 = IP address of the host (Machine 2)

Procedure 2.6. Create managed domain on two machines

  1. On Machine 1

    1. Use the add-user.sh script to add management user. For example, slave01, so the host can authenticate the domain controller. Note the SECRET_VALUE from the add-user output.
    2. Start domain with host-master.xml config file, which is preconfigured for dedicated domain controller.
    3. Use -bmanagement=$IP1 to make domain controller visible to other machines.
      EAP_HOME/bin/domain.sh --host-config=host-master.xml -bmanagement=$IP1
  2. On Machine 2

    1. Update EAP_HOME/domain/configuration/host-slave.xml file with user credentials.
      	<?xml version='1.0' encoding='UTF-8'?>
              <host xmlns="urn:jboss:domain:1.6" name="slave01">   
              <!-- add user name here -->
               <management>
                  <security-realms>
                     <security-realm name="ManagementRealm">
                        <server-identities>
                          <secret value="$SECRET_VALUE" />   
                          <!-- use secret value from add-user.sh output-->
                        </server-identities> 
                        ...
    2. Start host.
      EAP_HOME/bin/domain.sh --host-config=host-slave.xml  -Djboss.domain.master.address=$IP1 -b=$IP2
  3. Now we can manage the domain.

    via CLI:
    EAP_HOME/bin/jboss-cli.sh -c --controller=$IP1
    
    via Web Console:
    http://$IP1:9990
    
    Access the server index page:
    http://$IP2:8080/
    http://$IP2:8230/
    

2.2.7. Create Managed Domain on a Single Machine

Multiple host controllers can be run on a single machine by using the jboss.domain.base.dir property.

Important

It is not supported to configure more than one JBoss EAP host controller as a system service on a single machine.

Procedure 2.7. Run Multiple Host Controllers on a Single Machine

  1. Copy the EAP_HOME/domain directory for the domain controller.
    cp -r EAP_HOME/domain /path/to/domain1
  2. Copy the EAP_HOME/domain directory for a host controller.
    cp -r EAP_HOME/domain /path/to/host1
  3. Start the domain controller using /path/to/domain1.
    EAP_HOME/bin/domain.sh --host-config=host-master.xml -Djboss.domain.base.dir=/path/to/domain1
  4. Start the host controller using /path/to/host1.
    EAP_HOME/bin/domain.sh --host-config=host-slave.xml -Djboss.domain.base.dir=/path/to/host1 -Djboss.domain.master.address=IP_ADDRESS -Djboss.management.native.port=PORT
Result

Each instance started in this manner will share the rest of the resources in the base installation directory (i.e. EAP_HOME/modules/), but use the domain configuration from the directory specified by jboss.domain.base.dir.

2.2.8. Start JBoss EAP 6 with an Alternative Configuration

If you do not specify a configuration file, the server starts with the default file.
You can also specify a configuration manually. This process varies depending on whether you are using a Managed Domain or Standalone Server, and operating system.

Prerequisites

  • Before using an alternative configuration file, prepare it using the default configuration as a template.
  • For Managed Domains, alternative configuration files are stored in the EAP_HOME/domain/configuration/ directory.
  • For Standalone Servers, alternative configuration files are stored in the EAP_HOME/standalone/configuration/ directory.

Note

Example configurations are included in the EAP_HOME/docs/examples/configs/ directory. Use these examples to enable features such as clustering or the Transactions XTS API.
Start the Instance with an Alternative Configuration

Standalone server

For a Standalone Server, provide the configuration filename using the --server-config switch. The configuration file must be in the EAP_HOME/standalone/configuration/ directory, and you must specify the file path relative to this directory.

Example 2.1. Using an Alternate Configuration file for a Standalone Server in Red Hat Enterprise Linux

[user@host bin]$ ./standalone.sh --server-config=standalone-alternate.xml
This example uses the EAP_HOME/standalone/configuration/standalone-alternate.xml configuration file.

Example 2.2. Using an Alternate Configuration file for a Standalone Server in Microsoft Windows Server

C:\EAP_HOME\bin> standalone.bat --server-config=standalone-alternate.xml
This example uses the EAP_HOME\standalone\configuration\standalone-alternative.xml configuration file.
Managed Domain

For a Managed Domain, provide the configuration filename using the --domain-config switch. The configuration file must be in the EAP_HOME/domain/configuration/ directory, and you need to specify the path relative to that directory.

Example 2.3. Using an Alternate Configuration file for a Managed Domain in Red Hat Enterprise Linux

[user@host bin]$ ./domain.sh --domain-config=domain-alternate.xml
This example uses the EAP_HOME/domain/configuration/domain-alternate.xml configuration file.

Example 2.4. Using an Alternate Configuration file for a Managed Domain in Microsoft Windows Server

C:\EAP_HOME\bin> domain.bat --domain-config=domain-alternate.xml

This example uses the EAP_HOME\domain\configuration\domain-alternate.xml configuration file.

2.2.9. Stop JBoss EAP 6

The way that you stop JBoss EAP 6 depends on how it was started. This task covers stopping an instance that was started interactively, stopping an instance that was started by a service, and stopping an instance that was forked into the background by a script.

Note

For information on how to stop a server or server group in a Managed Domain see Section 2.3.3, “Stop a Server Using the Management Console”. For information on how to stop a server using the Management CLI, see Section 2.3.1, “Start and Stop Servers Using the Management CLI”.

Procedure 2.8. Stop an instance of JBoss EAP 6

  • Stop an instance which was started interactively from a command prompt.

    Press Ctrl-C in the terminal where JBoss EAP 6 is running.

Procedure 2.9. Stop an instance which was started as an operating system service.

Depending on the operating system, use one of the following procedures.
    • Red Hat Enterprise Linux

      For Red Hat Enterprise Linux, if you have written a service script, use its stop facility. This needs to be written into the script. Then you can use service scriptname stop, where scriptname is the name of the script.
    • Microsoft Windows Server

      In Microsoft Windows, use the net service command, or stop the service from the Services applet in the Control Panel.

Procedure 2.10. Stop an instance which is running in the background (Red Hat Enterprise Linux)

  1. Obtain the process ID (PID) of the process:
    • If only a single instance is running (standalone mode)

      Either of the following commands will return the PID of a single instance of JBoss EAP 6:
      • pidof java
      • jps
        (The jps command will return an ID for two processes; one for jboss-modules.jar and one for jps itself. Use the ID for jboss-modules.jar to stop the EAP instance)
    • If multiple EAP instances are running (domain mode)

      Identifying the correct process to end if more than one instance of EAP is running requires more comprehensive commands be used.
      • The jps command can be used in verbose mode to provide more information about the java processes it finds.
        Below is an abridged output from a verbose jps command identifying the different EAP processes running by PID and role:
        $ jps -v
        12155 jboss-modules.jar -D[Server:server-one] -XX:PermSize=256m -XX:MaxPermSize=256m -Xms1303m 
        ...
        
        12196 jboss-modules.jar -D[Server:server-two] -XX:PermSize=256m -XX:MaxPermSize=256m -Xms1303m 
        ...
        
        12096 jboss-modules.jar -D[Host Controller] -Xms64m -Xmx512m -XX:MaxPermSize=256m 
        ...
        
        11872 Main -Xms128m -Xmx750m -XX:MaxPermSize=350m -XX:ReservedCodeCacheSize=96m -XX:+UseCodeCacheFlushing 
        ...
        
        11248 jboss-modules.jar -D[Standalone] -XX:+UseCompressedOops -verbose:gc 
        ...
        
        12892 Jps 
        ...
        
        12080 jboss-modules.jar -D[Process Controller] -Xms64m -Xmx512m -XX:MaxPermSize=256m 
        ...
        
      • The ps aux command can also be used to return information about multiple EAP instances.
        Below is an abridged output from a verbose ps aux command identifying the different EAP processes running by PID and role:
        $ ps aux | grep java
        username 12080  0.1  0.9 3606588 36772 pts/0   Sl+  10:09   0:01 /path/to/java -D[Process Controller] -server -Xms128m -Xmx128m -XX:MaxPermSize=256m 
        ...
        
        username 12096  1.0  4.1 3741304 158452 pts/0  Sl+  10:09   0:13 /path/to/java -D[Host Controller] -Xms128m -Xmx128m -XX:MaxPermSize=256m 
        ...
        
        username 12155  1.7  8.9 4741800 344224 pts/0  Sl+  10:09   0:22 /path/to/java -D[Server:server-one] -XX:PermSize=256m -XX:MaxPermSize=256m -Xms1000m -Xmx1000m -server -
        ...
        
        username 12196  1.8  9.4 4739612 364436 pts/0  Sl+  10:09   0:22 /path/to/java -D[Server:server-two] -XX:PermSize=256m -XX:MaxPermSize=256m -Xms1000m -Xmx1000m -server 
        ...
        
      In the above examples, the Process Controller processes are the processes to stop in order to stop the entire domain.
      The grep utility can be used with either of these commands to identify the Process Controller:
      jps -v | grep "Process Controller"
      ps aux | grep "Process Controller"
  2. Send the process the TERM signal, by running kill PID, where PID is the process ID identified by one of the commands above.
Result

Each of these alternatives shuts JBoss EAP 6 down cleanly so that data is not lost.

2.2.10. Reference of Switches and Arguments to pass at Server Runtime

The application server startup script accepts arguments and switches at runtime. This allows the server to start under alternative configurations to those defined in the standalone.xml, domain.xml, and host.xml configuration files.
Alternative configurations might include starting the server with an alternative socket bindings set or a secondary configuration.
The available parameters list can be accessed by passing the help switch -h or --help at startup.

Table 2.2. Runtime Switches and Arguments

Argument or Switch Mode Description
--admin-only Standalone Set the server's running type to ADMIN_ONLY. This will cause it to open administrative interfaces and accept management requests, but not start other runtime services or accept end user requests.
--admin-only Domain Set the host controller'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.
-b=<value>, -b <value> Standalone, Domain Set system property jboss.bind.address, which is used in configuring the bind address for the public interface. This defaults to 127.0.0.1 if no value is specified. See the -b<interface>=<value> entry for setting the bind address for other interfaces.
-b<interface>=<value> Standalone, Domain Set system property jboss.bind.address.<interface> to the given value. For example, -bmanagement=IP_ADDRESS
--backup Domain Keep a copy of the persistent domain configuration even if this host is not the Domain Controller.
-c=<config>, -c <config> Standalone Name of the server configuration file to use. The default is standalone.xml.
-c=<config>, -c <config> Domain Name of the server configuration file to use. The default is domain.xml.
--cached-dc Domain If the host is not the Domain Controller and cannot contact the Domain Controller at boot, boot using a locally cached copy of the domain configuration.
--debug [<port>] Standalone Activate debug mode with an optional argument to specify the port. Only works if the launch script supports it.
-D<name>[=<value>] Standalone, Domain Set a system property.
--domain-config=<config> Domain Name of the server configuration file to use. The default is domain.xml.
-h, --help Standalone, Domain Display the help message and exit.
--host-config=<config> Domain Name of the host configuration file to use. The default is host.xml.
--interprocess-hc-address=<address> Domain Address on which the host controller should listen for communication from the process controller.
--interprocess-hc-port=<port> Domain Port on which the host controller should listen for communication from the process controller.
--master-address=<address> Domain Set system property jboss.domain.master.address to the given value. In a default slave Host Controller config, this is used to configure the address of the master Host Controller.
--master-port=<port> Domain Set system property jboss.domain.master.port to the given value. In a default slave Host Controller config, this is used to configure the port used for native management communication by the master Host Controller.
--read-only-server-config=<config> Standalone Name of the server configuration file to use. This differs from --server-config and -c in that the original file is never overwritten.
--read-only-domain-config=<config> Domain Name of the domain configuration file to use. This differs from --domain-config and -c in that the initial file is never overwritten.
--read-only-host-config=<config> Domain Name of the host configuration file to use. This differs from --host-config in that the initial file is never overwritten.
-P=<url>, -P <url>, --properties=<url> Standalone, Domain Load system properties from the given URL.
--pc-address=<address> Domain Address on which the process controller listens for communication from processes it controls.
--pc-port=<port> Domain Port on which the process controller listens for communication from processes it controls.
-S<name>[=<value>] Standalone Set a security property.
--server-config=<config> Standalone Name of the server configuration file to use. The default is standalone.xml.
-u=<value>, -u <value> Standalone, Domain Set system property jboss.default.multicast.address, which is used in configuring the multicast address in the socket-binding elements in the configuration files. This defaults to 230.0.0.4 if no value is specified.
-v, -V, --version Standalone, Domain Display the application server version and exit.

Warning

The configuration files that ship with JBoss EAP 6 are set up to handle the behavior of the switches (i.e. -b, -u). If you change your configuration files to no longer use the system property controlled by the switch, then adding it to the launch command will have no effect.