[ ALMA ] ALMA Common Software ACS 6.0 documentation


User Guide - Acs Command Center




Content

  1. Overview
    1. Launching Command Center
    2. Starting Acs
    3. Running Clients
    4. Stopping Acs

  2. Running Acs
    1. Deployment Scenario A
    2. Deployment Scenario B

  3. Managing Projects

  4. Extra Tools

  5. Glossary
    1. Progress Panel
    2. Deployment Info View
    3. Log Area
    4. Acs Instance
    5. Cdb, Cdb- Root

  6. Other resources
    1. What's New?



1. Overview


This section describes how to launch Acs Command Center and why you would want to launch it.

Launching Command Center


Acs Command Center is a tool to start up, manage, and shut down Acs sessions. It can be launched in two ways:

   a) via the command "acscommandcenter" in your (Linux) shell

        Command line options:
        Commandline arguments:


   b) via the Acs Java Web Start page (for this, your browser needs to have a Java Web Start plugin)


To make clear what Acs Command Center can do for you (and what it can't do), we first look at the general work-flow of an Acs session. If you have worked with Acs on the command line before, you will find these steps familiar.

Generally, a session with Acs consists of four tasks. We will give an overview here, and discuss them in more detail in the following sections.

Starting Acs


    1) Start the Services and the Manager
    2) Start one or more Containers

The single workers (worker = Service, Manager, or Container)  can be run on one single host (see figure A) or on several hosts (see figure B).

Deployment Scenario A
Deployment Scenario B
Figure A: Simple Deployment Scenario A
 Figure B: Complex Deployment Scenario B


Running Clients


After Acs has been started, you will want to run clients against it. Such a client can either be something provided by you or a preinstalled client (Acs comes with various popular and useful clients). These preinstalled clients can directly be started from within Acs Command Center through the Tools Menu.

    3) Run one or more clients


Stopping Acs


After your work is done, you should shut down all workers in reverse order.


    4) Stop the Container(s), the Manager, and the Services




Acs Command Center allows for different deployment scenarios, from simple ones like A to complex ones like B.* In the following section, you will learn how scenarios A and B can be put into practice.


---
*: Acs Command Center's frontend only supports scenarios where Services and Manager run on the same host. Acs Command Center's project files on the other hand do not have this constraint (as they are used for other purposes as well).

2. Running Acs


This section provides step-by-step instructions on how to set up the sample scenarios sketched in the previous section.

Deployment Scenario A

In our first deployment scenario (recall figure A), all workers run on localhost.


Figure C - Main Window
Figure C - There and back again... in 7 steps

Preparation

To run Acs locally on your machine, you have two alternatives:

a) Local script running
This requires a full, native Acs installation on your machine: Acs Command Center will use shell and python scripts to run your Acs installation.

Make sure "Local" is selected in the Common Settings (1).

Specify the Acs Instance to use (2, see Acs Instance in the glossary).


b) Pure Java running

This is a platform-independent variant that offers not all, yet the most frequently used features. Acs Command Center will execute all workers within its own Java Virtual Machine.

Make sure "Java-only Acs" is selected in the Common Settings section of the user interface.

Specify the Acs Instance to use (2, see Acs Instance in the glossary).

You need to specify a directory where an Acs configuration database is located (see also Cdb in the glossary). Commonly, there are three ways of gaining access to such a directory:

a) Download a Cdb and install it in your filesystem

Go to the Command Center Cdb Page and get yourself a tarred Cdb. Extract the archive in your local file system. The path plus the name of the archive will be your Cdb root.

Example: You downloaded acc-cdb-2.tar, stored it in your local home and extracted it there. This yields a new directory <home>/acc-cdb-2 which is your Cdb root:

on Windows  
 c:/docume~1/johnny/acc-cdb-2  
 Note: Use 8.3 names, no whitespace allowed
on Linux
 /home/johnny/acc-cdb-2


b) Java Web Start

If you have started (or plan to start) Acs Command Center via Java Web Start, the installation of a Cdb is done for you automatically in your local home directory. The correct directory then simply is <home>/.acsjava, e.g.:

