This manual describes version 0.1.0 of Schedwi.
Copyright © 2007 Herve Quatremain
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:
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
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.0 | January 2007 |
GNOME Documentation Project |
Table of Contents
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 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.
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.
The following steps describe how to compile and install schedwiclnt with GnuTLS support:
Download the Schedwi agent in a temporary directory.
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.
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
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 /usr/local/gnutls
--enable-ssl
parameter is even optional as by default configure will try to detect your
GnuTLS installation.
The --with-hostname=
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.flower.foo.com
The following steps describe how to compile and install schedwiclnt without GnuTLS support - for instance if the operating system does not support it:
Download the Schedwi agent in a temporary directory.
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.
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 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=
used
to specify the installation directory (path
/usr/local
by
default)
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.
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.
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.
If configure has been used with the
--prefix=
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 path
--prefix=/apps
, the
configuration file will be /apps/etc/schedwiclnt.conf
.
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
option of
schedwiclnt.configuration_file
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.
All the file paths specified in this section are the default ones. However, if
configure has been used with the
--prefix=
option during the installation
(see the section called “configure parameters”), the default paths are
relative to the provided path.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.
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.
All the file paths specified in this section are the default ones. However, if
configure has been used with the
--prefix=
option during the installation
(see the section called “configure parameters”), the default paths are
relative to the provided path.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.
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.
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
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.
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.
Never send the KILL
signal (number 9) to the daemon. This
signal does not allow the schedwiclnt daemon to stop in a
clean state.
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.
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.
These sample startup scripts start the Schedwi client daemon as
root
.
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).
#!/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
#!/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
#!/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
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.
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.
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 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.
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.
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.
The following steps describe how to compile and install schedwisrv, schedwiping and schedwiloadcert:
Download the Schedwi server in a temporary directory.
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
option specifies the path to the GnuTLS installation
directory. This parameter is optional if GnuTLS is installed
in a directory known by the system./usr/local/gnutls
The --with-hostname=
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.bee.foo.com
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=
used
to specify the installation directory (path
/usr/local
by
default)
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:
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=
option specifies a
MySQL user which is allowed to create databases.root
The associated password is provided with the
--password=
option.root_password
The
parameter is the name given to the new database. Any name can be used.schedwidb
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 ONschedwidb
.*mysql>
TOschedwi
@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.
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=
and
schedwi_password
options
must obviously be set according to the values chosen in the previous steps.schedwidb
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.
If configure has been used with the
--prefix=
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 path
--prefix=/apps
, the
configuration file will be /apps/etc/schedwisrv.conf
.
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
option of
schedwisrv.configuration_file
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.
All the file paths specified in this section are the default ones. However, if
configure has been used with the
--prefix=
option during the installation
(see the section called “configure parameters”), the default paths are
relative to the provided path.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.
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.
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
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).
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
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.
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.
Never send the KILL
signal (number 9) to the daemon. This
signal does not allow the schedwisrv daemon to stop in a
clean state.
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.
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.
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).
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).
#!/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
#!/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
#!/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
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.
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).
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.
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.
Firewall systems must be configured to allow the communication between the Schedwi server and its agents. Two TCP network streams are used:
From the Schedwi server to the agents. The TCP ports used are the ones
defined by the AGENT_PORT
directive in the configuration file on
each agent (see the section called “Basic configuration parameters”).
By default 2006.
From the agents to the server. The only TCP port used is defined by the
SERVER_PORT
directive in the server configuration file
(see the section called “Global Configuration parameters”).
By default 2005.
Schedwi was written by Herve Quatremain
(<rv4m@yahoo.co.uk>
). 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.