Schedwi Manual V0.1.1

Herve Quatremain

This manual describes version 0.1.1 of Schedwi.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License (GFDL), Version 1.1 or any later version published by the Free Software Foundation with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. You can find a copy of the GFDL at this link or in the file COPYING-DOCS distributed with this manual.

This manual is part of a collection of GNOME manuals distributed under the GFDL. If you want to distribute this manual separately from the collection, you can do so by adding a copy of the license to the manual, as described in section 6 of the license.

Many of the names used by companies to distinguish their products and services are claimed as trademarks. Where those names appear in any GNOME documentation, and the members of the GNOME Documentation Project are made aware of those trademarks, then the names are in capital letters or initial capital letters.

DOCUMENT AND MODIFIED VERSIONS OF THE DOCUMENT ARE PROVIDED UNDER THE TERMS OF THE GNU FREE DOCUMENTATION LICENSE WITH THE FURTHER UNDERSTANDING THAT:

  1. DOCUMENT IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, WARRANTIES THAT THE DOCUMENT OR MODIFIED VERSION OF THE DOCUMENT IS FREE OF DEFECTS MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE OR NON-INFRINGING. THE ENTIRE RISK AS TO THE QUALITY, ACCURACY, AND PERFORMANCE OF THE DOCUMENT OR MODIFIED VERSION OF THE DOCUMENT IS WITH YOU. SHOULD ANY DOCUMENT OR MODIFIED VERSION PROVE DEFECTIVE IN ANY RESPECT, YOU (NOT THE INITIAL WRITER, AUTHOR OR ANY CONTRIBUTOR) ASSUME THE COST OF ANY NECESSARY SERVICING, REPAIR OR CORRECTION. THIS DISCLAIMER OF WARRANTY CONSTITUTES AN ESSENTIAL PART OF THIS LICENSE. NO USE OF ANY DOCUMENT OR MODIFIED VERSION OF THE DOCUMENT IS AUTHORIZED HEREUNDER EXCEPT UNDER THIS DISCLAIMER; AND

  2. UNDER NO CIRCUMSTANCES AND UNDER NO LEGAL THEORY, WHETHER IN TORT (INCLUDING NEGLIGENCE), CONTRACT, OR OTHERWISE, SHALL THE AUTHOR, INITIAL WRITER, ANY CONTRIBUTOR, OR ANY DISTRIBUTOR OF THE DOCUMENT OR MODIFIED VERSION OF THE DOCUMENT, OR ANY SUPPLIER OF ANY OF SUCH PARTIES, BE LIABLE TO ANY PERSON FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF GOODWILL, WORK STOPPAGE, COMPUTER FAILURE OR MALFUNCTION, OR ANY AND ALL OTHER DAMAGES OR LOSSES ARISING OUT OF OR RELATING TO USE OF THE DOCUMENT AND MODIFIED VERSIONS OF THE DOCUMENT, EVEN IF SUCH PARTY SHALL HAVE BEEN INFORMED OF THE POSSIBILITY OF SUCH DAMAGES.

Feedback

To report a bug or make a suggestion regarding the Schedwi application or this manual, follow the directions in the Schedwi Help Page.

Revision History
Revision Schedwi Manual V0.1.1September 2007

Herve Quatremain

GNOME Documentation Project


Table of Contents

Introduction
The client
Introduction
Installation
Configuration
Running the client
Enabling SSL
Advanced configuration
The server
Introduction
Installation
Configuration
Running the server
Using the schedwiping program
Using the schedwiloadcert program
Using the schedwidbchecks program
Schedwi and firewalls
About Schedwi

Introduction

Schedwi is a task scheduler. It can run scripts or commands on remote clients at a specified date and time and its chaining capability allows tasks to be run in sequence. Schedwi is composed of the following components:

  • The server schedules the tasks and submits them to the clients. The execution of a task can be triggered by date and time but also by the result of a previous task or by the existence of a file on a remote client (useful when a task must process a file generated by a previous task).

  • The clients (or agents) receive the task requests from the server and run them on the local host. They report the execution status to the server.

  • An interface allows the administrators to follow the task scheduling in real time and to define new tasks.

The client

Introduction

The client part of Schedwi must be installed and configured on all the computers on which tasks have to be run. Moreover, schedwiclnt, the client program, must be running at all time to listen and reply to the server requests.

To be able to run tasks under several user accounts, schedwiclnt must be started under the system administrator account (root on Unix systems). However, if all the tasks have to be run under a single user account on a client computer, schedwiclnt can be started using this account.

Finally, for improved security, communications with the server can be secured using SSL (on systems that support it).

Installation

Requirements

The following components are required for compilation:

  • A C compiler.

  • GnuTLS (visit the GnuTLS Web Site for more information) if the operating system supports it and the communications with the server must be secured (recommended).

    The GnuTLS version required is at least the 1.3.1. (use the GnuTLS certtool -v command to check).

    On some systems, pre-packaged versions are provided. You have to install the libraries, the command line tools and, for the compilation, the development packages (usually gnutls-utils, gnutls-bin, libgnutls13, libgnutls-dev or gnutls-devel)

The compilation process uses the Automake and Autoconf system.

With GnuTLS

