Operations Guide

Man Pages for MCS

Monitoring data collection services for UM are provided by MCS.

See Monitoring Collector Service (MCS).

There are two executables for MCS, each with it's own man page:

- MCS Man Page - Unix and Windows command-line interface.
- Mcsds Man Page - Windows Service interface.

Note that these executables are not in the same "bin" directory as the platform native UM executables. Since it is a Java program, it has its own directory sub-tree, "MCS", with sub-directories "bin" and "lib". For example, the MCS executables are under "UMS_6.17.1/MCS/bin". For instructions on using a different directory structure, see the "Usage Notes" sections in MCS Man Page and Mcsds Man Page.

Note also that the MCS uses the underlying platform-specific UM library, so your proper paths should be set up.

# MCS Man Page <-

Unix and Windows command-line interface.

    Usage: MCS [options] [configfile]
    Available options:
      -h, --help                 help
      -p, --property-keys        dump the list of supported property keys to stdout and exit
      -v, --validate             validate config file and exit
      -V, --verbose              be verbose about each message
      -x, --xsd                  dump the configuration XSD to stdout and exit

Description
  The `MCS` command runs the Monitoring Collector Service (MCS). It can be run interactively from a shell or command prompt, or from a script or batch file. (For use as a Windows Service, see Mcsds Man Page.)

Exit Status
  The exit status from MCS is 0 for success and some non-zero value for failure.

Usage Notes

- When shutting down a Unix-based MCS Process, use a SIGINT to trigger a clean shutdown, which attempts to cleanly finish outstanding IO requests before shutting down.

- Given how the MCS was implemented, there are scripts, binary executables, and Java JAR files associated with the service. By default, the scripts and executables assume a certain directory structure, with the scripts and executables stored in a "bin" sub-directory, and JAR files stored in a "lib" sub-directory. This corresponds to how the UM package installation structures the files.

  Starting with UM version 6.17, the user can use their own directory structure. To assist the scripts and executables in finding the JAR files, the user can define an environment variable, "UM_MCS_DIR", which contains the full path for the directory containing the JAR files.

# Mcsds Man Page <-

Windows Service interface.

See UM Daemons as Windows Services for general information about UM daemons as Windows Services.

    Usage: mcsds [options] mcs_cfgfile_name
    Available options:
      -h, --help                  display this help and exit
      -l, --service-log=FILE      set a logfile name for the service log.
      -p, --process-log=FILE      set a logfile name for the mcs process output.
      -s, --service=request       Install, remove or add a configuration file.
                                  Examples: '-s install' to install the service with no config file
                                    '-s install cfgfile.xml' to install the service with a configuration file of cfgfile.xml
                                    '-s remove' to remove the service
                                    '-s config cfg2.xml' to change or add a configuration file
      -e, --event-log-level       Update/set service logging level.  This is the minimum logging
                                  level to send to the Windows event log.  Valid values are:
                                    NONE - Send no events
                                    INFO
                                    WARN - default
                                    ERROR
      -E, --env_var_file          update/set the environment Variable File
      -f, --flatdir               specify that binaries and java libraries are in the same directory
                                    Note: This sets UM_MCS_DIR environment variable to the directory path of this executable
      -U, --noenv_var_file        unset env_var_file (-E) entry
                                    Note: -U and -E are not supported on the same command line

Description
  The `mcsds` command has two functions:
  - First, it lets the user supply Windows Service operating parameters, which the command saves into the Windows registry. Those operating parameters are subsequently used by the MCS Service. See Configure the Windows Service.
  - Second, it provides Windows with the MCS daemon executable to run as a Service.

  The "mcs_cfgfile_name" parameter specifies the file path for the MCS's XML configuration file. It is supplied in conjunction with the "-s config" option (see below). See MCS Configuration File for configuration details.

  The "-l" option specifies a "service" log file path, which is saved in the Windows registry and subsequently by the Windows Service. Under normal circumstances, this log file will never be written to. It will be written if the MCS is unsuccessful in starting up as a service. (The normal MCS log file is configured differently, using the <log> element in the configuration file.)

  The "-p" option specifies a "process" log file path, which is saved in the Windows registry and subsequently by the Windows Service. Under normal circumstances, this log file will never be written to. It will be written if the Java JVM writes to standard out or standard error, of if the MCS is not able to write to its configured log file.

Warning
  By default, the MCS's configuration file uses <log type="console">. In this case, normal MCS logs are written to standard out and will be captured in the "process" log file. This is not recommended as it leads to unbounded growth of the log file. Users should set <log type="file"> and related attributes to control the log file sizes.

  For "-s install" see Install the Windows Service.

  For "-s remove" see Remove the Windows Service.

  For "-s config" and "-e", see Configure the Windows Service.

  The "-h" option prints the man page and exits.

  The "-E env_var_file" option provides a convenient method to specify environment variables for the service without having to modify the system-level environment. The MCS service will read this file and define variables in its own environment.

  The "-U" option removes a previously set "env_var_file" ("-E") so that the next time the Windows service is started, that file will not be read. (New in UM version 6.17)

  The "-f" option is a short cut for telling the MCS that its JAR files are in the same directory as the executables, without the need to define the "UM_MCS_DIR" environment variable. (New in UM version 6.17)

Exit Status
  The exit status from MCS is 0 for success and some non-zero value for failure.

Usage Notes

- When installing the MCS as a Microsoft Windows service, use only local disk devices and fully qualified path names for all filenames. This is because Windows services run by default under a Local System account, which has reduced privileges and is not allowed access to network devices.

- Given how the MCS Windows service was implemented, there are binary executables and Java JAR files associated with the service. By default, the executables assume a certain directory structure, with the executables stored in a "bin" sub-directory, and JAR files stored in a "lib" sub-directory. This corresponds to how the UM package installation structures the files.

  Starting with UM version 6.17, the user can use their own directory structure. To assist the executables in finding the JAR files, the user can define an environment variable, "UM_MCS_DIR", which contains the full path for the directory containing the JAR files. This environment variable can either be made at the system level, or can be defined in a disk file, specified by the "-E" command-line option to `mcsds`.

  Alternatively, if you plan to store the executables in the same directory as the JAR files, you can instead use the "-f" command-line option to `mcsds`.

- Stopping the MCS service triggers a clean shutdown, which attempts to cleanly finish outstanding IO requests before shutting down.

Attention
  Do not use the task manager or the "kill" command to stop a UM daemon running as a Windows service. Use the Windows service control panel to stop the service.