next_inactive up previous


HostProcControl : Administration Guide
DocumentId:GradSoft-AG503-e-79-02.09.2000-v1.0b
GradSoft http://www.gradsoft.com.ua


Contents

General information

Overview

Project mission

HostProcControl is a CORBA service, which provides API for remote managing of an operating system. Using HostProcControl, you can create CORBA-objects able to do:

  1. regarding to the host file system:
    1. reading and writing of files;
    2. deleting files;
    3. checking ones;
  2. regarding to the process control:
    1. receiving of the list of processes;
    2. starting processes;
    3. killing ones.

Platforms

You can use HostProcControl with several ORB realizations such as TAO, omniORB, and ORBacus for UNIX and with ORBacus only for Windows NT.

Support

The package is created and supported by GradSoft company, the home page of GradSoft is http://www.gradsoft.com.ua/. The current release number of the project is HostProcControl-1.0.

Project components

Supply

Supplied package consist of next of principle components:

  1. Host control API in the form of IDL-module HostControl.idl
  2. C++ source code of:
    1. Server HostControlServer;
    2. Accessories consisting of:
      1. NtInstaller for installing HostControlServer as Windows NT service;
      2. Samples of client applications;
  3. Compilation management tools for Windows NT;
  4. Compilation management tools for UNIX;
  5. User guides:
    1. Programmer guide;
    2. Administrator guide (this file);
All these components are joint in archive named HostProcControl-1.0 which may be .zip or .tar.gz depending on the choise.


Installation

Installed software consist of:

  1. IDL module HostControl.idl;
  2. Stub header file;
  3. C++ static libraries:

    platform library name contents
    UNIX libHostControlClient.a stub
    UNIX libHostControl.a stub, skeleton, servants
    Windows NT HostControlClient.lib stub
    Windows NT HostControl.lib stub, skeleton, servants

  4. Executable files:

All these components are created from the source code at the time of installing procedure (except for the HostControl.idl) and then are copied to personal subdirectories of some directory of installation selected by user. Subdirectory names for coping HostControl.idl, .h files, C++ libraries and executable files are fixed to be idl, include, lib, and bin correspondingly. These subdirectories should be created by user itself before begining installation.

UFO

Next UFO :-) component are created automatically when server is installed as Windows NT service: the file hpcservice.ini in Windows directory. This file is used for unattended startup of HostControlServer.exe.


Installing procedure

Necessary software

  1. CORBA ORB:
  2. C++ compiler:
  3. make:
  4. Special software: package GradC++ToolBox with components ProgOptions and ServiceOptions version 1.0.3 or highter

Installing procedure for UNIX

  1. Make sure that necessary software is installed and run in the current environment.
  2. Extract files from archive HostProcControl-1.0 (being .zip or .tar.gz) to some directory, hereinafter referred to as a <project_root>.
  3. Move out to <project_root>.
  4. Run "configure" by ./configure command;
  5. Start compilation process by command gmake
  6. Become superuser.
  7. Run installation process by command gmake install
  8. If you want to remove automatically generated files, type gmake clean

Installing procedure for Windows NT

  1. Make sure that necessary software are installed and are in working state. Add pathes to "nmake" and "cl" programs into environment variable PATH.
  2. Extract files from archive HostProcControl-1.0 (being .zip or .tar.gz) to some directory, hereinafter referred to as a <project_root>.
  3. Go to <project_root>\config directory and edit file env_inc.nt.mak. You have to set follow nmake values:

    name description
    PROJECT_ROOT <project_root>
    INSTALL_DIR Directory of installation
    ORB_DIR ORB root directory
    MSVC_DIR Microsoft Visual Studio root directory
    GEN_DIR GradC++ToolBox root directory

  4. Go to <project_root>.
  5. Start compilation process by command make
  6. Run installation process by command make install
  7. If you want to remove automatically generated files (such as *.obj, *.lib, *.exe) from <project_root> and its subdirectories, go to <project_root> and type "make clean"

Testing

General information

We provide 6 test/pattern applications disposed in 6 subdirectories 1,2,..,6 of <project_root>/test catalogue and named step1,step6,..,step6 correspondingly. Each application's description is placed to the same sub-directory and named readme<n>.txt, where n is number of the test application.

Test procedure

  1. Run compilation process according to previous chapter of the manual 2
  2. Create test/pattern applications - move out to the <project_root>/test catalogue and call command make
  3. Go to the <project_root>/src catalogue and run HostControlServer with following options:

    --userlist <project_root>/test/HostControlUserlist.ini -OAport 16001
    

    (these options meaning is described in chapter Usage 4 of the present manual);

  4. Check tests as follows - perform with <number> from 1 to 6:

  5. If you want to remove automatically generated test files, go to <project_root>/test and use "make clean"


Usage

Access permissions

A next outline of access permissions control is used:

Note path to user list must be set ( - full name is strongly recomended! ) when server starts.

How to run the server

General information