on Windows  
 c:/docume~1/johnny/.acsjava  
 Note: Use 8.3 names, no whitespace allowed
on Linux
 /home/johnny/.acsjava


c) Native Acs Installation

If you have access to a native Acs installation, there are chances you can use the Cdb that comes with it. The problem is that such a Cdb does not contain several necessary schema files - instead those schema files are located within the ACSROOT structure, outside the Cdb structure. Acs Command Center will attempt to find those schema files using the Java system properties ACS.cdbpath or ACS.root.
As a convenience, it will likewise examine the Java system properties ACS.cdbroot or ACS.data to find out the Cdb root directory.

Note that on Linux these properties are automatically set from your environment variables when you run acscommandcenter. On Windows, you need to set them yourself (e.g. -D ACS.cdbroot=y:/ACS-4.0/ACSSW) if you'd like to use this feature.

For the Cdb-Root Directory ...
...set environment variable
$ACS_CDB
(or alternatively:
 $ACSDATA)
...or set Java system property ACS.cdbroot
(or alternatively:
 ACS.data)


For the Additional-Schemas Directory ...
...set environment variable $ACSROOT
...or set Java system property ACS.cdbpath
(or alternatively: ACS.root)


To make a long story short: If you're on Linux, everything might instantly work without further interaction required - just try it out. If it doesn't work, use one of the afore described solutions.

Start

Press the Acs Suite's play button (3), which will start the Services and the Manager. A progress panel will come up (see Progress Panel in the glossary for more information). Note that while the progress panel is up, some controls in the user interface are locked. When all steps have been completed successfully, it will close automatically.

The output of any Acs-related action you trigger can be viewed in its own tab in the log area (L, see Log Area in the glossary for more information). If all goes well, there's no need to pay much attention to these logs. In case of problems in running the Acs Suite, however, you can use the (advanced) option of starting the services and the manager separately: Activate the advanced controls section by checking the avdanced checkbox,  press the Services'  play button,  wait for the progress panel to close, then press the Manager's play button.


The freshly started Manager now appears in the deployment info view (D, see Deployment Info View in the glossary for more information).

Ensure you have at least one Container visible on screen (their amount can be adjusted using the plus and minus buttons on the bottom, C). Specify a name (4) and a type (5) for the Container, e.g., "frodoContainer" of type java, then press play to start the Container (6).

Note: The Container name you specify here is used by the Manager to associate components with the Container. It must therefore be the same as the name specified in the CDB for the component(s) you're interested in working with. For C++, this is typically bilboContainer, for Java frodoContainer, and for Python aragornContainer.


Acs is now up and running, and clients can be run against it.
To run one or more of the predefined clients, use the Tools menu. For some of the tools, you may be asked to provide additional information.

Stop

Simply press the Acs Suite's stop button, (7). This will stop the Container(s), the Manager, and the Services. Once the Acs Suite has been stopped, the Manager will be automatically removed from the Deployment Info View.

Note: There's an asymmetry in the behavior of starting the Acs Suite and stopping the Acs Suite: The first starts the Services and the Manager, the latter stops the Services, the Manager plus any Containers.

Again, all output will go to the log area (L). In case of problems you have the possibility to stop all workers separately: first stop the Container through its stop button,  then stop the Manager and finally stop the Services through their stop buttons in the advanced section.

Troubleshooting

If you encounter problems, e.g., the progress panel presents an error message, and find the Acs session in an inoperable state,  you can attempt to terminate it with the kill button (X). Note, however, that this is, as the name implies, a brute shutdown that may kill the Acs Command Center as well.



Deployment Scenario B


In our second scenario (recall figure B), the workers run distributed on several separate hosts.

Preparation

Acs Command Center provides a way to start workers on remote hosts through a startup variant called

Remote script running

With this variant, Acs Command Center logs in to other hosts via SSH and runs Acs on these hosts. This variant is similar to Local script running  in that Acs Command Center will use the same collection of scripts to run Acs on the remote hosts. This implies that a full, native Acs installation must be present on these hosts.

