Schedwi Manual V0.1.3

Herve Quatremain

  

This manual describes version 0.1.3 of Schedwi.

Copyright © 2007-2011 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:

  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.3November 2011

Herve Quatremain

GNOME Documentation Project

Table of Contents

Introduction
The agent
Introduction
Installation
Configuration
Running the agent
Enabling SSL
Advanced configuration
The server
Introduction
Installation
Configuration
Running the server
Using the schedwiping program
Using the schedwica program
Using the schedwidbchecks program
The command-line program
Installation and configuration
Usage
Schedwi firewalls and security
About Schedwi

Introduction

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

  • The server schedules the tasks and submits them to the agents. 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 agent (useful when a task must process a file generated by a previous task).

  • The agents (or clients) 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 agent

Introduction

The agent part of Schedwi must be installed and configured on all the computers on which tasks have to be run. schedwiclnt, the agent 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, schedwiclnt can be started using this account.

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

Installation

Requirements

The following components are required for compilation:

  • A C compiler.

  • GnuTLS (visit the GnuTLS Web Site for more information) if the operating system supports it and you want a secure communication with the server (recommended).

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

    On some systems, pre-packaged versions are provided. You will have to install the libraries and, for the compilation, the development packages (usually gnutls, libgnutls26, libgnutls-dev or gnutls-devel)

The compilation process uses the Automake and Autoconf system.

With GnuTLS

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

  1. Download the Schedwi agent in a temporary directory.

    Note

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

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

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

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

Without GnuTLS

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

  1. Download the Schedwi agent in a temporary directory.

    Note

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

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

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

configure parameters

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

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

Validation test suite

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

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

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

## ------------------------------------------ ##
## schedwiclnt 0.1.3 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 fails.

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

Configuration

Configuration file location and syntax

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

Note

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

Tip

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

Also, 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 checked with the -t option of schedwiclnt. With this option, schedwiclnt just tests the syntax and exits.

Basic configuration parameters

Note

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

LOG_FILE

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

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

SYSLOG

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

No default value.

DATE_FORMAT

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

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

DATE_FORMAT=%c by default.

PID_FILE

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

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

SERVER

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

