homecontact us

Schedwi Manual V0.1.0

Herve Quatremain

This manual describes version 0.1.0 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.0January 2007

Herve Quatremain

GNOME Documentation Project


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, on systems that support it, communications with the server can be secured using SSL.

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 communication with the server must be secured (recommended).

    The GnuTLS version required is at least the 1.3.1. (use the certtool -v GnuTLS 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]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.0.tar.gz | tar xf -
    cd schedwiclnt-0.1.0
    ./configure --enable-ssl \
                --with-libgnutls-prefix=/usr/local/gnutls \
                --with-hostname=flower.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. In this case, the --enable-ssl parameter is even optional as by default configure will try to detect your GnuTLS installation.

    The --with-hostname=flower.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.

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]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.0.tar.gz | tar xf -
    cd schedwiclnt-0.1.0
    ./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 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.0.tar.gz | tar xf -
cd schedwiclnt-0.1.0
./configure --without-gnutls
make
make check
su root
make install

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

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

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

1 test was successful.
[Note]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]Note

If configure has been used 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]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]Note

All the file paths specified in this section are the default ones. However, if configure has been used 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/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/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 (ie. 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/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]Note

All the file paths specified in this section are the default ones. However, if configure has been used 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]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.

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]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]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]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]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).

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 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 in several lines to fit in the page. It must be typed on a single line without the \'s.

Advanced configuration

Most of the time, tasks will have to be run under different accounts. For instance a task may backup a database to a file. For this operation the database administrator account dba must be used. 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]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]Note

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

The schedwiping and schedwiloadcert 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.

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 certtool -v GnuTLS 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 librairies 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 Installaton

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

  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.0.tar.gz | tar xf -
    cd schedwisrv-0.1.0
    ./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.0/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]Note

If configure has been used 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]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]Note

All the file paths specified in this section are the default ones. However, if configure has been used with 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/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/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]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.

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]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).

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]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]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]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]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).

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

Using the schedwiping program

The schedwiping diagnostic tool is part of 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.0 is running.
[Tip]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 (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 certificat 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 optionnal, except 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 discrepency between the two values.

[Warning]Warning

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

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

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 2 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.