Version 6

    The purpose of this document is to walk through in some detail the use cases related to starting and stopping AS 7 servers.  The intent is to clarify what information is needed to complete the process, determine where that information comes from, and outline in some detail the startup process. The goal is to surface any issues and help clarify the appropriate roles of the ServerManager, Server and DomainController.

     

    In the use case discussion, I mention a number of sources of information to the processes that are starting/stopping servers. In a bit more detail, these are:

     

    • Command line arguments. The meaning here is information provided from a source external to the host on which the process in question is running. That could be a human or a script.
    • Environment variables. This is a variant on command line arguments; usage in this document is meant to  identify cases, e.g. cloud use cases, where the value could not come from outside the host on which the process is running (e.g. a human could not  supply the information via typing) it would have to come from a pre-set variable stored on the host. That pre-set variable wouldn't have to be an environment variable; wouldn't even have to be a variable; it could be a hard coded value in a script.
    • domain.xml. The information is read from the domain configuration file.
    • OS. The information comes from the OS. An example of this would be a machine's default address.
    • Dynamic. For example UUIDs generated by the process itself.

     

    Startup Use Cases

     

    1. Start a ServerManager from the command line

      1. OBJECTIVES: launch a process that can

        1. at minimum receive commands from a DomainController to start/stop a  Server

        2. perform whatever other functions are required based on the other use cases in this document – TODO: clarify these

      2. Required Information

        1. For OBJECTIVE 1.1.1:

          1. Alternative 1: from command line provide

            1. address on which to listen for DC commands

            2. port on which to listen for DC commands

            3. information on how to make the communication w/ DC secure

            4. NOTE: this approach requires telling the DC how to contact the ServerManager

          2. Alternative 2: from command line provide

            1. location of domain.xml

              1. Default to standard location relative to the working directory
            2. Identifier of the ServerManager in the domain.xml

              1. ServerManager parses domain.xml for address, port, information on making communication w/ DC secure

            3. credential needed for secure communication

              1. assumption: storing in domain.xml not acceptable

            4. NOTE: this approach ties the ServerManager to the InstalledImage

            5. NOTE: this approach removes requirement to inform DC of how to contact ServerManager; DC can read domain.xml

              1. This requires the relevant info in the ServerManager's domain.xml copy to be correct

      3. Process

        1. For OBJECTIVE 5.1.1

          1. Alternative 1:

            1. Take provided info; open socket

          2. Alternative 2:

            1. take provided info, find, parse domain.xml for address, port, information on making communication w/ DC secure

            2. open socket

               

    2. Start a ServerManager on a cloud host

      1. OBJECTIVES:

        1. same as 1.1.1

        2. perform whatever other functions are required based on the other use cases in this document – TODO: clarify these

      2. Required Information

        1. For OBJECTIVE 2.1.1

          1. Alternative 1: same a 1.2.1.1 except:

            1. any input is via environment variable; not via external input to host

            2. address  should be a keyword/alias a la JGRP-1204

              1. TASK: How does DC know what this resolved to?

          2. Alternative 2: same as 1.2.1.2 except:

            1. any input is via environment variable; not via external input to host

            2. address should be a keyword/alias a la JGRP-1204

              1. TASK: How does DC know what this resolved to?

              2. TASK:  Once DC finds out, how is this represented in domain.xml?

                1. Property with last known runtime value?

                  <server_property name=”address” value=”GLOBAL”>

                     <last_known_value>192.168.100.15</last_known_value>

                  </server_property>

                2. Does it need to be represented in domain.xml? Yes, otherwise if DC restarts, 2.2.1.2.2.1 task needs to be performed again

      3. Process

          1. For OBJECTIVE 2.2.1

            same  as 1.3.1, except added logic to resolve any keyword/alias used for address

             

    3. Start a known-to-DC Server from the command line

      1. OBJECTIVES:

        1. start a process that will run an ordinary Server (i.e. w/o the DomainControllerSubprofile)

        2. sync relevant content in InstalledImage with the domain before Server bootstrap is allowed to proceed

      2. Required Information

        1. location of InstalledImage – command line

          1. Default to standard location relative to the working directory
        2. id of Server (to locate its record in domain.xml) – command line

        3. ServerManager address/port, security info, if the implementation mechanism is to involve the ServerManager

        4. Discovery information for DC

          1. info in domain.xml (which may be out of date!!!)

            1. DC elements???

            2. DC discovery section???

          2. list of address/port info a la JNDI – from command line

          3. multicast discovery info a la HA-JNDI – from command line

        5. Security information for connection with DC

          1. credential – from command line

          2. what else?

        6. Command line overrides?

          1. -b

          2. system properties

          3. these would need to be provided to DC

      3. Process

        1. Either

          1. launch process

          2. or send a command to ServerManager via it's address/port

          3. Possibly try to send command to ServerManager and become ServerManager if unsuccessful?

        2. lock InstalledImage (how?)

          1. if ServerManager is doing this part, it can plant a lock file, fail to start if another process' lock file is there

            1. accept command line param to override, take lock

        3. parse domain.xml for required info

          1. this extra parsing step is an argument for NOT obtaining info from domain.xml

        4. hash domain.xml

        5. discover DomainController

          1. discovery should not be a simple try to connect; it should be a process of asking how to connect, being provided with information. This way a specialized process, a la a JGroups GossipRouter, could provide this information

            1. e.g. all nodes in domain are in cloud w/ unknown-in-advance addresses; only this specialized process runs outside the cloud with a known address

            2. other discovery mechanisms are possible as well, e.g. something like JGroups S3_PING (use S3 bucket to store domain topology info)

        6. Connect to domain controller

        7. Authenticate

        8. provide id to DC

          1. DC checks if id is known; if not we are in the “Start an unknown-to-DC Server from the command line” use case

        9. provide domain.xml hash to DC, along with any command line overrides we're allowing

        10. DC checks for hash mismatch, and if overrides change its domain.xml

          1. if yes mismatch, push domain.xml to newly joining node

          2. Question: push to rest of nodes in domain?

            1. For sure push to other DCs

            2. What if there are 200 nodes in the domain? Delay startup to deal with pushing an update to 200 nodes?
        11. Synchronize rest of InstalledImage

          1. Full or partial?

            1. Full ships stuff perhaps not needed

            2. Partial requires parsing, analyzing domain.xml to understand what's relevant

            3. Limit to user dirs? (e.g. deploy/)

          2. Synchronization is a la current farming

            1. Compute metadata about all files in InstalledImage

              1. This information could possibly be stored in the domain.xml itself
            2. send metadata to DC

            3. compare with master content

            4. execute actions to bring in sync

            5. sync is one-way – does not involve sending content to the domain (see “Start an unknown-to-DC Server in unknown-to-DC ServerGroup from the command line” for a use case that sends content)

        12. Unlock InstalledImage

        13. Parse domain.xml to find information needed to launch Server process (e.g. JVM args)

        14. Spawn Server JVM

          1. Properly deal with the sysin sysout syserr streams from the spawned process
        15. Normal boot begins

    4. Start an unknown-to-DC Server from the command line
      1. OBJECTIVES:
        1. Have newly starting server provide information to the DC such that the DC can add it to the domain.xml
        2. Assumption for this use case is the newly starting server is part of a ServerGroup known to the DC. See "Start an unknown-to-DC Server in unknown-to-DC ServerGroup from the  command line" for the use case where this is not the case.
        3. Otherwise, objectives are same as 3.1.
      2. Required information:

        1. Same as 3.2
        2. Alternative 1: get server-specific information from the command line
          1. The name of the ServerGroup of which the Server is a member -- command line
          2. Required Server-specific information -- command line
            1. bind address
            2. Others??? -- depends on domain scheam
          3. Any optional Server-specific overrides?
            1. Is this allowed?? Allowing it requires complex command line processing
        3. Alternate 2: parse local domain.xml and obtain ServerGroup name and server-specific information from there
          1. Adds a parsing step

      3. Process
        1. Basically the same as 3.3
        2. In step 3.3.8.1, DC requests the name of newly joining Server's ServerGroup
          1. Why not provide this information along with the Server id?
            1. Doing that forces use case 3 (where the Server id is known to the DC) to deal with getting the ServerGroup name, either from command line or the local domain.xml
          2. If the DC does not recognize the ServerGroup name, we are in the "Start an unknown-to-DC Server in unknown-to-DC ServerGroup from the  command line" case
    5. Start an unknown-to-DC Server in unknown-to-DC ServerGroup from the command line

    6. NOTE: It is currently not our intent to support this use case. The (vague) idea behind it was to support dynamic creation of new server groups on by deploying images on the cloud, but since those images would need to include the server group configuration and creating an image is not a trivial step, there is no reason to not require configuring the server group in the domain as part of the in-advance process that includes preparing the image.

      1. OBJECTIVE
        1. Expand upon use case 4 to include providing the DC with a new ServerGroup configuration, which will be added to the domain.xml
          1. A ServerGroup configuration includes information on the repository location of content needed to run the configuration
          2. Since the ServerGroup is new, it is possible some of the repository content is unknown to the domain
          3. Therefore, part of the objective is to identify any such new content and push it to the domain
      2. Required Information: TODO
      3. Process: TODO
        1. Note that the process needs to recognize that the newly joining Server doesn't determine whether the ServerGroup is unknown. That is the responsibility of the DomainController. If the DC already knows about a ServerGroup with a given name, it's information about that ServerGroup is definitive; any conflicting information from the newly joining Server will be replaced.

      1. Concurrently start a second server from the command line, same InstalledImage

        1. OBJECTIVE
          1. Ensure  that the InstalledImage layout can handle multiple servers (e.g. different write areas; content repository structure allows different servers to have different content)
          2. Ensure that elements involved in the startup (DomainController, ServerManager, InstalledImage) properly handle concurrency
            1. "Properly" could very well mean executing them in series
        2. Required information
          1. Same as starting one server, just done twice
          2. Starting multiple servers implies some mechanism to deal with port conflicts. If the port configuration is expressed in domain.xml, there is a lot of flexibility. However, things are more complex for variants where there may be no record for the Server in domain.xml
            1. Alternative: have some sort of "Server template" notion in the domain.xml; a server can specify it's template name. A template is a named set of Server-level configuration overrides. Complex.
            2. Alternative: something like the SBM "ports-xxx" concept is part of the ServerGroup configuration; what "ports-xxx" to use for a given Server can come from the command line. However, this notion may not map very well to how we wish to use to configure services; the current SBM is based on a separate configuration for ports that is disconnected from the services that actually use those ports.
        3. Process: TODO

      2. Start an unknown-to-DC Server on a cloud host
        1. OBJECTIVE
          1. Basically the same as use case 4, except we
            1. stipulate that no information comes from outside the host environment
            2. recognize things like IP addresses may not be known in advance
            3. Recognize that the Server's id may not be known in advance
              1. i.e. we shouldn't assume that the user prepares a separate cloud image for each server with a different Server id included in the image
        2. Required Information: TODO
        1. Should be the same as 4.2 except
          1. The Server id  needs to be generated.
            1. UUID
            2. Derived from host name or  host address
            3. See discussion at http://community.jboss.org/thread/148809?tstart=0
          2. As discussed in the "Start a  ServerManager on a cloud host" use case, any address in the  Required Information should be a keyword/alias.
        1. Process: TODO

      3. Start multiple Servers on same cloud host, same InstalledImage

        1. OBJECTIVE
          1. Basically the same as use case 6, except
            1. we stipulate that no Required Information comes from outside the host environment
            2. it's probably not a concurrent case; i.e. the boot process of the cloud image will likely start the servers in series
        2. Required Information: TODO
          1. The port conflict issue discussed in 6.2 is definitely relevant here, since the assumption is the Server id is unknown in advance and thus port information cannot come from an ordinary named Server element in the domain.xml
        3. Process: TODO

         

      4. Start a domain controller from command line

        1. OBJECTIVE
          1. Similar to launching a Server, but the Server is running the DomainControllerSubprofile
            1. Server needs to understand it can be the DC and determine if it is
              1. If not, act like a regular server in terms of contacting a DC to get latest domain config, content
              2. If yes, bypass the domain synchronization process
      5. Start a second domain controller from command line (lower priority for implementing, but needs to be explored)
        1. OBJECTIVE
          1. Explore in more detail the case where the newly starting DC determines it is not the acting DC
      6. Start a domain controller on a cloud host

          1. OBJECTIVE

            1. Combination of use cases 7 and 10
            2. Clarify the "discovery" process that will allow other nodes to find this DC since it's IP address is not known in advance and multicast discovery is presumably not available
          2. Required Information: TODO
          3. Process: TODO
            1. Perhaps includes a registration step with an external process a la a JGroups GossipRouter that other processes use for discovery
        1. Start a second domain controller on a cloud host
          1. OBJECTIVE: TODO
          2. Required Information: TODO
          3. Process: TODO
        2. Start a Server from the DomainController
          1. OBJECTIVE
            1. User uses management API to instruct the DomainController to launch a Server
          2. Required Information: TODO
          3. Process: TODO (In a nutshell, DC contacts relevant ServerManager, tells it to start Server, providing the Required Information)
        3. Start a standalone Server (developer use case)
          1. OBJECTIVE:
            1. Start a Server, but have it skip the process of discovering and contacting a DC, synchronizing with domain etc
            2. Apply any information provided via command line to Server configuration
          2. Required Information: TODO
          3. Process: TODO
        4. Start a standalone Server w/ DomainControllerSubprofile (developer use case)
          1. OBJECTIVE:
            1. Should be the same as 14.1; difference is when the Server starts its profile includes the DomainControllerSubprofile
          2. Required Information: TODO
          3. Process: TODO
        5. Start an embedded Server
          1. OBJECTIVE: TODO
          2. Required Information: TODO
          3. Process: TODO
        6. Start a ServerManager with no DomainController running
        7. Start a Server with no DomainController running
        8. Start a DomainController with existing ServerManager's and Servers running

         

        Stop Use Cases

         

        1. Stop a Server from the DomainController

        2. Stop a Server from the command line

        3. Stop a ServerManager from the command line

        4. Stop a DomainController from the command line

        5. Others, TBD as they logically fall out of "Start" use cases

         

         

         

        Questions:

         

        1. Is ServerManager tied to InstalledImage