As of version 5.0, Acs Command Center supports two variants of SSH operations:

a) The platform-independent variant is self-contained within Acs Command Center, and you get it "for free" without the need to configure anything. It has certain limitations, however: in particular, it only supports user/password authentication. This means, when you want to start/stop Acs on a remote host, you have to provide a valid accountname and a password for the remote host. The platform-independent variant is the default.

b) The native variant, on the other hand, makes use of an ssh program already installed on your local system. Thus, it can allow for all features of your native ssh: for instance, and foremost, the public-key authentication. That means, if your native ssh is configured properly, you wont' be required to provide a password for the remote host you want to start/stop Acs on.
The ssh program is available for virtually all platforms (see http://openssh.org/), and many systems already have it installed.
Beware: If you use the native variant but you did not configure ssh for public-key authentication, it will prompt for your password - and that prompt will be on the terminal (xterm, dos box) from which you started Acs Command Center. This behavior is part of the security concept of ssh.


Three ways exist to choose which of the two variants you want to use:

a) Through Java System Properties

AcsCommandCenter.useNativeSSH 
"true"
 use native variant 
"false" or undefined
 use platform-independent variant


There are more, rather expert-level, properties that control the behavior of the native mode. Foremost, the following property may be useful if you find unwanted SSH processes lingering around after quitting the Acs Command Center:

AcsCommandCenter.killNativeSSH 
"true"
 forcibly destroy still running SSH processes when exiting Acs Command Center 
"false" or undefined
 don't automatically destroy running SSH processes,
let operating system decide what to do with these processes, instead.


To define a Java System Property, issue the following command before running Acs Command Center:
 
export JAVA_OPTIONS="$JAVA_OPTIONS -Dname=value"
with the possible name and value arguments listed above. Note that there must be no spaces anywhere in "-Dname=value".


b) By specifying command line switches to the acscommandcenter command

-useNativeSSH
-killNativeSSH

Example: acscommandcenter -useNativeSSH -r myProject.xml

For a more detailed explanation of the meaning of these command line switches, please refer to foregoing section a).


c) Through Acs Command Center's Expert menu

In the main menu, go to Expert->SSH Mode and choose the desired mode. Note that the choice you make here will not be saved when you quit Acs Command Center. That is, you will have to redo your choice on your next run. For persistent behavior, you need to use one of the afore mentioned possibilities a) or b).



To continue with remote script running, make sure "Remote" is selected in the Common Settings (1). As for the local variant, you should specify an Acs Instance (2).

Start

Specify a remote host (e.g., "host1") and user credentials for that host in the Common Settings. Start the Services and the Manager as described before by pressing the Acs Suite's play button (3). Alternatively start them via their respective buttons in the advanced controls section.

Use the plus button (C) to ensure you have at least two Containers available on screen.

Give the first Container a name, and choose its type (4, 5). Then press the first Container's configure button (the one labeled with three dots) and specify a host (e.g., "host2") and appropriate user credentials.

Do the same for the second Container.

Finally, press play (6) to start all Containers in the order you entered them into the list. To move a Container up or down within the list, select it by clicking into its name field (4) and press the arrow buttons (C).

Stop

Shut down everything through the Acs Suite stop button (7). Alternatively shut down all workers in reverse order through their respective buttons. Please refer to Local script running above if unsure.

Troubleshooting

As for the local variants, you can terminate Acs mercilessly through the kill button (X) if it appears to hang and alike. Again, note that this will also kill the Acs Command Center if it is running on the same host.



3. Managing Projects


All settings you entered (in the Common Settings section, in the Containers section, etc.) can be stored as a Project. Projects are a neat thing that can save you a lot of typing. Their usage should be self-explanatory, simply use the Project menu to create, store, and load projects.

Note: Any passwords you enter as part of user credentials will not be saved when you store a project. You will have to reenter them the next time you use the project.







4. Extra Tools


Tools Menu