The following steps describe how to compile and install schedwiclnt with GnuTLS support:

  1. Download the Schedwi agent in a temporary directory.

    Note

    To avoid the failure of the test suite (see below the section called “Validation test suite”), do not choose a directory which name contains spaces.

  2. Compile schedwiclnt with the following commands (you don't need to be root except for the make install part):

    gunzip -c schedwiclnt-0.1.1.tar.gz | tar xf -
    cd schedwiclnt-0.1.1
    ./configure --enable-ssl \
                --with-libgnutls-prefix=/usr/local/gnutls
    make
    su root
    make install
    

    The --with-libgnutls-prefix=/usr/local/gnutls option specifies the path to the GnuTLS installation directory. This parameter is optional if GnuTLS is installed in a directory known by the system. In this case, the --enable-ssl parameter is even optional as by default configure will try to detect your GnuTLS installation.

Without GnuTLS

The following steps describe how to compile and install schedwiclnt without GnuTLS support - for instance if the operating system does not support it:

  1. Download the Schedwi agent in a temporary directory.

    Note

    To avoid the failure of the test suite (see below the section called “Validation test suite”), do not choose a directory which name contains spaces.

  2. Compile schedwiclnt with the following commands (you don't need to be root except for the installation part):

    gunzip -c schedwiclnt-0.1.1.tar.gz | tar xf -
    cd schedwiclnt-0.1.1
    ./configure --disable-ssl
    make
    su root
    make install
    

configure parameters

configure supports more parameters than the ones described in the previous sections. A complete list can be obtain with configure -h.

The most common one is --prefix=path which is used to specify the installation directory (/usr/local by default)

Validation test suite

The Schedwi agent comes with a test suite which may be use to validate the agent build. This test suite can be run after the make command, just before the make install. For instance:

gunzip -c schedwiclnt-0.1.1.tar.gz | tar xf -
cd schedwiclnt-0.1.1
./configure --without-gnutls
make
make check
su root
make install

Here is an example of a successful test (denoted by ok):

## ------------------------------------------ ##
## schedwiclnt 0.1.1 test suite: schedwiclnt. ##
## ------------------------------------------ ##
  1: Schedwi agent test                           ok

## ------------- ##
## Test results. ##
## ------------- ##

1 test was successful.

Note

The failure of the test suite does not always mean a failure of the build process. On some operating systems, it is the test suite program itself which failed.

On the other hand, a successful test is a strong sign that the Schedwi client will work fine.

Configuration

Configuration file location and syntax

All the configuration parameters are grouped in a single configuration file. By default, this file is named schedwiclnt.conf and is located in the /usr/local/etc directory.

Note

If configure has been run with the --prefix=path option during the installation (see the section called “configure parameters”), the default directory of the configuration file is relative to the provided path. For instance, with configure --prefix=/apps, the configuration file will be /apps/etc/schedwiclnt.conf.

Tip

Run schedwiclnt with the -h parameter. The path of the default configuration file is provided near the end.

However, the configuration file name and path can be specified at run-time using the -c configuration_file option of schedwiclnt.

The format of the file is straightforward:

  • Each parameter is defined on a line by itself. The parameter name and its value are separated by the equal (=) sign. The continuation sign \ used to define a parameter on several lines is not allowed.

  • Empty lines are ignored.

  • Lines starting by # or ; are comments and are ignored. Comments must be on lines by themselves; they cannot follow a parameter definition.

Finally, the syntax of the configuration file can be tested with the -t option of schedwiclnt. With this option, schedwiclnt just tests the syntax and exits.

Basic configuration parameters

Note

All the file paths specified in this section are the default ones. However, if configure has been run with the --prefix=path option during the installation (see the section called “configure parameters”), the default paths are relative to the provided path.

LOG_FILE

Path and name of the log file. This file is only used if the SYSLOG directive (see below) is not set.

LOG_FILE=/usr/local/var/log/schedwiclnt.log by default.

SYSLOG

Specifies that the syslog mechanism must be used to log messages. If this directive is set, LOG_FILE is ignored. The provided parameter is the syslog facility to use (LOG_USER, LOG_LOCAL5, ...). See your syslog(3) manual page for a complete list of values.

No default value.

DATE_FORMAT

The date format for the date and time field in the log file. This value is only used if the SYSLOG directive is not set. See your strftime(3) manual page for a format description.

For example: DATE_FORMAT=%Y%m%d - %H%M%S

DATE_FORMAT=%c by default.

PID_FILE

Path and name of the file that will be used to store the process ID of the schedwiclnt daemon. This file is used by the schedwiclnt program at startup to be sure that an other instance is not already running. This file may also be used by your scripts, to stop the schedwiclnt daemon for instance.

PID_FILE=/usr/local/var/run/schedwiclnt.pid by default.

SERVER

Host name of the Schedwi server. This name must be defined in your system (usually in /etc/hosts, in DNS or in NIS). An IP address in numbers-and-dots notation can also be used.

For example: SERVER=cherry.foo.com

SERVER=localhost by default.

SERVER_PORT

Network TCP port number used by the Schedwi server to listen to clients. A name defined in /etc/services can also be used.

The value defined here must be the same as the one defined in the SERVER_PORT directive in the server configuration file (see the section called “Global Configuration parameters”).

SERVER_PORT=2005 by default.

AGENT_PORT

Network TCP port number used by the Schedwi client (i.e. schedwiclnt) to listen to the server. A name defined in /etc/services can also be used. On most operating systems, the schedwiclnt daemon will have to be started as root if the chosen port is below 1024.

AGENT_PORT=2006 by default.

IFACE_LISTEN

On a multihomed host (several IP addresses and/or network cards), IFACE_LISTEN specifies on which interface schedwiclnt must listen to the server. A host name or an IP address in numbers-and-dots notation can be used.

For example: IFACE_LISTEN=flower.foo.com

By default schedwiclnt will listen to all available network interfaces.

RESULT_DIR

Directory name used by schedwiclnt as a working directory. Temporary job results are stored there before being sent to the server.

RESULT_DIR=/usr/local/var/run/schedwiclnt/results by default.

RESULT_PREFIX

Result files prefix (in the directory specified by the RESULT_DIR directive).

RESULT_PREFIX=job_ by default.

RESULT_SUFFIX

Result files suffix (in the directory specified by the RESULT_DIR directive).

Nothing by default.

SSL configuration parameters

All the following parameters are only used if the schedwiclnt program has been built with the GnuTLS support (see the section called “With GnuTLS” for more details). Otherwise, they are ignored.

Note

All the file paths specified in this section are the default ones. However, if configure has been run with the --prefix=path option during the installation (see the section called “configure parameters”), the default paths are relative to the provided path.

SSLEngine

Toggles the usage of the SSL Protocol Engine for all network communications. Use Y to enable SSL or N to disable it.

SSLEngine=Y by default if schedwiclnt has been built with GnuTLS support.

SSLClientCertificateFile

PEM-encoded certificate file name for the client. A such file has been generated and installed for you during the schedwiclnt built steps. This file must be copied on the server and loaded in the database.

SSLClientCertificateFile=/usr/local/etc/schedwiclnt.crt by default.

SSLClientCertificateKeyFile

PEM-encoded private key file for the client. A such file has been generated and installed for you during the schedwiclnt built steps.

This private key cannot be an encrypted one.

SSLClientCertificateKeyFile=/usr/local/etc/schedwiclnt.key by default.

Important

The private key file defined by this directive must not be copied on the server and must be protected. Use the chmod and chown commands to only allow access to this file and to its directory to the user running the schedwiclnt daemon.

SSLServerCertificateFile

PEM-encoded certificate file name of the server. This file must copied from the server.

SSLServerCertificateFile=/usr/local/etc/schedwisrv.crt by default.

SSLQuickRandom

At startup, schedwiclnt initializes the SSL network layer. This step requires good quality random numbers which are retrieved from the operating system. On some systems this may take a long time (up to 10 minutes). During this time, schedwiclnt is not yet available and working.

SSLQuickRandom can be used to speed up this startup time by using less good quality random numbers and therefore reducing encryption quality.

SSLQuickRandom=0 by default.

Running the client

Starting

To start the Schedwi client daemon simply run the schedwiclnt command. This program goes automatically in the background. If your PATH environment variable does not contain the path to the schedwiclnt command, the full path must be specified. For example:

bash# /usr/local/bin/schedwiclnt 

Note

See the section called “Advanced configuration” if you don't want to start the daemon as root.

schedwiclnt records information in a log file (or in the syslog mechanism - see the section called “Basic configuration parameters”). In case of failure to start the agent, this file may contain precious information on the error.

Stopping

To stop the agent, simply send the TERM signal (number 15) to the schedwiclnt process. The process identification of this daemon is stored in the file defined by the PID_FILE configuration directive.

Important

Never send the KILL signal (number 9) to the daemon. This signal does not allow the schedwiclnt daemon to stop in a clean state.

Reloading the configuration file

Changes to the configuration file whilst the schedwiclnt daemon is running are not automatically taken into account. A stop and a restart of the process will allow it to re-read its configuration file.

For minor changes, concerning the log file path or the date format for instance, it may be easier to send the HUP signal (number 1) to the schedwiclnt daemon. This signal force the process to re-read its configuration file without having to be stopped. Moreover, this signal can be used to rotate the log file as schedwiclnt will close it and reopen a new one.

Important

If schedwiclnt finds an error while reading its configuration file, it stops immediately. Therefore, before sending the HUP signal it is important to be sure that the configuration file is error free. This check can be done by running the schedwiclnt command with the -t option. With this option, schedwiclnt simply checks the configuration file and exits; it does not interfere with the running schedwiclnt daemon.

Sample startup scripts

These sample startup scripts start the Schedwi client daemon as root.

Note

All the following scripts are available under the scripts directory in the Schedwi client archive. A logrotate sample file is also provided for the rotation of the log file (see the logrotate(8) manual page for more details) as well as an OCF Resource Agent script for Linux-HA.

For Sun
#!/sbin/sh

# CHANGE this variable with the schedwiclnt install path
# This path is the one specified by the configure's --prefix option
# during installation.  If no --prefix has been use, the default
# path is /usr/local
SCHEDWI_INSTALL_DIR="/usr/local"

case "$1" in
'start')
        if [ -x "$SCHEDWI_INSTALL_DIR/bin/schedwiclnt" ]; then
                "$SCHEDWI_INSTALL_DIR/bin/schedwiclnt"
        fi
        ;;

'stop')
        /usr/bin/pkill -u 0 -P 1 schedwiclnt
        ;;

