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.
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.
Compile schedwiclnt with the following commands (you don't need to be
root
except for the makeinstall
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.
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.
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.
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. |
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 used with the
|
Tip | |
---|---|
Run schedwiclnt with the
|
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.
Note | |
---|---|
All the file paths specified in this section are the default ones. However, if
configure has been used with the
|
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 asroot
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.
Note | |
---|---|
All the file paths specified in this section are the default ones. However, if
configure has been used with the
|
SSLEngine
Toggles the usage of the SSL Protocol Engine for all network communications. Use
Y
to enable SSL orN
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.
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 |
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.
Important | |
---|---|
Never send the |
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
|
These sample startup scripts start the Schedwi client daemon as
root
.
Note | |
---|---|
All the following scripts are available under the
|
#!/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.
Note | |
---|---|
On most operating systems, schedwiclnt will not be allowed
to use port numbers below 1024 if not run as
|
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.
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.
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 makeinstall
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 passwordschedwi_password
:mysql
--user=
root
--password=
root_password
mysql>
GRANT ALL PRIVILEGES ONschedwidb
.*mysql>
TOschedwi
@localhost
mysql>
IDENTIFIED BY 'schedwi_password
';mysql>
quitAny 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 thesql
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.sqlThe
--user=
,schedwi
--password=
andschedwi_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.
Note | |
---|---|
If configure has been used with the
|
Tip | |
---|---|
Run schedwisrv with the
|
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.
Note | |
---|---|
All the file paths specified in this section are the default ones. However, if
configure has been used with the
|
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 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
Note | |
---|---|
The |
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 tolocalhost
, the connection will rather use a Unix socket (see theDB_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 fromlocalhost
, a TCP/IP port will rather be used for this connection (see theDB_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
Important | |
---|---|
The schedwisrv daemon does not need to be run as the
|
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.
Important | |
---|---|
Never send the |
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 |
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
|
#!/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.
Tip | |
---|---|
Run schedwiping with the
|
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.
Warning | |
---|---|
Do not use the |
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
(<[email protected]>
). 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.