Service options

  1. Full name of user list:

    The name of user list must be NESCESSARILY defined when server starts (the name undefined or the file is not exist leads to starting break). To fix the name, the option

    --userlist <filename>

    is provided. If the name spesified is NOT full name, it is supposed to be relative to the same "base" catalogue as the configuration file.

  2. Initial object reference:

    Publication of HostProcControl initial object reference is realized by means of module ServiceOptions derivable from package GradC++ToolBox. ServiceOptions provides facilities to use corbaloc style IOR to initial object and allows to publish IOR via next ways at user's option:

    1. if --with-naming option used, then initial object of service is reflected in NamingService;
    2. if --ior-stdout option used, then IOR is transformed to srting and printed on standard output;
    3. if --ior-file-HostControlService <filename> option used, then IOR is transformed to srting and placed into file <filename>.

  3. Parameters of ORB:

    In order to client be able to use corbaloc IOR later, you must set at least one ORB parametr when server starts: you must fix the port to communications via common ORB option such as

    Another parameters of ORB may be fixed too, and common ORB option for that must be used. However keeping in mind necessary: An options syntax in our program is the same irrespective of way these options has been obtained via. That is the spelling of ORB options in configuration file must be the same as the spelling in the command line. If you want to use syntax accepted for the ORB-like configuration file, you must create additional ORB-like configuration file and connect it via common ORB option -ORBconfig <filename>. For example, it is possible to use:

    ./HostControlServer --userlist HostControlUserlist.ini -ORBconfig orb.cf
    
    where orb.cf proide following settings:
    ooc.orb.server_timeout=2
    ooc.orb.oa.port=1025
    

Two ways to run HostControlServer for Windows NT

There are two ways to run HostControlServer for Windows NT:

  1. to run in capacity of console application
  2. to run in capacity of Windows NT service

On the first way you may simply call HostControlServer.exe with some options described. To install program in capacity of Windows NT service (and run it) dedicated application NtInstaller.exe may be used. The usage of NtInstaller.exe is following:

  1. Start NtInstaller.exe ( pop-up dialog box will be reflected )

  2. To installing service fix next parameters:
    1. the name of NT service ("HostControl" is proposed);
    2. the path to HostControlServer.exe executable file;
    3. the command line to send into the program.

    and press {Install and Start}. If all right, service will be installed and started with parameters present.

    Details:

    1. If the service has been already installed, it will be removed and installed anew.
    2. Autorun mode established. That is to say service being automatically runned when system starts.

  3. To get an information about service installed press the button {Service information}. In that case service status and starting parameters for working service will be presented.

  4. To removing service press the button {Uninstall}.

Model start procedure

Suppose the operation system is Windows NT and server must be started as a console application. The model start procedure is that:

  1. To fix a base - to choose a <base> directory and save its name in system variable HPC_CONFIG.

  2. To create a user list in <base> cataloigue (NB: it may be empty file being filled after start). Suppose the name of it is that: HostControlUserlist.ini

  3. To create <base>\HostControlConfig.ini configuration file with following contents (see http://www.gradsoft.kiev.ua/eng/Products/ToolBox/ProgOptions/ProgGuide/ProgrammingGuide_eng.html for more details):
    @"ProgOptions config file" // [first string] This stuff must create the file 
    
    # This is HostProcControl configuration file to use by executable:
    
      HostControlServer.exe  /* in the fist significant word's capacity  
                                the name of program must be used */
    # users list:
    
      --userlist HostControlUserlist.ini  /* the name of user list
                                             relative to the base */
    # options for ORB:
    
      -OAport 16001  /* ORB option spelling is the same
                        as option spelling in the command line */
    
    : this is EXAMPLE, but it may be copied and used directly.

  4. Run HostControlServer.exe without options.

Output messages being able to appear when server starts

  message situation actions connected
1 error of StartServiceCtrlDispatcher for Windows NT only: error of starting NT service program termination
2 error of parsing of <filename> erroneous format of configuration file specified program termination
3 filename necessary is NULL argument of either "--config" or "--userlist" option is not assigned program termination
4 file to read <filename> does not exist full name of either configuration file or user list is erroneous program termination
5 file to read <filename> does not exist in base directory <directory_name> either configuration file or user list isn't found in base catalogue program termination
6 CORBA System Exception erroneour options of ORB program termination
7 error while orb destroing error of ORB destroing, be able when program terminating no result to you
8 Server has been activated normal start starting server

Compiling client applications

Client applications must be linked with next HostProcControl libraries:

in addition to common ORB libraries including NamingService

Running client applications

Keep in mind options of server has been started!

Security risks

Note, that running HostProcControl allows client applications to get full access to server operation system.

So, to minimize security risks, please, follow next rules:

Remoiving package

  1. For Windows NT only:
    1. use NtInstaller to remove HostControl NT service if it is installed;
    2. check file hpcservice.ini in Windows catalogue (mostly C:\WinNT) and remove it if it's exist.
  2. Remove configuration files and user lists been created;
  3. Remove the system variables HPC_CONFIG if it is used;
  4. Remove directory of installation or HostControl<smth> files from it; see chapter Project components 1.2.2 for the list of such files to be removed.
  5. Remove directory in wich archive supplied has been opend.

History of the document

09.04.2001
current release; main changes relative to the previous release HostProcControl-1.0b2:
  1. Chapter General information is extended;
  2. New chapter Remoiving package is added.
24.02.2001
first public version.


next_inactive up previous
GradSoft