0. CONTENT

  1. installation
  2. runtime env



1. INSTALLATION

Command Overview:
to install the most relevant files and example configuration for SKV:

  export SKV_CONF=<dev|rpm|...}>
  export MPI_DIR=<path to mpi installation>
  ./skv_install.sh -i <SKV_INSTALL_DIR>


Details:

  * either use one of the prepared make.conf_NNN files or make a copy
    of one of them to adjust to your needs. Then set SVK_CONF to NNN

  * then export the path to your MPI installation into MPI_DIR env
    variable

  * then run the skv_install.sh script and provide the installation
    directory where you want SKV installed





2. RUNTIME ENVIRONMENT

2.1 prerequisites and dependencies

 Installation and setup of the following is not covered here:

  * any MPI runtime env to start the server (and parallel clients if
    applicable)

  * SoftIWarp (siw) if you plan to run server and clients on
    overlapping sets of nodes or nodes without InfiniBand or other
    verbs providers installed

  * an OFED-RDMA capable network and setup (alternative siw)


2.2 SKV runtime

 * skv_server.conf: this file contains important configuration
   information for server AND client.  The search for the config file
   is performed in the following order:

   * command line parameter for the Server (-c <path+filename>)
   * per-user config under ${HOME}/.skv_server.conf
   * global config under /etc/skv_server.conf

   the skv_install script installs an example copy as
   <SKV_DIR>/etc/skv_server.conf The file contains descriptions of
   each setting and should be self-explaining

 * running the server:

   * a single server can be run by just executing
     <SKV_DIR>/bin/SKVServer [-h] [-c <configfile>]. If you want a
     parallel server you need to use your preferred MPI program
     launcher to kick it off. For example:
   
        mpiexec -n 8 -f /etc/machinefile <SKV_DIR>/bin/SKVServer

   * if everything works fine, you'll _not_ get back a prompt. You'll
     see an SKVServer process running and /tmp/ (as of the defaults in
     skv_server.conf) will contain several skv_files as described
     below

 * skv server files:

   * skv_server.info; skv_machinefile: depending on the settings in
     the config file, the file(s) contains a list of IP addresses and
     port numbers indicating how to connect to the server on THIS
     particular node.  Each server instance replaces its entry with
     the loopback address and can be reached via a proper siw
     installation (this is only if the file is located on a local file
     system, if the configuration points to a shared file system
     between servers, the address is not replaced. Note that this will
     cause problems for clients on BG/Q, because they need to connect
     to the loopback address via siw)

   * beef.slab.N: is the mmapped file that contains the stored
     data. Where N is the MPI rank of the server process. Currently,
     all storage memory has to be pinned and thus the capacity per
     node is limited by the amount of available memory and the memlock
     limit of the user (see ulimit -l and /etc/security/limits...)

   * *.FxLog logfiles of the server. Logging can be configured via the
     make.conf(.in) file in the base directory of the SKV distribution
     by commenting in/out the *_LOG lines.



 * skv client:

   * a client requires the skv_server.conf file in one of the places
     described above.  If the client program is written without
     commandline support for the config file, you need to pick one of
     the 2 latter options ($HOME or /etc).  Every client needs access
     to the server machinefile to learn about the location of the
     servers.  Since the server creates this file, there's no manual
     intervention required if a client runs on a node that has a
     server too.  However, if the client runs on a distinct set of
     nodes, this file has to be created manually or on a shared file
     system (or by copying one of the server-created files and
     replace the lines that have the loopback address with the proper
     IP address).  In every case, it is suggested to consider the
     server-generated machinefile as a template.

   * clients can be either MPI or non-MPI programs.  Depending on
     which library and compiler was used to create the executable.
     The default build of SKV creates and installes MPI- and non-MPI
     versions of the client libraries.

   * a detailed description of the client API will be available
     later. For now, unfortunately we can only point to the source
     code examples and the file include/client/skv_client.hpp (for C++
     clients) or lib/include/skv.h (for C clients).