Chapter 2. Application Server Management

2.1. Start and Stop JBoss EAP 6

2.1.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 print a list of additional parameters to pass to the start-up scripts, use the -h parameter.
Result

The JBoss EAP 6 Standalone Server instance starts.

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

    For a list of parameters you can pass to the start-up script, use the -h parameter.
Result

The JBoss EAP 6 Managed Domain instance starts.

2.1.4. 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.6.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.3. 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.4. 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.1.5. 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, refer 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.5. 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.
      [$JBOSS_HOME/bin]$ ./domain.sh --host-config=host-master.xml -bmanagement=$IP1
  2. On Machine 2

    1. Update $JBOSS_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.
      [$JBOSS_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:
    [$JBOSS_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.1.6. Start JBoss EAP 6 with an Alternative Configuration

If you do not specify a configuration file, the server starts with the default file. However, when you start the server, you can specify a configuration manually. The process varies slightly, depending on whether you are using a Managed Domain or Standalone Server, and depending on which operating system you are using.

Prerequisites

  • Before using an alternate configuration file, prepare it using the default configuration as a template. For a Managed Domain, the configuration file needs to be placed in the EAP_HOME/domain/configuration/ directory. For a Standalone Server, the configuration file should be placed in the EAP_HOME/standalone/configuration/ directory.

Note

Several example configurations are included in the EAP_HOME/docs/examples/configs/ directory. Use these examples to enable extra features such as clustering or the Transactions XTS API.
Some of the example configurations must be modified before being used. The following configuration files produce errors if they are used without being modified: standalone-picketlink.xml, standalone-genericjms.xml and standalone-hornetq-colocated.xml.

Procedure 2.6. Start the Instance with an Alternative Configuration

  1. Standalone server

    For a Standalone Server, provide the filename of the configuration file as an option to the --server-config parameter. The configuration file must be located in the EAP_HOME/standalone/configuration/ directory, and you need to specify the file path relative to that 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.
  2. Managed Domain

    For a Managed Domain, provide the file name of the configuration file as an option to the --domain-config parameter. The file must be present 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.
Result

JBoss Enterprise Application Platform is now running, using your alternate configuration file.

2.1.7. 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.2.3, “Stop a Server Using the Management Console”. For information on how to stop a server using the Management CLI, see Section 2.2.1, “Start and Stop Servers Using the Management CLI”.
  • Procedure 2.7. 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.8. Stop an instance which was started as an operating system service.

    Depending on your 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 your 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.9. 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.1.8. Reference of Switches and Arguments to pass at Server Runtime

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

Example 2.5. 

The following example is similar to the server startup explained in Section 2.1.2, “Start JBoss EAP 6 as a Standalone Server” and Section 2.1.3, “Start JBoss EAP 6 as a Managed Domain”, with the addition of the -h or --help switches. The results of the help switch are explained in the table below.
Standalone mode:
[localhost bin]$ standalone.sh -h
Domain mode:
[localhost bin]$ domain.sh -h

Table 2.1. Table of 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 to the given value.
-b<interface>=<value> Standalone, Domain Set system property jboss.bind.address.<interface> to the given value.
--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 to the given value.
-v, -V, --version Standalone, Domain Display the application server version and exit.