*)
        echo "Usage: $0 { start | stop }"
        exit 1
        ;;
esac
exit 0

This script, named schedwiclnt, can be installed in /etc/init.d and links can be created in the startup folders as follow:

ln /etc/init.d/schedwiclnt /etc/rc3.d/S90schedwiclnt
ln /etc/init.d/schedwiclnt /etc/rc0.d/K90schedwiclnt
ln /etc/init.d/schedwiclnt /etc/rc1.d/K90schedwiclnt
ln /etc/init.d/schedwiclnt /etc/rc2.d/K90schedwiclnt
ln /etc/init.d/schedwiclnt /etc/rcS.d/K90schedwiclnt
For HP-UX
#!/sbin/sh

#
# Start schedwiclnt
#

# CHANGE this variable with the schedwiclnt install path
# This path is the one specified by the configure's --prefix option
# during installation.  If no --prefix has been use, the default
# path is /usr/local
SCHEDWI_INSTALL_DIR="/usr/local"


PATH=/sbin:/usr/sbin:/usr/bin
export PATH

rval=0
set_return() {
        x=$?
        if [ $x -ne 0 ]; then
                echo "ERROR CODE $x"
                rval=1
        fi
}

case $1 in
start_msg)
        echo "Start schedwi agent daemon"
        ;;

stop_msg)
        echo "Stop schedwi agent daemon"
        ;;

'start')
        if [ -x "$SCHEDWI_INSTALL_DIR/bin/schedwiclnt" ]; then
                "$SCHEDWI_INSTALL_DIR/bin/schedwiclnt" \
                      && echo schedwi agent daemon started
                set_return
        fi
        ;;

'stop')
        pid=`cat "$SCHEDWI_INSTALL_DIR/var/schedwiclnt.pid"`
        if [ "X$pid" != "X" ]; then
                if kill $pid; then
                        echo "schedwi agent daemon stopped"
                else
                        set_return
                        echo "Unable to stop the schedwi agent daemon"
                fi
        fi
        ;;

*)
        echo "usage: $0 {start|stop}"
        ;;
esac

exit $rval

This script, named schedwiclnt, can be installed in /sbin/init.d and links can be created in the startup folders as follow:

ln -s /sbin/init.d/schedwiclnt /sbin/rc3.d/S980schedwiclnt
ln -s /sbin/init.d/schedwiclnt /sbin/rc2.d/K980schedwiclnt
For GNU/Linux Debian
#!/bin/sh

# CHANGE this variable with the schedwiclnt install path
# This path is the one specified by the configure's --prefix option
# during installation.  If no --prefix has been use, the default
# path is /usr/local
SCHEDWI_INSTALL_DIR="/usr/local"
     
test -x "$SCHEDWI_INSTALL_DIR/bin/schedwiclnt" || exit 0

case "$1" in
start)
       echo -n "Starting schedwi agent service: schedwiclnt"
       start-stop-daemon --start --quiet \
         --exec "$SCHEDWI_INSTALL_DIR/bin/schedwiclnt"
       echo "."
       ;;
stop)
       echo -n "Stopping schedwi agent service: schedwiclnt"
       start-stop-daemon --stop --quiet  \
         --pidfile "$SCHEDWI_INSTALL_DIR/var/schedwiclnt.pid" \
         --exec "$SCHEDWI_INSTALL_DIR/bin/schedwiclnt"
       echo "."
       ;;
restart)
       echo -n "Restarting schedwi agent service: schedwiclnt"
       start-stop-daemon --stop --quiet --oknodo \
         --pidfile "$SCHEDWI_INSTALL_DIR/var/schedwiclnt.pid" \
         --exec "$SCHEDWI_INSTALL_DIR/bin/schedwiclnt"
       start-stop-daemon --start --verbose \
         --exec "$SCHEDWI_INSTALL_DIR/bin/schedwiclnt"
       echo "."
       ;;
force-reload|reload)
       echo -n "Reloading configuration of schedwi agent service: schedwiclnt"
       start-stop-daemon --stop --signal 1 --quiet  \
         --pidfile "$SCHEDWI_INSTALL_DIR/var/schedwiclnt.pid" \
         --exec "$SCHEDWI_INSTALL_DIR/bin/schedwiclnt"
       echo "."
       ;;
*)
       echo "Usage: /etc/init.d/schedwiclnt " \
              " {start|stop|restart|reload|force-reload}" >&2
       exit 1
       ;;
esac
     
exit 0

This script, named schedwiclnt, can be installed in /etc/init.d and links can be created in the startup folders as follow:

update-rc.d schedwiclnt defaults
For GNU/Linux Red Hat
#!/bin/sh
#
# schedwiclnt:        Starts the Schedwi agent daemon
#
# chkconfig: 2345 97 03
# description:  This is the agent daemon which receives task requests \
#               from the Schedwi server and runs them on the local host. \
#               When a task is finished, it reports its status back \
#               to te server
#
# processname: schedwiclnt
# pidfile: /usr/local/var/run/schedwiclnt.pid
#

# Sanity checks.
[ -x "/usr/local/bin/schedwiclnt" ] || exit 0

# Source function library.
. /etc/rc.d/init.d/functions

RETVAL=0

start() {
    echo -n $"Starting the Schedwi Agent Daemon: "
    daemon "/usr/local/bin/schedwiclnt"
    RETVAL=$?
    echo
    [ $RETVAL -eq 0 ] && touch /var/lock/subsys/schedwiclnt
}

stop() {
    echo -n $"Stopping the Schedwi Agent Daemon: "
    killproc "/usr/local/bin/schedwiclnt"
    RETVAL=$?
    echo
    if [ $RETVAL -eq 0 ]; then
        rm -f /var/lock/subsys/schedwiclnt
    fi
}

# See how we were called.
case "$1" in
    start)
        start
        ;;
    stop)
        stop
        ;;
    status)
        status schedwiclnt
        RETVAL=$?
        ;;
    restart)
        stop
        start
        ;;
    condrestart)
        if [ -f /var/lock/subsys/schedwiclnt ]; then
            stop
            start
        fi
        ;;
    reload)
        killproc "/usr/local/bin/schedwiclnt" -HUP
        RETVAL=$?
        ;;
    *)
        echo $"Usage: $0 {start|stop|status|restart|condrestart|reload}"
        ;;
esac
exit $RETVAL

This script, named schedwiclnt, can be installed in /etc/init.d and links can be created in the startup folders as follow:

/sbin/chkconfig --add schedwiclnt
For Windows 2000

schedwiclnt on Cygwin can be invoked as a Windows 2000 service. Cygwin has its own cygrunsrv.exe program to define, remove, start, and stop services. The following command can be used to install schedwiclnt as a service:

cygrunsrv.exe --install schedwiclnt   \
              --path /usr/local/bin/schedwiclnt.exe   \
              --args \-f   \
              --desc "Schedwi Agent"   \
              --shutdown

The previous command has been split into several lines to fit in the page. It must be typed on a single line without the \'s.

Enabling SSL

This section describes the steps required to set up SSL for a secure communication between the Schedwi server and its agents.

SSL (Secure Sockets Layer) is a cryptographic protocol that provides secure communications between two hosts. For Schedwi, it can be used for a mutual authentication between the server (schedwisrv) and the agents (schedwiclnt) and for the encryption of the network communications.

SSL can be enabled agent by agent. For instance, local agents, inside the company network, may not require a such security level. However, agents installed outside the company, which use an insecure network like Internet, should be configured to use SSL. Out of the box, schedwiclnt - the agent part of Schedwi - is not configured to use SSL: some configuration steps are required, both on the agent side and on the server side.

Certificate and key files

For each end of the SSL network link, two files are required: a certificate file and a key file. On the server side - schedwisrv - these files have been generated automatically during the installation and they will be used for the SSL communications with all the agents. On the client side however, an additional step is required which needs the GnuTLS's certtool or the openssl command.

With GnuTLS's certtool

The following commands will generate a SSL key file (schedwiclnt.key) and a certificate file (schedwiclnt.crt) on the agent.

Note

These commands may take a very long time to complete (up to 15 minutes)

certtool --generate-privkey --outfile schedwiclnt.key
certtool --generate-self-signed --load-privkey schedwiclnt.key \
         --outfile schedwiclnt.crt

This command will ask a number of questions. The important ones must be be replied as follow:

Common name:

The full hostname (with its domain) of the agent

Does the certificate belong to an authority? (Y/N):

N

Is this a TLS web client certificate? (Y/N):

Y

Is this also a TLS web server certificate? (Y/N):

Y

Enter the dnsName of the subject of the certificate:

The full hostname (with its domain) of the agent

Will the certificate be used for signing (DHE and RSA-EXPORT ciphersuites)? (Y/N):

Y

Will the certificate be used for encryption (RSA ciphersuites)? (Y/N):

Y

Enter the URI of the CRL distribution point:

Leave empty

The value for the Common name and dnsName must be entered with great care: the full hostname must be resolvable on the server by the naming system in used (DNS, /etc/hosts, NIS, ...)

With openssl

The following commands will generate a SSL key file (schedwiclnt.key) and a certificate file (schedwiclnt.crt) on the agent.

openssl genrsa 1024 > schedwiclnt.key
openssl req -new -x509 -nodes -sha1 -days 365 -key schedwiclnt.key > schedwiclnt.crt

The second command will ask a number of questions. The important one is:

Common Name (eg, YOUR name) []:

and must exactly match the hostname of the agent host including its full domain (flower.foo.com for instance). This full name must be resolvable on the server by the naming system in used (DNS, /etc/hosts, NIS, ...)

Install the SSL files on the agent

The two files generated during the previous step (schedwiclnt.key and schedwiclnt.crt) must be moved into the same directory as the Schedwi agent configuration file (usually in /etc)

The key file, schedwiclnt.key, should be protected carefully (using the chown and chmod commands): it must belong to the same user as the schedwiclnt daemon and must only be readable by this user (chmod 600 schedwiclnt.key). For improved security it may be moved to a special directory only accessible to the user running the schedwiclnt daemon.

For the mutual authentication to work between the server and the agent, the certificate file of the server must be copied on the agent, under the /etc directory. On the server, this file can be usually found under the /etc directory with the name schedwisrv.crt (alternatively you can have a look at the SSLServerCertificateFile parameter in the server configuration file to find the full path of this file).

Warning

Only the server certificate file is required. For security reasons it is important not to copy the server key file: it is only required on the server.

The configuration file, schedwiclnt.conf, must then be edited to enable SSL and declare the three new files. The parameters to modify are as follow:

SSLEngine=Y
SSLClientCertificateFile=<full path and name of the schedwiclnt.crt file>
SSLClientCertificateKeyFile=<full path and name of the schedwiclnt.key file>
SSLServerCertificateFile=<full path and name of the schedwisrv.crt file>

A restart of the schedwiclnt daemon is then required for the activation of SSL. During this restart, a look at the log file should ensure that everything is working fine.

Note

The complete start of the schedwiclnt daemon, in particular the initialization of the SSL layer, may take several minutes. During this time, the agent is not yet available. To reduce the starting time, the parameter SSLQuickRandom can be set to Y in the configuration file. However this parameter also reduce the quality of the SSL encryption.

Register the agent certificate on the server

For the mutual SSL authentication, the agent certificate file generated previously under the name schedwiclnt.crt must be loaded in the Schedwi database, on the server.