The Tools menu provides access to several useful tools dealing with Acs and Corba. They are invoked as separate local processes, in other words, they must exist as executables on your host.

The necessary configuration required by the tools is automatically derived from your Common Settings without further interaction required (still some tools might ask for additional configuration when you launch them).
If you are not satisfied with the default settings, a custom configuration for the tools can be defined in the Configure Tools... dialog.

Tool Definitions

The tools in the Tools menu are defined in an xml file AcsCommandCenterTools.xml that AcsCommandCenter reads in on startup. These definitions can be re-read at run-time. This is done through Expert -> Tools -> Replace All... which brings up a file-search dialog to point to a new definition file. The default definition file contains quite exhaustive documentation in case you'd like to copy and accommodate it.


5. Glossary


Progress Panel


    The Progress Panel  shows the single steps necessary to accomplish a task, and how far Acs Command Center has succeeded so far in performing your request. When an error occurs, it is also shown in the Progress Panel. Thus, it will (hopefully) support you in tracking down failures.

figure E - Progress Panel
Figure E - Progress Panel showing a host lookup error


Deployment Info View


    The Deployment Info View shows information about an Acs Manager and its related workers. When you start a Manager via the Acs Command Center, the Manager is automatically added to the Deployment Info View. Still, you can add any Manager manually provided you know which host and port it runs on: according to the Acs conventions, the port of a Manager is "3x00", where "x" is the Acs instance (0-9). Simply type in the Manager's host and port into the fields above the Deployment Info View and press the "Add to View" button.

The shown information will be refreshed automatically. Note, however, that this automatism cannot detect all changes on the server-side. To refresh the data manually, press the "Full Refresh" button.

In the screen shot below, a component has been selected in the tree: all occurences of the component are highlighted in response (the selected occurrence in blue, all other occurrences in gray).

Figure F - Deployment
Figure F - Deployment Info View with a manually added Manager


Most elements of the Deployment Info View offer context menus that allow to, e.g., refresh the currently displayed information, activate a component, or shut down a Manager. The Deployment Info View's capabilities are very close to that of the admin client tool ("adminc"). Give it a try.


Log Area

    The Log Area shows the logs (i.e. the console output) of started processes. It allows to view, copy, and save these logs.

To prevent the Java Virtual Machine from running out of memory, the Log Area allows to restrict the buffer size for each log. It is recommended to make use of this feature -- note however that the Scroll Lock for a log only works properly if its buffer size is "unlimited".  The foregoing said, you should only activate the Scroll Lock, resp. disable the buffer size limit, in special cases but not in the general case.

figure G - Progress Panel
Figure G - Log Area showing the console output of started processes


Acs Instance

    As of version 3.0, Acs allows for more than one session to be run on the same machine at the same time; we speak of multiple Acs instances (currently up to ten). One may think of a collection of slots on a host, with each one being capable of holding one Acs instance. If you have special preference on which slot to occupy  (e.g., because you made an agreement with your team members to avoid clashes), specify its number explicitly. Otherwise simply try with the default number 0 (zero). If the requested slot is already occupied, you will receive an according message. You should then try a different number.


Cdb, Cdb-Root

    The Cdb (Configuration Database) contains information about schemas, Managers, and components. The Cdb's content is read and published by a server process (Cdb-Dal). In order to be readable by the server process, the Cdb needs to reside in a filesystem directory. This directory is called Cdb-Root.


6. Other Resources


What's new?

The change log for the different versions is on the What's New? page



Version
 Author
Changes
2007-02-09 Marcus Schilling Adjusted to Acs6.0
2005-10-28 Marcus Schilling Adjusted to Acs5.0
2005-07-26
 Marcus Schilling
 Adjusted to Acs4.1.2
2005-04-27
 Marcus Schilling
 Adjusted to Acs4.1
2004-11-08
 Marcus Schilling
 Adjusted to Acs4.0
2004-05-10
 Marcus Schilling
 Adjusted to Acs3.1
2004-02-04
 Marcus Schilling
 Adjusted to Acs3.0.1
2003-11-17
 Marcus Schilling
 Created