If SSL is used, this server name must match the one in the server certificate (so it's best to use the fully qualified name - FQDN).

For IPv6 you may need to use the address%scope-id notation for specifying the IPv6 scope-ID: fe80::211:d8af:f19e:7ae4%eth0.

For example: SERVER=cherry.foo.com

SERVER=localhost by default.

SERVER_PORT

Network TCP port number used by the Schedwi server to listen to agents. 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.

REGISTRAR_PORT

Network TCP port number used by the schedwireg daemon to listen to agents for the registration process. A name defined in /etc/services can also be used.

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

REGISTRAR_PORT=2004 by default.

ALLOW_FROM

Allow access based on the host name, or host address, of the server. This directive may be used if the Schedwi server is known by several addresses (if it's clustered by instance).

ALLOW_FROM accepts a list of addresses or host names separated by a comma: 192.168.0.1, 127.0.0.0/8, fe80::211:d8af:f19e:7ae4, schedwisrv.your.organization.com, 172.24.0.*

Addresses can be prefixed with ! to explicitly deny access. Denies have precedence on allow rules. For instance, the following rule allows access only from the hosts in the 192.168.0.0/24 network but except 192.168.0.1 which is denied: 192.168.0.0/24, !192.168.0.1

Also, notice that the TCP Wrappers can be used to filter the access to the Schedwi agent. See your hosts_access(5) manual page for more details.

The same value as SERVER by default.

AGENT_PORT

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

AGENT_PORT=2006 by default.

ADDRESS_FAMILY

Specifies which address family should be used. Valid arguments are any, inet (use IPv4 only) or inet6 (use IPv6 only).

any 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 (v4 or v6) in numbers-and-dots notation can be used.

For IPv6 you may need to use the address%scope-id notation for specifying the IPv6 scope-ID: fe80::211:d8af:f19e:7b41%eth0.

For example: IFACE_LISTEN=flower.foo.com

By default schedwiclnt will listen to all available network interfaces.

RESULT_DIR

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

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

RESULT_PREFIX

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

RESULT_PREFIX=job_ by default.

RESULT_SUFFIX

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

Nothing by default.

SSL configuration parameters

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

Note

All the file paths specified in this section are the default ones. However, if configure has been run with the --prefix=path option during the installation (see the section called “configure parameters”), the 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=N by default.

SSLCertificateFile

PEM-encoded certificate file name for the agent. A such file is build the first time the schedwiclnt daemon is started.

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

SSLCertificateKeyFile

PEM-encoded private key file for the agent. A such file is generated for you the first time the schedwiclnt daemon is started.

This private key cannot be encrypted.

SSLCertificateKeyFile=/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.

SSLCACertificateFile

PEM-encoded certificate file name for the server. This file is retrieved from the server the first time the schedwiclnt daemon is started.

SSLCACertificateFile=/usr/local/etc/schedwisrv-ca.crt by default.

SSLQuickRandom

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

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

SSLQuickRandom=Y by default.

Running the agent

Starting

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

bash# /usr/local/bin/schedwiclnt

Note

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

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

Stopping

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

Important

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

Reloading the configuration file

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

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

Important

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

Sample startup scripts

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

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

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

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

Enabling SSL

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

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

SSL can be enabled agent by agent. For instance, local agents, inside the company network, may not require a such security level. However, agents installed outside the company, which use an insecure network, should be configured to use SSL. Out of the box, schedwiclnt — the agent part of Schedwi — is not configured to use SSL: the SSLEngine parameter must be set at Y first.

For each end of the SSL network link, two files are required: a certificate file and a key file. On the server side — schedwisrv — these files have been generated automatically during the first start and they will be used for the SSL communications with all the agents. On the agent side the required files will also be generated the first time schedwiclnt is started. At that time a request will be sent to the server and will have to be validated by an administrator through the schedwica command (see the section called “Using the schedwica program” for more details). Only then, the agent will start listening to requests from the server.

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

schedwiping <full_host_name_of_the_agent>

The following reply means that everything is working as expected:

The agent v0.1.3 is running.

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

Advanced configuration

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

To be able to run tasks for several users like this, the schedwiclnt daemon must be run under the system administrator account (i.e. root on Unix systems). This may be a security issue as the agent will be able to run as a privileged user any command 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 agent. Using GnuTLS the agent and the server authentify to each other before running any command. Moreover, the communication between them is encrypted. Using this method, the agent is sure that the commands are issued by the Schedwi server.

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

Note

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

On the server side, the agent 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 Schedwi server is composed of three parts:

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

  • The schedwireg daemon which must also be running at all time and is responsible to collect the new agents registration requests.

  • The database which contains all the parameters required by schedwisrv. For instance the jobs, the jobsets and the associated commands are all defined in this database. The command line and graphical tools allow administrators to define all those parameters.

    So far, Schedwi has been tested with SQLite, PostgreSQL and MySQL. By default, a SQLite database is create and configure at the end of the installation process.

    The installation of a database system is beyond the scope of this manual. Please refer to the official documentation of those databases or use a pre-packaged installation for your operating system.

Note

The schedwisrv daemon and the database server do not have to be installed on the same computer (except for SQLite).

The schedwi, schedwiping, schedwica and schedwidbchecks commands are also part of the Schedwi server. schedwi is the command line user interface which is used to configure jobs and jobsets. schedwiping allows the administrator to test the connection with the agents. schedwica is used to register new agents and sign agent certificates. schedwidbchecks can be used to detect and repair inconsistencies 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 2.2.0 or above. The GnuTLS certtool -v command can be used to check the installed version.

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

  • The libdbi library. Again, some systems provide pre-packaged versions (look for the development package usually called libdbi-devel or libdbi0-dev). For more information on libdbi, visit the libdbi Web Site.

  • SQLite version 3 to create the initial database at installation time. This database can be replaced later on by PostgreSQL or Mysql.

The compilation process uses the Automake and Autoconf system.

Compilation and Installation

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

  1. Download the Schedwi server in a temporary directory.

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

    gunzip -c schedwisrv-0.1.3.tar.gz | tar xf -
cd schedwisrv-0.1.3
./configure --with-libgnutls-prefix=/usr/local/gnutls
make
su root
make install

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

configure parameters

configure supports more parameters than the one described above. A complete list can be obtain with configure -h.

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

Database creation

The Schedwi server requires a database. All the Database Systems supported by the libdbi library can be used (see the libdbi Web Site for more details). In this manual, only the configuration of MySQL, PostgreSQL and SQLite is detailed.

Note

A SQLite database has already been created and configured for you during the installation process.

MySQL

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 your operating system.

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

  1. The creation of 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 as follow:

    cd schedwisrv-0.1.3/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.

  4. The libdbi driver for MySQL must be installed. Your system probably provides a pre-packaged version for it (libdbi-dbd-mysql or libdbd-mysql)

  5. The database configuration directives in the schedwisrv.conf configuration file must be set accordingly:

    DBI_DRIVERNAME=mysql
DBI_USER=schedwi
DBI_PASSWORD=schedwi_password
DBI_DBHOSTNAME=localhost
DBI_DBNAME=schedwidb
PostgreSQL

The installation of the PostgreSQL Database System is not described in this manual. Visit the PostgreSQL Web Site for installation details. You can also use pre-packaged installations provided for your operating system.

Once the PostgreSQL server is installed and started, the following basic steps can be used to set up the Schedwi database.

  1. Create a Linux user which is going to be assigned a role in PostgreSQL. For example, to create the schedwi user:

    useradd schedwi

  2. Create a PostgreSQL role for the newly created schedwi user:

    su postgres
psql
  CREATE ROLE schedwi;
  ALTER ROLE schedwi LOGIN;
  ALTER ROLE schedwi CREATEDB;

  3. Create the schedwidb database:

    su schedwi
createdb schedwidb

  4. Load the Schedwi schema and initial data. This can be done by the use of the provided SQL script under the sql directory of the Schedwi server archive:

    su schedwi
cd schedwisrv-0.1.3/sql
psql schedwidb < schedwi_postgresql.sql

  5. Install the libdbi driver for PostgreSQL. Your system probably provides a pre-packaged version for it (libdbi-dbd-pgsql or libdbd-pgsql)

  6. The database configuration directives in the schedwisrv.conf configuration file must be set accordingly:

    DBI_DRIVERNAME=pgsql
DBI_USER=schedwi
DBI_DBHOSTNAME=localhost
DBI_DBNAME=schedwidb
SQLite

SQLite is usually provided as a package on most systems (check for sqlite-3 or sqlite3)

Once SQLite is installed, follow these steps:

  1. Create and populate a database for Schedwi. For this step, a SQL script is provided under the sql directory of the Schedwi server archive:

    cd schedwisrv-0.1.3/sql
sqlite3 /usr/local/var/run/schedwidb < schedwi_sqlite.sql

    The location of the database file (/usr/local/var/run/schedwidb in the example) can be changed as long as the DBI_DBDIR and the DBI_DBNAME directives are set accordingly in the configuration file (see below)

  2. Install the libdbi driver for SQLite. Your system probably provides a pre-packaged version for it (libdbi-dbd-sqlite3 or libdbd-sqlite3)

  3. The database configuration directives in the schedwisrv.conf configuration file must be set as follow:

    DBI_DRIVERNAME=sqlite3
DBI_DBNAME=schedwidb
DBI_DBDIR=/usr/local/var/run

Configuration

Configuration file location and syntax

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

Note

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

Tip

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

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

The format of the file is straightforward:

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

  • Empty lines are ignored.

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

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

Global Configuration parameters

Note

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

USER

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

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

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

GROUP

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

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

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

LOG_FILE

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

LOG_FILE=/usr/local/var/log/schedwisrv/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 fields in the log file. This value is only used if the SYSLOG directive is not set. See your strftime(3) manual page for a format description.

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

DATE_FORMAT=%c by default.

PID_FILE

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

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

PID_FILE_REGISTRAR

Path and name of the file that will be used to store the process ID of the schedwireg daemon. This file is used by the schedwireg 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 schedwireg daemon for instance.

PID_FILE_REGISTRAR=/usr/local/var/run/schedwisrv/schedwireg.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 agents. A name defined in /etc/services can also be used.

SERVER_PORT=2005 by default.

REGISTRAR_PORT

Network TCP port number used by the schedwireg daemon to listen to agents. A name defined in /etc/services can also be used.

REGISTRAR_PORT=2004 by default.

ALLOW_FROM

Allow access based on the host name, or host address, of the agents.

ALLOW_FROM accepts a list of addresses or host names separated by a comma: 192.168.0.1, 127.0.0.0/8, fe80::211:d8af:f19e:7ae4, agent1.your.organization.com, 172.24.0.*

Addresses can be prefixed with ! to explicitly deny access. Denies have precedence on allow rules. For instance, the following rule allows access only from the hosts in the 192.168.0.0/24 network but except 192.168.0.1 which is denied:

192.168.0.0/24, !192.168.0.1

Also, notice that the TCP Wrappers can be used to filter the access to the Schedwi server. See your hosts_access(5) manual page for more details.

No access control by default.

ADDRESS_FAMILY

Specifies which address family should be used. Valid arguments are any, inet (use IPv4 only) or inet6 (use IPv6 only).

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

SSLCertificateFile

PEM-encoded certificate file name for the server. This file is generated automatically the first time schedwisrv is started. It is sent to the agent every time a session is established to allow the authentication of the server.

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

SSLCertificateKeyFile

PEM-encoded private key file for the server. This file is generated automatically the first time schedwisrv is started.

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.

SSLCACertificateFile

PEM-encoded authority's certificate file name used to sign agent certificate requests. This file will be automatically created for you the first time the schedwisrv daemon is started.

SSLCACertificateFile=/usr/local/etc/schedwisrv-ca.crt by default

SSLCACertificateKeyFile

PEM-encoded private key file for the authority. This file will be automatically created for you the first time the schedwisrv daemon is started.

Also, the private key file defined by this directive 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.

SSLCACertificateKeyFile=/usr/local/etc/schedwisrv-ca.key by default

SSLCACRLFile

PEM-encoded Certificate Revocation List (CRL). Agents with revoked certificates will not be able to access the schedwisrv daemon any more. This file is managed through the schedwica command.

SSLCACRLFile=/usr/local/etc/schedwisrv-ca.crl by default

SSLAgentCertificateDir

Directory used to store the signed agent certificates.

SSLAgentCertificateDir=/usr/local/var/lib/schedwisrv/crt by default

SSLAgentRequestDir

Directory that contains the certificate signing requests (CSR) of the agents waiting to be registered. These pending requests must be approved by an administrator through the schedwica command.

SSLAgentRequestDir=/usr/local/var/lib/schedwisrv/csrpending by default

SSLAgentSaveRequestDir

Directory that contains a backup of the certificate signing requests (CSR) of registered agents.

SSLAgentSaveRequestDir=/usr/local/var/lib/schedwisrv/csr by default

SSLQuickRandom

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

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

SSLQuickRandom=Y by default.

Database Configuration parameters

The following configuration parameters allow the Schedwi server to access the database. They are all optional. If not set, the schedwisrv daemon will use the SQLite3 database /usr/local/var/run/schedwidb.

DBI_DRIVERDIR

The directory to search for libdbi database drivers. If not set, the default, libdbi will use its predefined directory.

For example, DBI_DRIVERDIR=/usr/lib/dbd

DBI_DRIVERNAME

The database driver to use. Can be mysql, pgsql, freetds (for MS SQL Server and Sybase), sqlite, sqlite3, firebird or mSQL. Also, for each of these Database System a libdbi driver must be installed.

DBI_DRIVERNAME=sqlite3 by default.

DBI_DBHOSTNAME

Database server. A name or an IP address in numbers-and-dots notation can be used. This parameter is ignored if the database driver in use is sqlite or sqlite3 (see DBI_DRIVERNAME above)

DBI_DBHOSTNAME=localhost by default.

DBI_USER

Database login name (not required for sqlite and sqlite3).

By default the current Unix login name.

DBI_PASSWORD

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

No password by default.

DBI_DBNAME

Database name. For sqlite and sqlite3 this is the database file name under the DBI_DBDIR directory (see below).

DBI_DBNAME=schedwidb by default.

DBI_DBDIR

Only used for sqlite and sqlite3. This is the directory that contains the Sqlite databases.

DBI_DBDIR=/usr/local/var/run by default.

DBI_FREETDS_VERSION

FreeTDS protocol version:

  • 4.2 for Sybase before System 10, Microsoft SQL Server 6.x

  • 5.0 for Sybase System 10 and above

  • 7.0 for Microsoft SQL Server 7.0

  • 8.0 for Microsoft SQL Server 2000

DBI_FREETDS_VERSION=8.0 by default.

DBI_ENCODING

Character encoding which is to be used as the connection encoding.

Not set by default.

DBI_ENCODING=UTF-8 for example.

Modules Configuration parameters

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

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

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

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

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

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

MODULE_DIR

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

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

MODULE_LOAD

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

For example: MODULE_LOAD=mod_shell

MODULE:module_name:module_directive

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

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

Running the server

Starting

To start the Schedwi server daemon simply run the schedwisrv and schedwireg commands. These programs go automatically in the background. If your PATH environment variable does not contain the path to the schedwisrv and schedwireg commands, the full path must be specified. For example:

bash# /usr/local/bin/schedwisrv
bash# /usr/local/bin/schedwireg

Important

The schedwisrv and schedwireg daemons do 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 and schedwireg record 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.

Stopping

To stop the server, simply send the TERM signal (number 15) to the schedwisrv and schedwireg processes. The process identification of these daemons are stored in the files defined by the PID_FILE and PID_FILE_REGISTRAR configuration directives.

Important

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

Reloading the configuration file

Changes to the configuration file whilst the schedwisrv and schedwireg daemons are running are not automatically taken into account. A stop and a restart of the processes will allow them to re-read the 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 daemons. This signal force the processes to re-read the configuration file without having to be stopped. Moreover, this signal can be used to rotate the log file as schedwisrv and schedwireg will close and reopen a new one.

Important

If schedwisrv or schedwireg find an error while reading the 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

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

Using the schedwiping program

The schedwiping diagnostic tool is part of the Schedwi server and is installed alongside 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 sides.

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

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

Tip

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

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

If the agent is defined by its IPv6 address in the database, the address must be surrounded by square brakets on the command line:

bash# /usr/local/bin/schedwiping '[fe80::6a10:59ef:ffe5:5db8]'

Using the schedwica program

schedwica is part of the Schedwi server. This tool is used to register the new agents with the Schedwi server and to distribute and revoke agent certificates.

When an agent is started for the first time it generates a certificate signing request and send it to the schedwireg daemon on the server. This pending request must then be accepted by an administrator via the schedwica command. SSL or non-SSL agents are managed the same way. Although a certificate is not generated for non-SSL agents.

Finally, in some special cases when a certificate has already been generated through an other mecanism (a company CA for instance) it can be used instead and loaded in the Schedwi database with schedwica CERTFILE.

schedwica accepts a few command line parameters. You can use the -h option to get a complete list.

With the -l option, the list of pending certificate signature requests is displayed.

From this list, an agent can be registered and a certificate generated with the -s option. In that case, you can provide a description for the new agent with the -d option.

With the -R option, all records of the specified agent are removed (certificate signing requests and certificate) and its certificate is revoked. The agent stays in the database but cannot be used anymore until a new certificate is generated for it.

To get more details, consult the schedwica(8) man page.

Using the schedwidbchecks program

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

The command-line program

A command line tool, schedwi, is also provided to create and manage jobs and jobsets. Through this tool you can control all aspects of the scheduling of your jobs, like configuring new calendars, force start a job, getting the status of your workload.

With schedwi, you can configure all the following items:

Jobs

A job is simply a command to be run at a specific date and time on a remote host. A lot of parameters can be associated with a job like for instance the user name under which to run the command, the file names to store the output of the command, or the expected return code.

Jobsets

A jobset is a group of jobs or other jobsets. This allows you to organize logically your jobs in a tree-like fashion. Like jobs, jobsets also have parameters. In fact, they can store exactly the same parameters as jobs. Those parameters will be inherited by jobs bellow the jobset. Think of them as default values for jobs. For instance, if you define the remote host name at the jobset level, then all the jobs inside it will run on this host (if not specifically defined at the job level). If you need to change this host name, simply changing it in the jobset will change it in all the jobs.

Links

Dependency links are a way to chain together jobs and jobsets. This way you can specify that for the job B to start, then job A must be successfully completed. A job can be linked to several other jobs/jobsets and the status code to wait can also be “failed” (to recover from a error) or “running” (to start a job at the same time as an other one).

Calendars

A calendar is one of the job or jobset parameter. It specifies which days the job/jobset should be run. Calendars must be defined before been associated with jobs and jobsets.

In the schedwi command-line tool, a special mode is used to administer your calendars — use the cal command to enter this mode.

Each calendar has a name and a formula that defines the associated days. The formula can be as simple as “Jan/23” (23rd of January) to the more complex “Jan-Mar/Open/Last” (last open day of January, February and March). Hopefully, Schedwi comes with pre-defined calendars for common situations (Every day, Every week day, ...)

Finally, calendars are showed in a tree-like fashion, just for you to organize them as you like.

Hosts

Remote hosts on which jobs are going to be run must be defined; the Schedwi agent must have been installed on those hosts. Through the schedwi command line tool, the hosts mode allows you to define these hosts and their parameters (SSL encryption, TCP port, ...)

Environment groups

Environment variables can be associated with jobs. Whenever the command associated with a job starts, the defined environment variables are automatically set. Also, environment variables can be associated with hosts; every time a command starts on a host, the variables are set.

Environment variables are grouped in environment groups which are then associated with jobs, jobsets and hosts. The env mode of the schedwi tool is used to administer these groups.

Workloads

Every day, the Schedwi server will decide, based on the calendars, which jobs and jobsets are going to be run. This is the workload for the day. Once a workload is completed — all its jobs have successfully run — it is removed. Workloads that failed — at least one job failed — are kept a few days so you can restart or retry failed jobs. Workloads can be listed with the wl command.

When the Schedwi server decides that a job is planned for the day, it will copy all its parameters in a special area of its database. The changes you may carry on a job are then not applied for its instances in workloads (only a few parameters can be changed on these instances).

Installation and configuration

The schedwi command line tool is part of the Schedwi server package and is installed at the same time. It uses the same configuration file — schedwisrv.conf — but can also optionally use two other files that can overwrite parameters defined in the server configuration file: schedwi.conf and ~/.schedwirc (in that order).

Only a few parameters are required and they simply specify how to access the Schedwi database: DBI_DRIVERNAME, DBI_USER, DBI_PASSWORD, DBI_DBHOSTNAME, DBI_DBNAME and DBI_DBDIR (see the section called “Database Configuration parameters” for a full description of these parameters).

Usage

To start the Schedwi command line tool, just type schedwi at the command prompt:

bash# schedwi
Schedwi version 0.1.3
Enter "help" for instructions
/>

Then, to get the list of available commands type help. The help on a specific command can be displayed with help command.

jobs

Create

The mk command can be used to create a new job. The job parameters can be specified as options. If not set, they will inherit their value from the parent jobset. See help mk for the list of parameters.

Example:

mk --start=18:00 --command=/usr/local/bin/send_report.sh /Dev/Report/send
Display parameters

The cat command shows all the job parameters:

cat /Dev/Report/send
                 Name   : send
                 Type   : Job
              Enabled   : True
                 Host * : localhost (2006)
             Calendar * : /Samples/Every day
           Start time   : 18h00
              Command   : /usr/local/bin/send_report.sh
           Parameters * :
  Success return code * : 0
             Username * : nobody
          Output file * : /dev/null
           Error file * : /dev/null
         Max duration * : No limit
    Number of retries * : 0
     Interval retries * : 0h05
Limit past start time * : 24h00
        Load user env * : False
          Description   :

The * character specifies that the parameter is inherited from the parent jobset.

Change parameters

Once a job is created, you can change any of its parameter with the set command. For instance, to change the start time and the user, the following command can be used:

set --start=18:30 --user=john /Dev/Report/send

Also, if you decide to remove a parameter so its value will be inherited from its parent jobset, you can prefix the parameter with del. For instance to remove the start time and get the one from the parent jobset, you can type:

set --delstart /Dev/Report/send
Links

Dependency links can be established between jobs. This way you can specify for instance that for the job B to start, the job A must have been executed successfully. Links with jobsets are also allowed: you can define a link between the job B and the jobset C. For the job B to start, all the jobs and jobsets inside jobset C must be completed.

You can define links not only on the successful completion of an other job but also on all the other status. For instance you can define a job to start when an other job fails, or when it starts running.

Finally, a job can be linked to several other jobs. All the linked jobs must be validated for the job to start (logical AND).

To create a link, use the ln command:

ln jobB jobA

which means that jobA must be completed for jobB to start. Also, you can specify the status to wait for (by default it’s completed as in the previous example):

ln --failed jobB jobA
ln --running jobB jobA

Finally, links can be displayed with the cat command (see the link parameter near the end):

cat /Dev/Report/send
                 Name   : send
                 Type   : Job
              Enabled   : True
                 Host * : localhost (2006/SSL)
             Calendar * : /Samples/Every day
           Start time   : 18h00
              Command   : /usr/local/bin/send_report.sh
           Parameters * :
  Success return code * : 0
             Username * : nobody
          Output file * : /dev/null
           Error file * : /dev/null
         Max duration * : No limit
    Number of retries * : 0
     Interval retries * : 0h05
Limit past start time * : 24h00
        Load user env * : False
                 Link   : /Dev/Report/build must be completed
          Description   :
Renaming, copying and moving jobs

Jobs can be renamed and moved with the mv command. They can be copied with the cp command:

mv /Dev/Report/send "/Dev/Report/Send Report"
cp "/Dev/Report/Send Report" /Prod/Report

Notice how you need to enclose names that contain spaces with quotes.

Jobsets

Change the current jobset

By default, when you start schedwi, the current jobset is the root one (/). You can change this current jobset with the cd command so you won’t have to specify the full path name of jobs you want to access:

cd /Dev/Report
pwd
List content of jobsets

The ls command can be used to list the jobs and jobsets inside a specific jobset. If no jobset is specified, then the content of the current jobset is displayed. As an alternate way, the tree command will list the jobs and jobsets in a tree-like format.

Create

The mkjs command can be used to create a new jobset. The jobset parameters can be specified as options. If not set, they will inherit their value from the parent jobset. See help mkjs for the list of parameters.

Example:

mkjs --host=flower.example.com --calendar="/Samples/Every Day" --start=16:00 /Dev/Backups
Change parameters

The set command is used to change the jobset parameters. For more details, see help set.

Links

As for jobs, dependency links can be create between jobsets. See help link for more details.

Renaming, copying and moving jobsets

Like jobs, jobsets can be renamed and moved with the mv command. They can be copied with the cp command (with the -r option):

cp -r /Prod /Test

Calendars

New calendars can be create and managed through the cal sub-command. At the schedwi prompt, just type cal to enter this mode:

/> cal
Type exit to leave the cal sub-command
cal:/>

Calendars are arranged in directories. These directories are simply a way for you to organize and group your calendars. To navigate the calendar directory tree, you can use the cd, pwd, ls and tree commands:

cal:/> pwd
/
cal:/> ls
Custom   Samples  
cal:/> cd Samples
cal:/Samples> ls
Every Friday                 Every Monday                 
Every Saturday               Every Sunday                 
Every Thursday               Every Tuesday                
Every Wednesday              Every day                    
Every weekday                Every weekend                
First day of the month       First open day of the month  
Last day of the month        Last open day of the month   
Worldwide                    
cal:/Samples>
Create

New directories are created with the mkdir command. New calendars are created with the mk command:

mk --formula=Aug/* --description="Every day in August" /Custom/august

For a full presentation on calendar formulas, see help formula and also pre-defined calendars in /Samples to get examples.

Display a calendar

A calendar can be displayed with the cat command:

cat /Custom/august
        Name : august
        Type : Calendar
     Formula : Aug/*
 Description : Every day in August.

Also, you can have an overview of the matching days with the show command:

show -m 0 /Custom/august
/Custom/august:
                           2011                            
         January                         February          
Mon Tue Wed Thu Fri Sat Sun    Mon Tue Wed Thu Fri Sat Sun
                     1   2           1   2   3   4   5   6  
 3   4   5   6   7   8   9       7   8   9  10  11  12  13  
10  11  12  13  14  15  16      14  15  16  17  18  19  20  
17  18  19  20  21  22  23      21  22  23  24  25  26  27  
24  25  26  27  28  29  30      28                          

          March                           April            
Mon Tue Wed Thu Fri Sat Sun    Mon Tue Wed Thu Fri Sat Sun
     1   2   3   4   5   6                       1   2   3  
 7   8   9  10  11  12  13       4   5   6   7   8   9  10  
14  15  16  17  18  19  20      11  12  13  14  15  16  17  
21  22  23  24  25  26  27      18  19  20  21  22  23  24  
28  29  30  31                  25  26  27  28  29  30      

           May                             June            
Mon Tue Wed Thu Fri Sat Sun    Mon Tue Wed Thu Fri Sat Sun
                         1               1   2   3   4   5  
 2   3   4   5   6   7   8       6   7   8   9  10  11  12  
 9  10  11  12  13  14  15      13  14  15  16  17  18  19  
16  17  18  19  20  21  22      20  21  22  23  24  25  26  
23  24  25  26  27  28  29      27  28  29  30              

           July                           August           
Mon Tue Wed Thu Fri Sat Sun    Mon Tue Wed Thu Fri Sat Sun
                 1   2   3     [ 1][ 2][ 3][ 4][ 5][ 6][ 7] 
 4   5   6   7   8   9  10     [ 8][ 9][10][11][12][13][14] 
11  12  13  14  15  16  17     [15][16][17][18][19][20][21] 
18  19  20  21  22  23  24     [22][23][24][25][26][27][28] 
25  26  27  28  29  30  31     [29][30][31]                 

        September                        October           
Mon Tue Wed Thu Fri Sat Sun    Mon Tue Wed Thu Fri Sat Sun
             1   2   3   4                           1   2  
 5   6   7   8   9  10  11       3   4   5   6   7   8   9  
12  13  14  15  16  17  18      10  11  12  13  14  15  16  
19  20  21  22  23  24  25      17  18  19  20  21  22  23  
26  27  28  29  30              24  25  26  27  28  29  30  

         November                        December          
Mon Tue Wed Thu Fri Sat Sun    Mon Tue Wed Thu Fri Sat Sun
     1   2   3   4   5   6                   1   2   3   4  
 7   8   9  10  11  12  13       5   6   7   8   9  10  11  
14  15  16  17  18  19  20      12  13  14  15  16  17  18  
21  22  23  24  25  26  27      19  20  21  22  23  24  25  
28  29  30                      26  27  28  29  30  31
Change parameters

Once a calendar is created, you can change any of its parameter with the set command.

Jobs and jobsets using a specific calendar

To get the list of jobs and jobsets associated with a calendar, you can use the whatuses command:

whatuses "/Samples/Every Day"
/Samples/Every day:
    Jobset : /
    Jobset : /Dev
    Jobset : /Dev/Backups
    Jobset : /Dev/Reports
    Jobset : /Prod
    Jobset : /Prod/Reports
    Jobset : /Test
    Jobset : /Test/Reports
       Job : /Dev/Reports/Send Report
       Job : /Prod/Reports/Send Report
       Job : /Test/Reports/Send Report

Hosts

Before being able to run jobs on a remote host, the Schedwi agent must be installed on this host and also the host must be defined in the Schedwi database.

To manage hosts in the database, you first need to enter the hosts mode:

/> hosts
Type exit to leave the hosts sub-command
hosts>
Create

Hosts are usually created through the schedwica command which is the recommended way. See the section called “Using the schedwica program” for more details.

However, to define a new host, you can use the mk command:

mk flower.example.com

Also, if you want to define a host that uses ssl for its communications, you should use the --ssl and --sslcert options:

mk --ssl=True --sslcert=/tmp/cherry.crt cherry.example.com

with /tmp/cherry.crt the certificate file of the remote host.

See help mk for all the possible options.

Change a host parameter

The set command can be use to change a parameter to an already defined job. Any change (like port, description, ...) will be applied immediately.

View host parameters

To list all the details of a specific host, use the cat command:

hosts> cat flower.example.com:2006
        Hostname : flower.example.com
            Port : 2006
             SSL : False
     Certificate :
     Description :
List defined hosts

To list all defined host, simply use the ls command.

Jobs and jobsets using a specific host

To get the list of jobs and jobsets associated with a specific host, you can use the whatuses command:

hosts> whatuses flower.example.com
flower.example.com (2006):
         Jobset : /Dev
         Jobset : /Dev/Backups
         Jobset : /Dev/Reports
         Jobset : /Test
         Jobset : /Test/Reports
            Job : /Prod/Reports/Send Report
Constraint file : /Prod/Reports/Send Report: /tmp/report.xml must exist

Environment groups and variables

Environment groups are groups of environment variables that can be set on the remote host running a job. These groups can then be associated not only with jobs and jobsets but also with hosts. In this last case, every time a job is started on the host, these variables will be set.

Environment groups associated with jobsets are inherited by lower jobs and jobsets but added up. For instance, if the environment group A is associated with the jobset /test and the environment group B is associated with the job /test/job1 then, when run, /test/job1 will have defined the variables from A and from B (in that order — so a variable can be overwritten at the job level) Furthermore, if the environment group C is associated with the host on which /test/jobs1 is going to run, then the variables from C, A and B (in that order) are going to be set.

To manage environment groups, you first need to enter the specific mode:

/> env
Type exit to leave the env sub-command
env>
Create a group and add environment variables

To create a new environment group, simply use the mk command:

env> mk prod_env

Then, to add environment variables to the new group the set command can be used with the --append option:

env> set --append=DEBUG=0 --append=BINPATH=/usr/local/bin prod_env

In this case, two variables have been added:

DEBUG=0
BINPATH=/usr/local/bin

Also the --insert, --position and --delete parameters can be used to insert a new variable in a specific position in the group or to delete an existing variable. See help set for more details.

View a group details

To list all the variables defined in a group, use the cat command:

env> cat prod_env
       Name : prod_env
      Var 1 : DEBUG=0
      Var 2 : BINPATH=/usr/local/bin
Description :
List environment groups

The ls command is used to list all defined environment groups.

Jobs, jobsets and hosts associated with a specific group

The whatuses command can be used to list all the jobs, jobsets and hosts associated with a specific environment group.

env> whatuses test_env
test_env:
    Jobset : /Dev
      Job : /Test/Report/Send Report
      Job : /Test/Report/Print
     Host : cheese.example.com (2006)

Schedwi firewalls and security

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

Alternatively, and if available on the operating system, schedwiclnt, schedwisrv and schedwireg can all use the TCP Wrappers to filter the network access. See your hosts_access(5) manual page for more details. The daemon names are schedwiclnt for the agent, and schedwisrv for both schedwisrv and schedwireg.

Example on the agent to only allow the server (cherry.foo.com):

/etc/hosts.allow:
     schedwiclnt: cherry.foo.com

/etc/hosts.deny:
     schedwiclnt: ALL

On the server, to only allow agents from the 192.168.0.0/24 network:

/etc/hosts.allow:
     schedwisrv: 192.168.0.0/255.255.255.0

/etc/hosts.deny:
     schedwisrv: ALL

Finally, the ALLOW_FROM directive in the configuration file of both the agent (schedwiclnt.conf) and the server (schedwisrv.conf) can also be used to filter the network access. For a complete description of this directive, see the section called “Basic configuration parameters” for schedwiclnt. For schedwisrv see the section called “Global Configuration parameters”.

About Schedwi

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

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

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