The first step is then to copy this file on the server, in a temporary directory (/tmp for instance).

Warning

Only the agent certificate file is required (schedwiclnt.crt). For security reasons it is important not to copy the key file: it is only required by the schedwiclnt daemon.

The next step is to load this file into the Schedwi database. This can be achieved in two ways.

Upload the agent certificate file using gschedwi

The graphical interface gschewi can be used to upload the certificate:

  1. From the menu choose Tools->Hosts.

  2. Double-click on the agent name in the list.

  3. Click on the Upload button and navigate to the temporary folder where the certificate file has been copied and select this file.

Upload the agent certificate file using schedwiloadcert

The command line tool schedwiloadcert can also be used to upload the agent certificate file as follow:

schedwiloadcert -a <full_host_name_of_the_agent> schedwiclnt.crt

See the section called “Using the schedwiloadcert program” for more details.

Test the SSL connection between the server and the agent

The schedwiping tool on the server can be used to check that the SSL configuration on both the agent and the server is correct:

schedwiping <full_host_name_of_the_agent>

The following reply means that everything is working as expected:

The agent v0.1.1 is running.

See the section called “Using the schedwiping program” for more details.

Advanced configuration

Most of the time, tasks will have to be run under different accounts. For instance a task may backup a database into a file. The database administrator account dba must be used for this operation. A second task must then copy this file to a tape for external storage. This task needs to be run under the backup administrator account - say bkpadm - which has write access to the tape drive.

To be able to run tasks for several users like this, the schedwiclnt daemon must be run under the system administrator account (i.e. root on Unix systems). This may be a security issue as the client will be able to run as a privileged user any commands received from the server: the ones sent by the Schedwi server daemon but also the ones sent by a malicious user connected to the server (or using a server pretending to be the Schedwi server).

The recommended solution to this issue is to use the GnuTLS enabled client. Using GnuTLS the client and the server authentify to each other before running any command. Moreover, the communication between them is encrypted. Using this method, the client is sure that the commands are issued by the Schedwi server.

An other solution is not to run the schedwiclnt daemon under the system administrator account but to run several daemons, one for each user account. Using this method, the daemons have no special privileges. However, each daemon must use a separate configuration file (using the -c option) and a separate TCP port.

Note

On most operating systems, schedwiclnt will not be allowed to use port numbers below 1024 if not run as root.

On the server side, the client host must be defined several times with the different TCP ports. The tasks must then be associated with the correct host/port.

In our previous example, two daemons will be running, one under the dba account and an other one under the bkpadm account. The configuration file for the daemon running under the dba account will be /home/dba/schedwiclnt_dba.conf:

AGENT_PORT=3001
SERVER=cherry.foo.com
SERVER_PORT=2005
LOG_FILE=/home/dba/schedwiclnt.log
PID_FILE=/home/dba/schedwiclnt.pid
RESULT_DIR=/home/dba/schedwiclnt_result
SSLEngine=N

schedwiclnt will then be started under the dba account by the following command:

bash$ schedwiclnt -c /home/dba/schedwiclnt_dba.conf 

For the daemon to be started with the bkpadm account the configuration file will be /home/bkpadm/schedwiclnt_bkpadm.conf:

AGENT_PORT=3002
SERVER=cherry.foo.com
SERVER_PORT=2005
LOG_FILE=/home/bkpadm/schedwiclnt.log
PID_FILE=/home/bkpadm/schedwiclnt.pid
RESULT_DIR=/home/bkpadm/schedwiclnt_result
SSLEngine=N

And the start command will be (under bkpadm):

bash$ schedwiclnt -c /home/bkpadm/schedwiclnt_bkpadm.conf 

The server

Introduction

The server part of Schedwi must be installed and configured on a single computer. It is composed of two parts:

  • The schedwisrv daemon which must be running at all time to schedule the jobs and request their execution on the agents.

  • The MySQL database which contains all the parameters required by the schedwisrv. For instance the jobs, the jobsets and the associated commands are all defined in this database. The Schedwi graphical user interface allows administrators to defined all those parameters.

    The installation of the MySQL Database System is beyond the scope of this manual. Please refer to the official MySQL documentation (visit the MySQL Web Site) or use a pre-packaged installation for your operating system.

Note

The schedwisrv daemon and the MySQL database do not have to be installed on the same computer.

The schedwiping, schedwiloadcert and schedwidbchecks commands are also part of the Schedwi server. schedwiping allows the administrator to test the connection with the agents. schedwiloadcert is used to load agent SSL certificates in the database. schedwidbchecks can be used to detect inconsistencies in the database and to repair them.

Installation

Requirements

The following components are required for compilation:

  • A C compiler.

  • GnuTLS (visit the GnuTLS Web Site for more information) version 1.3.1. or above. The GnuTLS certtool -v command can be used to check the installed version.

    On some systems, pre-packaged versions are provided. You have to install the libraries, the command line tools and, for the compilation, the development packages (usually gnutls-utils, gnutls-bin, libgnutls13, libgnutls-dev or gnutls-devel)

  • The MySQL libraries version 4.1.1 or above (visit the MySQL Web Site for more information).

The compilation process uses the Automake and Autoconf system.

Compilation and Installation

