     [file version.texi not included]
     [file rendition.texi not included]

Published by the Free Software Foundation, 51 Franklin Street, Fifth Floor Boston, MA 02110-1301, USA

Copyright © 2005 Sergey Poznyakoff

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the license is included in the section entitled ``GNU Free Documentation License''.

(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify this GNU Manual, like GNU software.  Copies published by the Free Software Foundation raise funds for GNU development.''

GSC
***

This edition of the GSC Manual, last updated UPDATED, documents GSC Version VERSION.

Introduction to GSC
*******************

GSC stands for Gray's Script Collection. It is a collection of various mostly unrelated tools and configuration files I use in system administration and software development. The tools are mainly for my own use, however I'd be glad if you find them useful too. The package is distributed under GPL, for exact license terms and conditions see file COPYING in the main distribution directory.

This manual documents version VERSION of the package. It is distributed under GFDL, see Copying This Manual.

CVS Tools
*********

This set of tools is designed to facilitate some tasks related to CVS and Savane maintenance.

mksnapshot
==========

This mksnapshot utility creates source tarballs from modules in CVS and/or SVN repositories. This is useful, for example, to create daily snapshots from the repository.

The program looks for modules in the CVS repository. For each module found, it checks out first line of ChangeLog file, and if it presents a date later than the one when the last snapshot was made, it checks out the module into a temporary directory, tars its contents and places the resulting archive into the distribution directory.

The resulting archive is named PROJECT-DATE.tar.gz, where PROJECT is the name of the module and DATE is latest ChangeLog date in YYYY-MM-DD format. In addition, a symbolic link to the latest snapshot is created. The link is named PROJECT-latest.tar.gz.

The actual compression method, and the tarball suffix are configurable (see the description of COMPRESS variable below).

If the module is not found in the CVS, mksnapshot tries out the SVN repository, if it is configured.  The repository last change date is checked using svn info command, and if it is later than the date of the last snapshot, the new snapshot is made, as described above.

The program takes a single argument, a name of the configuration file. This file should declare several environment variables that control mksnapshot behavior.

 -- Variable: CVSROOT
     This variable specifies the CVS root directory name.

 -- Variable: SVNROOT
     This variable specifies the SVN root directory name.

 -- Variable: WD
     A working directory for extracting repository data.

 -- Variable: FTP
     Target directory where tarballs should be placed.

 -- Variable: MAXSNAPSHOTS
     Maximum number of snapshots to keep for each project. This variable is optional. It defaults to 3.

 -- Variable: REPOSITORY
     Type of CVS repository. This variable is optional.

     Set REPOSITORY=PLAIN if you use classic ``plain'' CVS repository, and REPOSITORY=SAVANE, if you use Savane-based repository. Lower-case values are accepted as well. Default is SAVANE.

     Warning: setting REPOSITORY=PLAIN works only with CVS repositories.

 -- Variable: COMPRESS
     Name of the compress program to use. Recognized values are compress, gzip (default), and bzip2. Any other value is also accepted, provided that you also set the ZSUFFIX variable (see below).

 -- Variable: ZSUFFIX
     Additional suffix for compressed tarballs (without leading dot). Default values depend on the value of the COMPRESS variable, as shown in the table below:

     COMPRESS value   Suffix
     compress   Z
     gzip   gz
     bzip2   bz2

 -- Variable: VERBOSE
     Set verbosity level. Allowed values are yes, no, or any decimal number. The bigger the number, the more information is displayed. The value of yes is equivalent to 1, that of no is equivalent to 0. Default is no.

The behaviour of mksnapshot differs depending on the type of repository used. For plain repositories, mksnapshot processes all the modules in the repository, except CVSROOT. Obviously, this approach works only for CVS repositories.

For Savane repositories, the program first gets the list of user's groups, then for each group it looks up a module of this name. When found, such module is processed as described above. Thus, only those modules are selected, in which the current user participates.

Sync WWW
========

The programs in this section form a framework for automatic update of a directory upon CVS commit. This is useful, for example, to keep a mirror of a module. Puszcza (http://puszcza.gnu.org.ua) uses this for automatic update of projects' home pages.

This works as follows: suppose that each project keeps publicly available data (html pages, etc) in directory /software/PROJECT. These data are under CVS control in directory /webcvs/PROJECT. Upon commit, CVS server executes CVSROOT/loginfo which calls sv_sync_www_schedule. This utility schedules an update job. Another program, sv_sync_www is called as a cron job. This program flushes all jobs scheduled so far. For each project it changes to the project public directory and performs cvs update  (well, actually it does much more than that... see sv_sync_www).

The following subsections describe each utility in detail.

sv_sync_www_schedule
--------------------

The program sv_sync_www_schedule schedules a CVS synchronization job for further execution. The jobs are stored in directory /var/spool/savane/. This directory must have sufficient permissions for sv_sync_www_schedule to access it. Normally, this means adding each CVS user to a common group, e.g. svusers and setting directory access mode to 0775:

     $ ls -ld /var/spool/savane
     drwxrwxr-x    2 root     svusers        25 Aug 18 18:00 savane/

The program takes three arguments: user name (not used currently), file name of the CVS repository, and the list of files changed by the commit. The program is supposed to be invoked by each commit. The proper way to do so is to add the following line to the project's CVSROOT/loginfo file:

     ALL      /bin/sv_sync_www_schedule ${USER} ${CVSROOT} %s

sv_sync_www_schedule logs errors via syslog channel local1.error.

sv_sync_www
-----------

UNREVISED The program sv_sync_www is the main engine for CVS synchronization. It operates in two modes: in single job mode it synchronizes a single CVS commit (called job), in cron job mode it processes a set of accumulated jobs at once.

Whatever the mode is, the processing of a single job looks as follows: the program determines CVS root directory, subdirectory and files affected by the commit, changes to the directory where the synchronization must be performed (a destination directory, and runs cvs update with appropriate arguments. After update, sv_sync_www recursively searches for files named .symlinks under the destination directory. Each such file specifies the symbolic links that should be created within a directory, where it resides.

In a .symlinks file any empty lines and lines starting with # or ; are ignored. Rest of lines must contain two words: the name of the file to create the link from, and the name of the link to be created. Thus, the following .symlinks file:

     # comment
     gsc.html index.html

will create a link named index.html, pointing to the file gsc.html.

Notice that the linking is allowed only within or under the directory containing .symlinks file. In particular, sv_sync_www will refuse to create links whose names begin with the directory separator or contain ...

Single job
..........

Single job mode is the default mode for sv_sync_www. It operates in this mode, unless -s command line option is specified.

It takes one or two command line arguments. A single command line argument is parsed as a %s parameter in loginfo invocation, i.e. it must consist of the project directory name and the whitespace separated list of files, affected by the commit. The project directory name can be absent, which is indicated by the leading whitespace. The list of files can have two special forms: - New directory and - Imported sources.

In order to invoke sv_sync_www_flush on each commit, the loginfo file must contain a line similar to the following:

     ALL  (date; cat; (sleep 2; /bin/sv_sync_www %s ) \
             &\ ) >> /var/log/sync_www.log 2>&1

There are two notes on this example. First, programs like sv_sync_www must be run in the background, otherwise they will cause dead lock conditions due to the use of lock files. Secondly, this example shows only the minimal invocation of sv_sync_www. You will always need to pass it the commited file name or names (see %s above). However, depending on the actual configuration you may need to pass it some configuration options as well.

Cron job
........

UNREVISED Sv_sync_www starts in cron job mode when it is given -s command line argument. It takes a single optional argument, specifying the spool directory to use (defaults to /var/spool/savane.

Invocation
..........

UNREVISED First of all, sv_sync_www assumes some default settings that you should know about. Namely, it supposes that both CVS repository and update directory (hereinafter called WWW directory) are located on the same server. Further, it supposes that the former is called /webcvs and the latter is called /home/puszcza/software. And, finally, it invokes cvs binary using the following command line:

     CVS_RSH=ssh cvs -q -z3

Of course, any of these defaults can be changed from the command line.

To specify another WWW directory, use -w option.

To specify a repository directory, use -R. The argument to this option should be a directory name itself, without any access method prefix. See below for a way to specify this.

In particular, if you use Savane-like CVS layout and wish to use immediate synchronization, your loginfo would contain:

     ALL  (date; cat; (sleep 2; /bin/sv_sync_www -R ${CVSROOT} %s ) \
             &\ ) >> /var/log/sync_www.log 2>&1

The sv_sync_www_flush script passes this option by default.

If the repository and WWW directory are located on different servers, the IP address of host name of the server containing WWW directory must be specified via -H.

In this case sv_sync_www will invoke cvs binary on the WWW server using ssh (more precisely: /usr/bin/ssh). The name of the ssh binary can be set using -r option.

Further, invoked cvs will need to access remote CVS repository. The directory name of this repository can be specified using -R option, described above. To specify access method, use -m option. The argument to this option will be prepended to the repository directory (either default one or the one specified using -R option), so make sure you end it with a colon.

By default, sv_sync_www will assume that cvs should use ssh for accessing the remote server (see the default cvs invocation above). If it is not the case, you can use -c command line option. The cvs commands will be appended to the supplied command verbatim.

Finally, please notice that using remote WWW server you will have to set up an access from the CVS to WWW and from the WWW to CVS without passwords (usually this means setting up ssh for public keys authentication).

To illustrate these concepts, suppose that the name of the remote WWW server is www.foo.org, it should be accessed using rsh (Note: do not use it in real life. It is unsecure), the repository itself should be accessed using gserver method, and all CVS interactions should use maximal compression. Then, the command line for sv_sync_www will be:

     sv_sync_www -H www.foo.org -m :gserver:cvs.foo.org: \
                 -r rsh -c 'cvs -q -z9' -R ${CVSROOT} %s

When setting up unusual configurations, it is often useful to be able to run sv_sync_www without actually changing anything. This mode is called dry run, and it is turned on by -n option. In dry run mode, sv_sync_www does not change anything, instead it just prints what it would have done. Additional debugging diagnostics can be enabled using -x option.

Finally, running sv_sync_www -h displays a short usage summary.

Seting Up CVS synchronization framework.
----------------------------------------

Loginfo file
............

     ALL  /usr/local/bin/sv_sync_www_schedule ${USER} ${CVSROOT} %s

Crontab
.......

     # Flush WWW synchronisation jobs, scheduled by sv_sync_www_schedule
     # once an hour
     0 */1 * * *     /usr/local/bin/sv_sync_www -s

sv_www_loginfo
--------------

The program sv_www_loginfo scans loginfo files of all the projects in the repository and replace the default ones (i.e. the ones whose contents is entirely commented out) with the contents described in the previous subsection. This is to avoid directly modfifying Savane sources and to achieve, at the same time, the desired WWW synchronization functionality. Once Savane is flexible enough to allow for user-configurable CVSROOT contents, the need for this program will go away.

At the time of this writing, sv_www_loginfo is called from crontab as follows:

     30 */2 * * * sv_groups --cron && \
                  sv_users --cron && \
                  sv_www_loginfo --cron

The program assumes the CVS repository under /webcvs. It takes the following command line options:

--cron
     Run as a cron job. All diagnostics is in this case reported via syslog channel local1.info. Without this option it goes directly to stderr.

--help
     Display short usage summary.

Source Tree Utilities
*********************

Programs described in this chapter perform a set of global replacements on all the files within a project. The operation is being performed in a separate directory, which is populated by make distdir command. After the replacement, make distcheck is run to ensure that the operation did not break integrity of the project. If distcheck passes successfully, the resulting update can be left in the temporary directory for further inspection, archived in a tar archive, or propagated back to the original project.

Prerequisites for running these programs are:

 1. Project must conform to GNU Coding Standards. In particular, it must support make distdir and make distcheck and these two goals must be built successfully on the unmodified project.

 2. The program must be run in the project top source directory

The usage synopsis is similar for both programs. The following command line options are supported:

-k
     Leave modified project in the temporary working directory. The name of the working directory is formed as PREFIX-PROGRAM, where PREFIX is the base name of the projects top source directory (unless overridden by -p, see below) and PROGRAM is the name of the invoked program.

-r
     Propagate the changed files to the original progect. This option requires GNU tar version 1.15.1 or newer.

-t
     Store modified project tree in tar archive named PREFIX-PROGRAM.tar.gz.

-p PREFIX
     Specify name prefix for temporary working directory and tar archive (see options -k and -t).

-h
     Display short usage summary.

The command line options to configure can be given using --configure. This option can be specified several times, arguments of multiple --configure options are concatenated in a whitespace separated list. The very first --configure option should be preceeded by a double-dash:

     -- --configure --with-prog

Any non-option arguments containing an equals sign, and any non-option arguments beginning with double-dash (--) are considered to be additional make arguments and are passed to make verbatim.

fixnamespace
============

Fixnamespace utility replaces all global identifiers in a project by prefixing them with a given string. This is useful for creating a common namespace if a project contains a loadable library, hence the name of the utility. Notice that only those symbols are modified, that do not already begin with the prefix.

Global identifiers are any functions, variables and typedefs declared in the header files of the project. To locate these, fixnamespace uses tag files, created by etags utility (see Tags Tables (GNU Emacs Manual)). Thus, to use fixnamespace you must have Emacs version 21.3 or newer installed on your system.

The utility takes two or more arguments. First argument is the prefix to be appended to all symbols. Rest of arguments specify the header files where to look for global symbols. Only file names should be given, without any directory prefixes.

Apart from the command line options common for all source-tree utilities, fixnamespace understands following option:

-x SYMBOL
     Exclude SYMBOL from replacement. This option can be given multiple times.

Example of using this program:

     fixnamespace -x scm_long2num mu_ message.h mailbox.h body.h list.h

Final notice: when too many header files are specified in the command line, the number of created Lisp variable bindings can exceed Emacs capacity; in this case emacs will signal an error. To overcome this, increase value of max-specpdl-size variable in fixnamespace.el near line 215.

fsf-move
========

During my activity as a free software programmer, the Free Software Foundation has twice changed its locations. Each such move implied a change of postal mail address, and, consequently, a need for updating each file in any free software project, since the standard GPL or LGPL copyright header refers to it.

Such a work can be very tedious for large projects, so when the FSF has recently changed its location again, I decided to automate the process once and for all. This is what fsf-move is for.

The program does not take any special command line options or arguments beside those described above (see Source Tree Utilities). Currently it is tuned to change postal mail address from

     59 Temple Place, Suite 330 Boston, MA 02110-1301 USA.

to

     51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

Should FSF move again, you will have to change these defaults by modifying fsf-move:177 and fsf-move.awk:21-22.

The program implements a sophisticated search-and-replace algorithm, if it knows a syntax of the language a file is written in. The purpose of the algorithm is to allow for arbitrary splitting of lines in the address and to preserve alignment and formatting of comments. This algorithm is applied to files whose names match following regexps:

*.[chyl]
     C sources;

*.m4|*.ac|*.at
     M4 sources;

*.sh
     Shell scripts;

*.awk
     AWK sources;

*.exp|*.tcl
     TCL sources;

*.am|Makefile.tmpl
     Automake sources;

*.el|*.scm*|*.lisp
     Various dialects of Lisp;

PO files (*.po), and their derivatives are ignored.

The rest of files is processed using fuzzy search algorithm, which is able to find the postal address in the majority of cases, though not always. Such files should probably be inspected after fsf-move finishes its work.

Root Utilities
**************

This chapter describes a set of utilities useful in system administration.

bind replication
================

UNREVISED

firewall
========

The firewall subdirectory of the source tree contains an m4 wrapper over GNU/Linux iptables utility. The basic idea behind it is to create a framework that could be used without changes on any platform, no matter what the underlying firewall implementation is. Currently it is implemented only for iptables. The support for BSD-style ipfw and, eventually, more will be added soon.

The framework is based on a set of m4 wrappers. From the point of view of a final user, its usage is as follows. First, the administrator creates a set of firewall rules using the primitives supplied by firewall.m4. Then he processes firewall.m4 using m4 and obtains a set of implementation-dependent firewall rules that can be fed to the shell.

You will probably not need to process firewall.m4 manually, we recommend to use rc.firewall instead (see rc.firewall). However, for the sake of completeness, here is how it should be invoked:

     m4 [-DSYSCONFDIR=DIR] -DACTION=ACTION firewall.m4

This command generates a set of implementation-dependent firewall rules that can be fed to the shell.

Its arguments are:

 -- Variable: ACTION
     Specifies which set of commands firewall.m4 is to create. Possible values are:

     status
          List actual firewall rules.

     flush
          Flush the firewall rules.

     FILENAME
          Read in and process file FILENAME.

Optional variable SYSCONFDIR specifies a directory where rule.d subdirectory is located (see rule.d). It defaults to /etc/firewall.

Firewall Primitives
-------------------

UNREVISED

 -- Firewall Primitive: ACCEPT chain, srcip, srcport, dstip, dstport, proto, log

 -- Firewall Primitive: REJECT chain, srcip, srcport, dstip, dstport, proto, log

 -- Firewall Primitive: DENY chain, srcip, srcport, dstip, dstport, proto, log

 -- Firewall Primitive: LIST

 -- Firewall Primitive: port_setup rule ip

Manage PHP Sessions
===================

The script session-cleanup provides flexible garbage collection for PHP session files. It is designed first of all for managing session files stored in a deep directory structrure (i.e. when session.save_path = N;path in php.ini), for which the built-in PHP garbage collection is turned off. Beside this, session-cleanup allows to set up different TTL (time to live) intervals for different session files, based on their contents.

The script should be started at regular intervals as a cron job. Upon startup it obtains the value of session.save_path variable from /etc/apache/php.ini. If your php.ini is located elsewhere, specify its exact location using -c command line option. Then session-cleanup scans the storage directory and removes session files that were created more than TTL days ago. The exact value of TTL is determined using following rules:

 1. If the command line contains a non-option argument, it is taken as a name of configuration file. This file is scanned for a line that matches the contents of the session file. If such a line is found, it determines the TTL for this session.

 2. If -t is given in the command line, its argument specifies TTL.

 3. Otherwise, default value of 3 days is used.

Configuration file has a simple line-oriented syntax. Blank lines and lines that begin with a hash character (#) are ignored. The rest of lines is split into two fields. First field specifies a regular expression to search for in the session file. Second field gives the TTL value in days for files that match this regular expression. The first matching line is used.

A sample configuration file follows:

     # Regex                 TTL (days)

     ^gallery_session_.*     1
     mprogh                  62

If a regular expression contains whitespace, use shell escapes or quotes to protect it.

Syntax
------

     session-cleanup OPTIONS [CONFIG-FILE]

OPTIONS are:

-c FILE
     Use FILE instead of /etc/apache/php.ini.

-h
     Display a short help summary.

-n
     Dry run. Only display which files will be removed, do not actually remove them.

-t TTL
     Set default session time to live. TTL is measured in days.

-v
     Verbose mode. Useful for debugging in conjunction with -n.

Startup Scripts
***************

This chapter describes several startup files, designed mainly for GNU/Linux. To use any of them, first read its description, then copy it to the location where your startup scripts reside (/etc/rc.d on Slackware) and make sure it is executed at startup. Then follow the script-specific recommendations set forth in the corresponding section.

rc.inet1
========

The startup script rc.inet1 sets up network interfaces. It was thought as a replacement for Slackware startup script with the same name, which I find extremely inconvenient.

To use the script, copy it to the location where your startup scripts reside (/etc/rc.d on Slackware) and make sure it is executed at startup. The script itself does not use any configuration files. Instead, it consists of configurable and immutable parts. Both parts are clearly separated with appropriate comments.

Configurable part contains a set of variable definitions. The variables are:

 -- Variable: if_list
     This variable contains a whitespace separated list of interface names to be configured. For example:

          if_list="lo eth0"

     Each interface name must itself be a valid shell variable name. Names of almost all existing interfaces meet this condition. The common exception are ethernet aliases, which on GNU/Linux contain colon. To list such an interface name, replace the colon with underscore. For example to configure interfaces lo, eth0 and eth0:0, one would write:

          if_list="lo eth0 eth0_0"

     One more note: it is advisable to always keep lo in this list.

 -- Variable: if_IFACE
     For each interface name IFACE in if_list, there must be defined a variable named if_IFACE. The value of this variable must be an ifconfig command line initializing given interface. The name of the interface itself should be omitted from the command line. Given the previous example, one might write:

          # Configure three interfaces
          if_list="lo eth0 eth0_0"

          # Set up loopback interface
          if_lo="127.0.0.1"

          # Set up eth0
          if_eth0="inet 192.168.10.1 netmask 255.255.255.224\
                   broadcast 192.168.10.31"

          # Set up eth0:0
          if_eth0_0="inet 192.168.10.2 netmask 255.255.255.224\
                     broadcast 192.168.10.31"

 -- Variable: route_IFACE
     For each interface name IFACE in if_list, there can be defined a variable route_IFACE. If it is defined, it contains a route command line for setting up routing for this interface. Completing our previous example, for loopback interface one might write:

          if_lo"127.0.0.1"
          route_lo="add -net 127.0.0.0 netmask 255.0.0.0 lo"

 -- Variable: default_gw
     This variable defines IP address of the default gateway.

 -- Variable: static_routes
     The variable static_routes declares route identifiers for each static route to be set up. A route identifier is an arbitrary word consisting of alphanumeric characters and underscores. For each identifier ID in static_routes there must be declared variable route_ID, whose value is route command line for setting up this route. For example:

          static_routes="1"
          route_1="add -net 192.168.10.0 netmask 255.255.255.224 \
                   gw 192.168.10.10 metric 216 reject"

As other configuration scripts, this one should probably take a command line argument {start|stop|status}. For the time being it always behaves as if invoked with start

rc.autofs
=========

The script rc.autofs controls GNU/Linux automounter facility. It accepts a single mandatory command line argument:

start
     Start automounter.

stop
     Stop automounter.

status
     List configured and active automounter instances and mount points. Here is a sample output (long lines being split for readability):

          Configured Mount Points:
          ------------------------
          /usr/sbin/automount --timeout=1 \
                  /auto file /etc/automount/auto.misc

          Active Mount Points:
          --------------------
          1040 /usr/sbin/automount --timeout=1 \
                 /auto file /etc/automount/auto.misc

reload
     Reload current configuration, restarting automount daemon if necessary.

restart
     Unconditionally restart automount daemon.

The script assumes following full file names:

/usr/sbin/automount
     The name of the automount binary. Adjust DAEMON variable if it is located elsewhere.

/etc/automount
     Configuration directory. Adjust CFGDIR if you need another name.

/etc/automount/master
     The name of the master configuration file. Adjust CFGFILE variable if you need another name.

/var/lock/subsys/autofs
     The name of the lock directory. Adjust LOCKFILE variable if necessary.

rc.ntpd
=======

Rc.ntpd controls the network time protocol daemon. It takes a single mandatory command line argument:

start
     Start ntpd. Before starting it the script attempts to synchronize current date with the master servers by running ntpdate. If ntpdate fails, the script sleeps for a specified number of seconds and attempts to synchronize again. Such attempts are tried several times while increasing proportionally the initial delay between the attempts, so that the delay after Nth attempt is N times the initial one. Two configuration variables are provided to control this behavior: MAXRETRY sets the maximum number of attempts, TIMEOUT sets the initial delay in seconds. If all attempts fail, rc.ntpd sends a mail to root and exits without trying to launch ntpd.

stop
     Stop ntpd.

status
     List running ntpd instances and display current date/time difference between the local machine and its servers. points. Here is a sample output (long lines being split for readability):

          Running processes:
          ------------------
          1124 /usr/sbin/ntpd

          Current date diff:
          ------------------
          server 10.10.10.1, stratum 2, offset -0.008749, delay 0.13557

reload
restart
     Restart ntpd daemon.

The script assumes following full file names:

/usr/sbin/ntpd
     Name of the ntpd daemon. Kept in DAEMON variable.

/etc/ntp.conf
     Main ntpd configuration file. Kept in CONFIG variable.

The script searches ntpdate, mail and ps binaries using usual path mechanism. You may need to update PATH settings at the beginning of the script.

rc.local
========

The rc.local script manages local services.  For the purposes of this script, we call each service a component.  It is also supposed that the component management is handled by a script, that takes a single word as its argument.

A component name is used to locate its startup script.  If a component name is a single word, NAME, then rc.local assumes the script name is /etc/rc.d/rc.NAME.  Otherwise, if NAME is a full path name, then it is used as a script name.

Additionally, if component name has the form USER@NAME, where USER is a valid user name and NAME is as described above, then the script will be executed with the privileges of USER.

The following table provides an example of valid component names along with their description.

mailman
     The script is named /etc/rc.d/rc.mailman.

postmaster@mailman
     The script is named /etc/rc.d/rc.mailman and is executed with the privileges of the user postmaster.

/usr/local/etc/rc.d/rc.mailman
     The script is named /usr/local/etc/rc.d/rc.mta

postmaster@/usr/local/etc/rc.d/rc.mailman
     Same as above, but executed from the postmaster account.

local.conf file
---------------

The configuration file local.conf, located in /etc directory, contains the configuration for the rc.local. The syntax is very simple:

 1. Empty lines and comments are ignored.

 2. Comments begin with #.

 3. The file consists of one or more sections.

 4. Each section begins with [NAME] on a line by itself, and ends on the beginning of the next section, or end of file, whichever occurs first.  The NAME above is the section name.

 5. Each section contains a list of component names, each on a separate line.

The section named components is mandatory.  It contains names of all components managed by rc.local.  The components will be started in the same order as listed in the section, and stopped in the reverse order.  For example, given the following configuration file:

     [components]
     mta
     httpd
     postmaster@mailman

the order of startup is: mta, httpd, mailman. The order of shutdown is: mailman, httpd, mta.

Additional sections may be provided to specify inter-component dependency.  Such sections are named after a particular component and contain a list of components that depend on that component.  For example, consider this file:

     [components]
     map
     mysql
     mta
     httpd
     postmaster@mailman

     [mta]
     map
     mysql

The last section tells that mta component depends on components map and mysql.  If you run rc.local restart mta, then the following sequence of commands will be performed:

Inocation of rc.local.
----------------------

rc.firewall
===========

This startup script sets firewall using m4 firewall wrappers (see firewall). It tajes a single mandatory command line argument:

start
restart
     Set up firewall.

stop
     Flush all firewall rules.

status
     List all installed firewall rules.

check
test
     Produce a list of shell commands that will be used to set up firewall rules. Equivalent to rc.firewall -d start.

Option -d can be given before the argument to make rc.firewall produce a list of shell commands it would have used to perform a given task. For example

     rc.firewall -d start

prints commands that would be executed by rc.firewall start.

The script searches for m4 wrappers in /etc/firewall. This location can be changed by setting FWDIR environment variable.

The list of firewall rules is expected to be located in $FWDIR/rules.m4. This location can be changed by setting START environment variable.

rc.ipacct
=========

This script controls the ipacct daemon (-pxrefipacct). It takes a single mandatory command line argument indicating what action to take:

start
     Start the daemon.

stop
     Stop the daemon.

status
     Display PID of the current instance of ipacct.

restart
     Unconditionally restart the daemon.

reload
reconfigure
     Tell ipacct to re-read its configuration file.

The script searches for ipacct binary in the current PATH. Two variables defined at the beginning of the script control its behavior:

 -- Variable: IFACE
     Interface where to install ipacct. Default is eth0.

 -- Variable: PIDFILE
     Location of ipacct pid file. Default is /var/run/ipacct-IFACE.pid.

rc.ppp
======

This script sets up a set of PPP connections at start up. It reads configuration from the file /etc/ppp.conf. The configurations is expressed as a set of shell variables.

 -- Variable: ppp_list
     This variable contains a whitespace separated list of identifiers for PPP connections. Each identifier is an arbitrary word, such that it is a valid shell variable. For each identifier ID, the configuration file must declare a shell variable pppID_options, specifying command line options for pppd.

 -- Variable: pppID_options
     This variable specifies command line options for connection ID.

A sample ppp.conf file follows:

     ppp_list="0 1"
     ppp0_options="modem passive nodetach defaultroute crtscts \
      lock 192.168.0.1:192.168.0.2 /dev/ttyS0 9600"
     ppp1_options="modem lock 192.168.0.1:192.168.0.3 /dev/ttyS1 57600"

rc.tagr
=======

Rc.tagr controls tagr daemon (-pxreftagr). It takes a single mandatory command line argument indicating what action to take:

start
     Start the daemon.

stop
     Stop the daemon.

status
     Display PID of the current instance of tagr.

restart
     Unconditionally restart the daemon.

reload
reconfigure
     Tell tagr to re-read its configuration file.

The script searches for tagr binary in /usr/local/sbin/tagr and for its PID file in /var/run/tagr.pid. This can be changed by editing variables PROGRAM, PIDFILE and CMD at the beginning of the script.

User Tools
**********

dict-setup
==========

Dict-setup automates setting up a set of aspell dictonaries (see Overview (GNU Aspell Manual)). It takes a list of file names as its arguments. Each file must contain a list of languages for which spell checking dictionaries must be installed. The languages should be specified as ISO 639 language abbreviations, one per line. Empty lines and shell-style comments are ignored.

For each language, dict-setup downloads its latest spell checking dictionary from ftp://ftp.gnu.org.ua/gnu/aspell/dict, builds and installs it.

If you wish to use another URL, specify it via -u command line option, for example

     dict-setup -u ftp://ftp.gnu.org FILE

To save bandwidth, dict-setup looks for dictionaries compressed via bzip2 command. This can be altered by setting SUF variable to the desired file suffix, e.g. SUF=.tar.gz.

By default, dict-setup installs the latest dictionary version. If this behavior is not desired, you can select which dictionary to install by invoking the program with -c option.

When run with this option, dict-setup prints a list of available dictionaries for each language and allows you to select one for download (it uses lynx to display the list, so make sure it is in your PATH). Use following commands to navigate through the list:

v
     View index file.

x
     Do not install dictionaries for this language. Proceed to the next language.

q
     Abort installation immediately.

NUMBER
     Install NUMBERth dictionary from the list.

Following is the complete list of dict-setup options:

-c
     Run in confirm mode: for each language, present the user with a list of available dictionaries and allow him to select which one to install.

-h
     Print a short usage summary and exit.

-v
     Verbosely list each action executed.

-u URL
     Use URL instead of the default ftp://ftp.gnu.org.ua/gnu/aspell/dict.

consoleconf
===========

Consoleconf sets console encoding and input method, for both text and X consoles. The program uses kbd package (ftp://ftp.win.tue.nl/pub/linux-local/utils/kbd/).

Consoleconf consists of the following parts:

 1. consoleconf binary. It is normally installed as $prefix/consoleconf.

 2. Data directory with language definition files. It is normally installed as $datadir/consoleconf.

Usage of consoleconf is quite simple. Running:

     consoleconf LANG

sets up the console for language LANG, i.e. it sets keyboard map, optional screen map and screen font. Command line option -c can be used to specify encoding. For example:

     consoleconf -c latin1 no

The package is shipped with support for the following languages:

da
     Danish

es
     Spanish

el
     Greek

no
     Norwegian

pl
     Polish

ru
     Russian

uk
     Ukrainian

To add a new language, create its language description file describing how to set up the console for this language. I suggest to use two-letter language codes as per ISO 639. The file has a regular sh(1) syntax. It should define following variables:

 -- Variable: Consoleconf variable KEYMAP
     Specifies the name of the keymap to use. Keymaps are usually stored in /usr/share/kbd/keymaps/, although the exact location may vary.

 -- Variable: Consoleconf variable FONT
     Specifies the name of console font file to use when in text console. Console font files are usually located in /usr/share/kbd/consolefonts/, although the exact location may vary.

 -- Variable: Consoleconf variable X11
     Setxkbmap command line to use when under X11.

 -- Variable: Consoleconf variable MOTD
     Message of the day. It is displayed after the console is set up. If it starts with commercial at sign, it is taken as a name of file whose contents is the message of the day. The file is looked up in $datadir/consoleconf/motd.

     This variable is optional.

For example, the following is the definition of Polish language:

     KEYMAP=pl.map
     FONT="-m 8859-2 iso02.16.gz"
     X11="-rules xfree86 -model pc102 -layout pl"

ppp
===

This sub-package provides a framework for setting up a dial-up connection. At the core of it is start-ppp, a program which actually installs a connection. Various configuration data are supplied to it by several configuration files, normally located in /etc/ppp. When run, start-ppp interprets the file /etc/ppp/pppscript.m4 to determine various configuration settings for the modem. There is normally no need to edit this file, as the actual configuration data are stored in two files it includes: /etc/ppp/modem and /etc/ppp/login.

Modem configuration is kept in file /etc/ppp/modem. This file should define the following variables.

 -- Variable: MODEM_INITSTRING
     Initialization string for the modem.

 -- Variable: MODEM_TIMEOUT
     Default modem timeout in seconds.

 -- Variable: MODEM_DIALPREFIX
     Dial prefix, t for tone dialing, p for pulse dialing

 -- Variable: AREA_CODE
     Optional area code.

This file defines dial-up user credentials. These are kept in two variables:

 -- Variable: LOGIN
     Specifies user login name.

 -- Variable: PASSWORD
     Specifies user password.

Finally, the list of numbers to dial is supplied by file /etc/ppp/numbers. This file must contain one number per line. Empty lines and shell-style comments are allowed. The numbers from this file are tried in turn until dialing one of them succeeds or the end of file is reached. By default, start-ppp first looks up the file numbers in current working directory. If it is found, it is read instead of /etc/ppp/numbers.

How to Report a Bug
*******************

As I said, this is not a package on its own. Rather gsc is a collection of scripts for my own use. However, I will be pleased if you will find it useful, and even more pleased if you will send me your suggestions or bug reports. If you decide to do so, write to gray@gnu.org.ua.

As the purpose of bug reporting is to improve software, please be sure to include maximum information when reporting a bug. The mimimum information needed is:

  * Topmost date from the ChangeLog file.

  * Conditions under which the bug appears.

     [file fdl.texi not included]

Concept Index
*************

This is a general index of all issues discussed in this manual