Guide for Persistence

Man Pages for Store

Persistent Store services are provided by Store Process.

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

- Umestored Man Page - Unix and Windows command-line interface.
- Umestoreds Man Page - Windows Service interface.

# Umestored Man Page <-

Unix and Windows command-line interface.

    UMP Store daemon
    Usage: umestored [options] configfile
    Available options:
      -h, --help                     display this help and exit
      -d, --dump-dtd                 dump DTD to stdout
      -f, --detach                   detach from terminal (not supported on Windows)
      -v, --validate                 validate config, but do not run
      -u, --use-utc                  Use UTC time format for log messages
      -a, --affinitize=PCPU[,RRLIST] assign CPU process affinity to PCPU. If optional RRLIST is given
                                     assigns CPU affinity in a round-robin sequence as key processing
                                     threads are created, example: -a 1,3,5 assigns CPU 1 to the process
                                     and CPUs 3, 5, 3, ... to created threads in a repeating sequence

Description
  The `umestored` command (the final "d" stands for "daemon") runs the Store Process. 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 Umestoreds Man Page.)

  The "configfile" parameter is required and specifies the file path for the Store configuration file. See Configuration Reference for Umestored for configuration details.

  The "-f" option directs a Unix-based `umestored` to fork a child process which detaches from the controlling terminal. The `umestored` command normally remains attached to the controlling terminal and runs until interrupted. With "-f", the `umestored` command exits back to the shell, and the forked child continues running in the background.

  The "-a" option provides the CPU core affinity for Store threads. This "pins" the threads to one or more desired CPU cores, which can provide a significant improvement in throughput. See Store Thread Affinity for details.

  The "-d" option dumps (prints) the Store's XML DTD to standard output. After dumping the DTD, `umestored` exits.

  The "-u" option tells the Store to format its log file timestamps as UTC.

  The "-v" option validates the XML structure of the given configuration file against the Store's XML DTD. After validating the configuration file's XML structure, `umestored` exits with status 0 for no errors, or non-zero if errors were found. For example:

      umestored -v /um/store1_cfg.xml

  Note that valid XML structure does not guarantee that the configuration file is completely correct. It must be tested on a running Store.

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

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

Usage Notes
  When shutting down a Unix-based UM Persistent Store process, use a SIGINT to trigger a clean shutdown, which attempts to cleanly finish outstanding IO requests before shutting down. Two successive SIGINTs force an immediate shutdown (not recommended unless absolutely necessary).

# Umestoreds Man Page <-

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

    UMP Store service
    Usage: umestoreds [options] [configfile]
    Available options:
      -E, --env_var_file             update/set environment variable file
      -U, --unset_env_var_file       unset the environment variable file
      -h, --help                     display this help and exit
      -d, --dump-dtd                 dump DTD to stdout
      -u, --use-utc                  Use UTC time format for log messages
      -s, --service=install          install the service passing configfile
      -s, --service=remove           delete/remove the service
      -s, --service=config           update configfile info to use configfile passed
      -v, --validate                 validate config, but do not run
      -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
      -a, --affinitize=PCPU[,RRLIST] assign CPU process affinity to PCPU. If optional RRLIST is given
                                     assigns CPU affinity in a round-robin sequence as key processing
                                     threads are created, example: -a 1,3,5 assigns CPU 1 to the process
                                     and CPUs 3, 5, 3, ... to created threads in a repeating sequence
      configfile                     XML config file (if not present, looks in registry)

Description
  The `umestoreds` 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 Store Service. See Configure the Windows Service.
  - Second, it provides Windows with the Store Process executable to run as a Service.

  The "configfile" parameter provides the file path for the Store configuration file. It is supplied in conjunction with the "-v" option or the "-s config" option (see below). See Configuration Reference for Umestored for configuration details.

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

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

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

  The "-a" option specifies the CPU core affinity for Store threads, which is saved in the Windows registry and subsequently by the Windows Service. This "pins" the threads to one or more desired CPU cores, which can provide a significant improvement in throughput. See Store Thread Affinity for details.

  The "-d" option dumps (prints) the Store's XML DTD to standard output. After dumping the DTD, `umestoreds` exits.

  The "-v" option validates the XML structure of the given configuration file against the Store's XML DTD. After validating the configuration file's XML structure, `umestoreds` exits with status 0 for no errors, or non-zero if errors were found. For example:

      umestoreds -v c:\um\store1_cfg.xml

  Note that valid XML structure does not guarantee that the configuration file is completely correct. It must be tested on a running Store.

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

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

Usage Notes
  When installing the UM Persistent Store 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.

  Stopping the UM Persistent Store 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. In particular, if the persistent Store is killed non-gracefully, it can leave its files in an inconsistent state.