The following steps describe how to compile and install schedwisrv, schedwiping, schedwiloadcert and schedwidbchecks:

  1. Download the Schedwi server in a temporary directory.

  2. Compile with the following commands (you don't need to be root except for the make install part):

    gunzip -c schedwisrv-0.1.1.tar.gz | tar xf -
    cd schedwisrv-0.1.1
    ./configure --with-libgnutls-prefix=/usr/local/gnutls \
                --with-hostname=bee.foo.com
    make
    su root
    make install
    

    The --with-libgnutls-prefix=/usr/local/gnutls option specifies the path to the GnuTLS installation directory. This parameter is optional if GnuTLS is installed in a directory known by the system.

    The --with-hostname=bee.foo.com parameter specifies the fully-qualified domain name (FQDN) of the current system. This is required to generate the GnuTLS certificate at the end of the make command.

configure parameters

configure supports more parameters than the ones described in the previous sections. A complete list can be obtain with configure -h.

The most common one is --prefix=path used to specify the installation directory (/usr/local by default)

MySQL database creation

The Schedwi server requires a MySQL database. The installation of the MySQL Database System is not described in this manual. Visit the MySQL Web Site for installation details. You can also use pre-packaged installations provided for you operating system.

Once the MySQL Database System is installed and running, the following steps can then be undertaken:

  1. The creation if a Schedwi dedicated database. This can be achieved with the following command:

    mysqladmin --user=root --password=root_password create schedwidb

    The --user=root option specifies a MySQL user which is allowed to create databases.

    The associated password is provided with the --password=root_password option.

    The schedwidb parameter is the name given to the new database. Any name can be used.

  2. The creation of a MySQL user with full rights on the Schedwi database. For example, the following commands create the user schedwi with the password schedwi_password:

    mysql --user=root --password=root_password
    mysql> GRANT ALL PRIVILEGES ON schedwidb.*
    mysql> TO schedwi@localhost
    mysql> IDENTIFIED BY 'schedwi_password';
    mysql> quit
    

    Any user name can be chosen.

    The localhost parameter specifies that only connections to the database from the local host will be allowed. If the Schedwi server is not installed on the same host as the database, the host name parameter must be changed accordingly.

  3. Load of the Schedwi schema and initial data. This is done by the use of the provided schedwi_mysql.sql SQL script under the sql directory in the Schedwi server archive. This script must be run from this directory as follow:

    cd schedwisrv-0.1.1/sql
    mysql --user=schedwi \
                   --password=schedwi_password schedwidb < schedwi_mysql.sql
    

    The --user=schedwi, --password=schedwi_password and schedwidb options must obviously be set according to the values chosen in the previous steps.

Configuration

Configuration file location and syntax

All the configuration parameters are grouped in a single configuration file. By default, this file is named schedwisrv.conf and is located in the /usr/local/etc directory.

Note

If configure has been run with the --prefix=path option during the installation (see the section called “configure parameters”), the default directory of the configuration file is relative to the provided path. For instance, with configure --prefix=/apps, the configuration file will be /apps/etc/schedwisrv.conf.

Tip

Run schedwisrv with the -h parameter. The path of the default configuration file is provided near the end.

However, the configuration file name and path can be specified at run-time using the -c configuration_file option of schedwisrv.

The format of the file is straightforward:

  • Each parameter is defined on a line by itself. The parameter name and its value are separated by the equal (=) sign. The continuation sign \ used to define a parameter on several lines is not allowed.

  • Empty lines are ignored.

  • Lines starting by # or ; are comments and are ignored. Comments must be on lines by themselves; they cannot follow a parameter definition.

Finally, the syntax of the configuration file can be tested with the -t option of schedwisrv. With this option, schedwisrv just tests the syntax and exits.

Global Configuration parameters

Note

All the file paths specified in this section are the default ones. However, if configure has been used run the --prefix=path option during the installation (see the section called “configure parameters”), the default paths are relative to the provided path.

USER

User ID as which the schedwisrv daemon will run. For the process to be able to change its user ID, it must be initially started as root.

A name (in /etc/passwd) or a number are allowed.

By default, the server will not change to an other user and will continue running with the original one.

GROUP

Group ID as which the schedwisrv daemon will run. For the process to be able to change its group ID, it must be initially started as root.

A name (in /etc/group) or a number are allowed.

By default, the server will not change to an other group and will continue running with the original one.

LOG_FILE

Path and name of the log file. This file is only used if the SYSLOG directive (see below) is not set.

LOG_FILE=/usr/local/var/log/schedwisrv.log by default.

SYSLOG

Specifies that the syslog mechanism must be used to log messages. If this directive is set, LOG_FILE is ignored. The provided parameter is the syslog facility to use (LOG_USER, LOG_LOCAL5, ...). See your syslog(3) manual page for a complete list of values.

No default value.

DATE_FORMAT

The date format for the date and time field in the log file. This value is only used if the SYSLOG directive is not set. See your strftime(3) manual page for a format description.

For example: DATE_FORMAT=%Y%m%d - %H%M%S

DATE_FORMAT=%c by default.

PID_FILE

Path and name of the file that will be used to store the process ID of the schedwisrv daemon. This file is used by the schedwisrv program at startup to be sure that an other instance is not already running. This file may also be used by your scripts, to stop the schedwisrv daemon for instance.

PID_FILE=/usr/local/var/run/schedwisrv.pid by default.

WORKLOAD_PURGE_COMPLETED

Number of days to keep the completed workloads in the database.

WORKLOAD_PURGE_COMPLETED=5 by default.

WORKLOAD_PURGE_FAILED

Number of days to keep the failed or still running workloads in the database.

WORKLOAD_PURGE_FAILED=7 by default.

SERVER_PORT

Network TCP port number used by the Schedwi server to listen to clients. A name defined in /etc/services can also be used.

SERVER_PORT=2005 by default.

IFACE_LISTEN

On a multihomed host (several IP addresses and/or network cards), IFACE_LISTEN specifies on which interface schedwisrv must listen to the agents. A host name or an IP address in numbers-and-dots notation can be used.

For example: IFACE_LISTEN=bee.foo.com

By default schedwisrv will listen to all available network interfaces.

SSLServerCertificateFile

PEM-encoded certificate file name for the server. A such file has been generated and installed for you during the schedwisrv built steps. This file must be copied on each agent.

SSLServerCertificateFile=/usr/local/etc/schedwisrv.crt by default.

SSLServerCertificateKeyFile

PEM-encoded private key file for the server. A such file has been generated and installed for you during the schedwisrv built steps.

This private key cannot be an encrypted one.

SSLServerCertificateKeyFile=/usr/local/etc/schedwisrv.key by default.

Important

The private key file defined by this directive must not be copied on the agents and must be protected. Use the chmod and chown commands to only allow access to this file and to its directory to the user running the schedwisrv daemon.

SSLQuickRandom

At startup, schedwisrv initializes the SSL network layer. This step requires good quality random numbers which are retrieved from the operating system. On some systems this may take a long time (up to 10 minutes). During this time, schedwisrv is not yet available and working.

SSLQuickRandom can be used to speed up this startup time by using less good quality random numbers and therefore reducing encryption quality.

SSLQuickRandom=0 by default.

Database Configuration parameters

The following configuration parameters allow the Schedwi server to access the MySQL database. They are all optional. If not set, the schedwisrv daemon will try to retrieve them from the MySQL option files (my.ini, my.cnf, ... in the default MySQL location) using the [schedwisrv] group. Here is a sample of a such group:

[schedwisrv]
      host=localhost
      user=schedwi
      password=schedwi_password
      database=schedwidb
      port=3306
      socket=/tmp/mysql.sock

Note

The .my.cnf configuration file in the home directory of the current user is ignored and cannot be used.

DB_HOST

Database server. A name or an IP address in numbers-and-dots notation can be used.

DB_HOST=localhost by default.

DB_USER

Database login name.

By default the current Unix login name.

DB_PASSWD

Password for the database login name specified by the DB_USER parameter.

No password by default.

DB_DATABASE

Database name.

There is no default value for this parameter. If not set here, the schedwisrv daemon will try to get it from the MySQL option file.

DB_PORT

TCP port number for the connection to the database. Only a number is allowed.

There is no default value for this parameter. If the DB_HOST directive is set to localhost, the connection will rather use a Unix socket (see the DB_UNIXSOCKET directive).

DB_UNIXSOCKET

Socket or named pipe that should be used for the connection to the local database.

There is no default value for this parameter. If the DB_HOST directive is set to something different from localhost, a TCP/IP port will rather be used for this connection (see the DB_PORT directive).

Modules Configuration parameters

Modules (or plug-ins) can be used to extend the capabilities of the Schedwi server. Such plug-ins are called in two places:

  • when the status of a job or jobset changes. This can be used for example to report failed jobs to a centralized monitoring system such Nagios.

  • when a job or jobset is ready to start. This can be used to check for external constraints and to block the job until such contraints are resolved.

Out of the box, Schedwi is provided with one module, mod_shell, which can be used to run external scripts or commands. Also, sample scripts to be used by this module include mod_shell_mail.sh to send e-mails whenever the status of a job changes, mod_shell_snmp.sh to send snmp traps and mod_shell_nagios.sh to report status changes to a Nagios Monitoring server.

A module skeleton is provided in the doc directory under the Schedwi server archive (mod_example.c). Alternatively, the mod_exec.c file is a good example.

The following configuration file parameters are related to the module management:

MODULE_DIR

Search directory for the modules. When a module to load (see below the MODULE_LOAD directive) is provided without its path, it is searched in this directory. This directive can be repeated several times to define more search directories.

MODULE_DIR=/usr/local/lib/schedwisrv by default.

MODULE_LOAD

Specifies the name of a module to load. If the full path to the module file is not provided, the module is searched in the directories defined by the MODULE_DIR directives. The extension (.la, .so, ...) can be omitted. MODULE_LOAD can be used several times to load several modules.

For example: MODULE_LOAD=mod_shell

MODULE:module_name:module_directive

This special directive is used to transmit configuration parameters to modules. module_name is the module name as defined by the MODULE_LOAD directive (without the path and the extension). module_directive is a parameter name known from the module. See the specific module documentation to get a list of these parameters.

For example: MODULE:mod_shell:CMD_STATUS=/usr/local/libexec/mod_shell_mail.sh

Running the server

Starting

To start the Schedwi server daemon simply run the schedwisrv command. This program goes automatically in the background. If your PATH environment variable does not contain the path to the schedwisrv command, the full path must be specified. For example:

bash# /usr/local/bin/schedwisrv 

Important

The schedwisrv daemon does not need to be run as the root user. For security reasons it is then highly recommended to use an unprivileged user account by defining the USER and GROUP directives in the configuration file (see the section called “Global Configuration parameters” for details).

schedwisrv records information in a log file (or in the syslog mechanism - see the section called “Global Configuration parameters”). In case of failure to start the server, this file may contain precious information on the error.

Stopping

To stop the server, simply send the TERM signal (number 15) to the schedwisrv process. The process identification of this daemon is stored in the file defined by the PID_FILE configuration directive.

Important

Never send the KILL signal (number 9) to the daemon. This signal does not allow the schedwisrv daemon to stop in a clean state.

Reloading the configuration file

Changes to the configuration file whilst the schedwisrv daemon is running are not automatically taken into account. A stop and a restart of the process will allow it to re-read its configuration file.

For minor changes, concerning the log file path or date format for instance, it may be easier to send the HUP signal (number 1) to the schedwisrv daemon. This signal force the process to re-read its configuration file without having to be stopped. Moreover, this signal can be used to rotate the log file as schedwisrv will close it and reopen a new one.

Important

If schedwisrv finds an error while reading its configuration file, it stops immediately. Therefore, before sending the HUP signal it is important to be sure that the configuration file is error free. This check can be done by running the schedwisrv command with the -t option. With this option, schedwisrv simply checks the configuration file and exits; it does not interfere with the running schedwisrv daemon.

Sample startup scripts

These sample startup scripts start the Schedwi server daemon as root (it is highly recommended to use the USER and GROUP directives in the configuration file to use an unprivileged user account).

Note

All the following scripts are available under the scripts directory in the Schedwi server archive. A logrotate sample file is also provided for the rotation of the log file (see the logrotate(8) manual page for more details) as well as an OCF Resource Agent script for Linux-HA.

For Sun
#!/sbin/sh

# CHANGE this variable with the schedwisrv install path
# This path is the one specified by the configure's --prefix option
# during installation.  If no --prefix has been use, the default
# path is /usr/local
SCHEDWI_INSTALL_DIR="/usr/local"

case "$1" in
'start')
        if [ -x "$SCHEDWI_INSTALL_DIR/bin/schedwisrv" ]; then
                "$SCHEDWI_INSTALL_DIR/bin/schedwisrv"
        fi
        ;;

'stop')
        /usr/bin/pkill -u 0 -P 1 schedwisrv
        ;;

*)
        echo "Usage: $0 { start | stop }"
        exit 1
        ;;
esac
exit 0

This script, named schedwisrv, can be installed in /etc/init.d and links can be created in the startup folders as follow:

ln /etc/init.d/schedwisrv /etc/rc3.d/S90schedwisrv
ln /etc/init.d/schedwisrv /etc/rc0.d/K90schedwisrv
ln /etc/init.d/schedwisrv /etc/rc1.d/K90schedwisrv
ln /etc/init.d/schedwisrv /etc/rc2.d/K90schedwisrv
ln /etc/init.d/schedwisrv /etc/rcS.d/K90schedwisrv
For HP-UX
#!/sbin/sh

#
# Start schedwisrv
#

# CHANGE this variable with the schedwisrv install path
# This path is the one specified by the configure's --prefix option
# during installation.  If no --prefix has been use, the default
# path is /usr/local
SCHEDWI_INSTALL_DIR="/usr/local"


PATH=/sbin:/usr/sbin:/usr/bin
export PATH

rval=0
set_return() {
        x=$?
        if [ $x -ne 0 ]; then
                echo "ERROR CODE $x"
                rval=1
        fi
}

case $1 in
start_msg)
        echo "Start schedwi server daemon"
        ;;

stop_msg)
        echo "Stop schedwi server daemon"
        ;;

'start')
        if [ -x "$SCHEDWI_INSTALL_DIR/bin/schedwisrv" ]; then
                "$SCHEDWI_INSTALL_DIR/bin/schedwisrv" \
                      && echo schedwi server daemon started
                set_return
        fi
        ;;

'stop')
        pid=`cat "$SCHEDWI_INSTALL_DIR/var/schedwisrv.pid"`
        if [ "X$pid" != "X" ]; then
                if kill $pid; then
                        echo "schedwi server daemon stopped"
                else
                        set_return
                        echo "Unable to stop the schedwi server daemon"
                fi
        fi
        ;;

*)
        echo "usage: $0 {start|stop}"
        ;;
esac

exit $rval

This script, named schedwisrv, can be installed in /sbin/init.d and links can be created in the startup folders as follow:

ln -s /sbin/init.d/schedwisrv /sbin/rc3.d/S980schedwisrv
ln -s /sbin/init.d/schedwisrv /sbin/rc2.d/K980schedwisrv
For GNU/Linux Debian
#!/bin/sh

# CHANGE this variable with the schedwisrv install path
# This path is the one specified by the configure's --prefix option
# during installation.  If no --prefix has been use, the default
# path is /usr/local
SCHEDWI_INSTALL_DIR="/usr/local"
     
test -x "$SCHEDWI_INSTALL_DIR/bin/schedwisrv" || exit 0

case "$1" in
start)
       echo -n "Starting schedwi server service: schedwisrv"
       start-stop-daemon --start --quiet \
         --exec "$SCHEDWI_INSTALL_DIR/bin/schedwisrv"
       echo "."
       ;;
stop)
       echo -n "Stopping schedwi server service: schedwisrv"
       start-stop-daemon --stop --quiet  \
         --pidfile "$SCHEDWI_INSTALL_DIR/var/schedwisrv.pid" \
         --exec "$SCHEDWI_INSTALL_DIR/bin/schedwisrv"
       echo "."
       ;;
restart)
       echo -n "Restarting schedwi server service: schedwisrv"
       start-stop-daemon --stop --quiet --oknodo \
         --pidfile "$SCHEDWI_INSTALL_DIR/var/schedwisrv.pid" \
         --exec "$SCHEDWI_INSTALL_DIR/bin/schedwisrv"
       start-stop-daemon --start --verbose \
         --exec "$SCHEDWI_INSTALL_DIR/bin/schedwisrv"
       echo "."
       ;;
force-reload|reload)
       echo -n "Reloading configuration of schedwi server service: schedwisrv"
       start-stop-daemon --stop --signal 1 --quiet  \
         --pidfile "$SCHEDWI_INSTALL_DIR/var/schedwisrv.pid" \
         --exec "$SCHEDWI_INSTALL_DIR/bin/schedwisrv"
       echo "."
       ;;
*)
       echo "Usage: /etc/init.d/schedwisrv " \
              " {start|stop|restart|reload|force-reload}" >&2
       exit 1
       ;;
esac
     
exit 0

This script, named schedwisrv, can be installed in /etc/init.d and links can be created in the startup folders as follow:

update-rc.d schedwisrv defaults
For GNU/Linux Red Hat
#!/bin/sh
#
# schedwisrv:        Starts the Schedwi server daemon
#
# chkconfig: 2345 97 03
# description:  This is the server daemon which schedules the tasks and \
#               submits them to the clients.  The execution of a task \
#               can be triggered by date and time but also by the \
#               result of a previous task or by the existence of a file \
#               on a remote client (useful when a task must process a \
#               file generated by a previous task)
#
# processname: schedwisrv
# pidfile: /usr/local/var/run/schedwisrv.pid
#

# Sanity checks.
[ -x "/usr/local/bin/schedwisrv" ] || exit 0

# Source function library.
. /etc/rc.d/init.d/functions

RETVAL=0

start() {
    echo -n $"Starting the Schedwi Server Daemon: "
    daemon "/usr/local/bin/schedwisrv"
    RETVAL=$?
    echo
    [ $RETVAL -eq 0 ] && touch /var/lock/subsys/schedwisrv
}

stop() {
    echo -n $"Stopping the Schedwi Server Daemon: "
    killproc "/usr/local/bin/schedwisrv"
    RETVAL=$?
    echo
    if [ $RETVAL -eq 0 ]; then
        rm -f /var/lock/subsys/schedwisrv
    fi
}

# See how we were called.
case "$1" in
    start)
        start
        ;;
    stop)
        stop
        ;;
    status)
        status schedwisrv
        RETVAL=$?
        ;;
    restart)
        stop
        start
        ;;
    condrestart)
        if [ -f /var/lock/subsys/schedwisrv ]; then
            stop
            start
        fi
        ;;
    reload)
        killproc "/usr/local/bin/schedwisrv" -HUP
        RETVAL=$?
        ;;
    *)
        echo $"Usage: $0 {start|stop|status|restart|condrestart|reload}"
        ;;
esac
exit $RETVAL

This script, named schedwisrv, can be installed in /etc/init.d and links can be created in the startup folders as follow:

/sbin/chkconfig --add schedwisrv

Using the schedwiping program

The schedwiping diagnostic tool is part of the Schedwi server and is installed along the schedwisrv program. As its name suggests (from the ping network tool), it allows to test the connection with the agents and ensure that the network and Schedwi configuration is right on both side.

To use the tool simply run it with the agent host name to test in parameter. For instance :

bash# /usr/local/bin/schedwiping flower.foo.com 
The agent v0.1.1 is running.

Tip

Run schedwiping with the -h parameter to display the command help message.

schedwiping must be run on the same host as the server as it needs the same configuration file (by default /usr/local/etc/schedwisrv.conf) and uses the same MySQL database to retrieve agent details (such as the agent TCP port number or whether SSL must be used).

Using the schedwiloadcert program

schedwiloadcert is part of the Schedwi server. This tool can be used to upload a provided agent SSL certificate file in the database. If the agent is already defined in the database, it is updated with the new parameters. Otherwise it is created. schedwiloadcert accepts a few command line parameters. All are optional, except for the SSL certificate file name, and can be used to overwrite some default values. For example, the -p option defines the agent TCP port (2006 by default). The -d option provides a description of the new agent. You can use the -h option to get a complete list of parameters.

By default, the agent host name is retrieved from the SSL certificate itself (from the Alternate Name field or the Common Name field). An other name can be specified with the -a option. In this case, the -f option may need to be used to force schedwiloadcert to ignore discrepancy between the two values.

Warning

Do not use the -a option unless you really know what you are doing. A wrong host name may prevent the SSL connection establishment between the server and the agent.

The Schedwi graphical user interface can also be used to define the agent and its SSL certificate.

Using the schedwidbchecks program

schedwidbchecks is part of the Schedwi server. This tool can be used to detect Schedwi objects inconsistencies in the database. If asked, it can try to fix them. schedwidbchecks accepts a few command line parameters. All are optional. The complete list can be obtain with the -h parameter. One interesting parameter is the -f one. It can be used to fix the database when inconsistencies have been detected by a previous run of schedwidbchecks (without this parameter). schedwidbchecks should be run from time to time, or when a database issue is suspected.

Schedwi and firewalls

Firewall systems must be configured to allow the communication between the Schedwi server and its agents. Two TCP network streams are used:

About Schedwi

Schedwi was written by Herve Quatremain (). To find more information about Schedwi, please visit the Schedwi Web page.

To report a bug or make a suggestion regarding this application or this manual, follow the directions in this document.

This program is distributed under the terms of the GNU General Public license as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version. A copy of this license can be found at this link, or in the file COPYING included with the source code of this program.