ab2

NAME

ab - Apache HTTP server benchmarking tool

 

SYNOPSIS

 

ab [ -A auth-username:password ] [ -c concurrency ] [ -C cookie-name=value ] [ -d ] [ -e csv-file ] [ -g gnuplot-file ] [ -h ] [ -H custom-header ] [ -i ] [ -k ] [ -n requests ] [ -p POST-file ] [ -P proxy-auth-username:password ] [ -q ] [ -s ] [ -S ] [ -t timelimit ] [ -T content-type ] [ -v verbosity] [ -V ] [ -w ] [ -x <table>-attributes ] [ -X proxy[:port] ] [ -y <tr>-attributes ] [ -z <td>-attributes ] [http://]hostname[:port]/path
 

 

SUMMARY

 

ab is a tool for benchmarking your Apache Hypertext Transfer Protocol (HTTP) server. It is designed to give you an impression of how your current Apache installation performs. This especially shows you how many requests per second your Apache installation is capable of serving.
 

 

OPTIONS

 
 

-A auth-username:password

Supply BASIC Authentication credentials to the server. The username and password are separated by a single : and sent on the wire base64 encoded. The string is sent regardless of whether the server needs it (i.e., has sent an 401 authentication needed).

-c concurrency

Number of multiple requests to perform at a time. Default is one request at a time.

-C cookie-name=value

Add a Cookie: line to the request. The argument is typically in the form of a name=value pair. This field is repeatable.

-d

Do not display the "percentage served within XX [ms] table". (legacy support).

-e csv-file

Write a Comma separated value (CSV) file which contains for each percentage (from 1% to 100%) the time (in milliseconds) it took to serve that percentage of the requests. This is usually more useful than the `gnuplot` file; as the results are already `binned`.

-g gnuplot-file

Write all measured values out as a `gnuplot` or TSV (Tab separate values) file. This file can easily be imported into packages like Gnuplot, IDL, Mathematica, Igor or even Excell. The labels are on the first line of the file.

-h

Display usage information.

-H custom-header

Append extra headers to the request. The argument is typically in the form of a valid header line, containing a colon-separated field-value pair (i.e., "Accept-Encoding: zip/zop;8bit").

-i

Do HEAD requests instead of GET.

-k

Enable the HTTP KeepAlive feature, i.e., perform multiple requests within one HTTP session. Default is no KeepAlive.

-n requests

Number of requests to perform for the benchmarking session. The default is to just perform a single request which usually leads to non-representative benchmarking results.

-p POST-file

File containing data to POST.

-P proxy-auth-username:password

Supply BASIC Authentication credentials to a proxy en-route. The username and password are separated by a single : and sent on the wire base64 encoded. The string is sent regardless of whether the proxy needs it (i.e., has sent an 407 proxy authentication needed).

-q

When processing more than 150 requests, ab outputs a progress count on stderr every 10% or 100 requests or so. The -q flag will suppress these messages.

-s

When compiled in (ab -h will show you) use the SSL protected https rather than the http protocol. This feature is experimental and very rudimentary. You probably do not want to use it.

-S

Do not display the median and standard deviation values, nor display the warning/error messages when the average and median are more than one or two times the standard deviation apart. And default to the min/avg/max values. (legacy support).

-t timelimit

Maximum number of seconds to spend for benchmarking. This implies a -n 50000 internally. Use this to benchmark the server within a fixed total amount of time. Per default there is no timelimit.

-T content-type

Content-type header to use for POST data.

-v verbosity

Set verbosity level - 4 and above prints information on headers, 3 and above prints response codes (404, 200, etc.), 2 and above prints warnings and info.

-V

Display version number and exit.

-w

Print out results in HTML tables. Default table is two columns wide, with a white background.

-x <table>-attributes

String to use as attributes for <table>. Attributes are inserted <table here >.

-X proxy[:port]

Use a proxy server for the requests.

-y <tr>-attributes

String to use as attributes for <tr>.

-z <td>-attributes

String to use as attributes for <td>.
 

 

BUGS

 

There are various statically declared buffers of fixed length. Combined with the lazy parsing of the command line arguments, the response headers from the server and other external inputs, this might bite you.
 

It does not implement HTTP/1.x fully; only accepts some `expected` forms of responses. The rather heavy use of strstr(3) shows up top in profile, which might indicate a performance problem; i.e., you would measure the ab performance rather than the server`s.
 

accton

NAME

accton - turns process accounting on or off  

SYNOPSIS

accton

[ -V | --version ] [ -h | --help ] [ filename ]

 

DESCRIPTION

accton filename turns on process accounting. If called with no arguments, it will, by default, stop process accounting.  

OPTIONS

..PD 0

-V, --version

Print the version number of ac to standard output and quit.

-h, --help

Prints the usage string and default locations of system files to standard output and exits.

 

FILES

acct

The system wide process accounting file. See acct(5) (or pacct(5)) for further details.

 

AUTHOR

The GNU accounting utilities were written by Noel Cragg <noel@gnu.ai.mit.edu>. The man page was adapted from the accounting texinfo page by Susan Kleinmann <sgk@sgk.tiac.net>.  

SEE ALSO

acct(5), ac(8)

acpi_listen

NAME

acpi_listen - ACPI event listener  

SYNOPSIS

acpi_listen [options]

 

DESCRIPTION

acpid is the sysem-wide ACPI event catcher. acpi_listen is a simple shell-friendly tool which connects to acpid and listens for events. When an event occurs, acpi_listen will print it on stdout.

 

OPTIONS

-c, --count events

Receive up to a maximum number of ACPI events, then exit.

-s, --socketfile filename

This option changes the name of the UNIX domain socket which acpid opens. Default is /var/run/acpid.socket.

-t, --time seconds

Listen for the specified time in seconds, before exiting.

-v, --version

Print version information and exit.

-h, --help

Show help and exit.

 

FILES

/var/run/acpid.socket

 

BUGS

There are no known bugs. To file bug reports, see AUTHORS below.  

SEE ALSO

regcomp(3), sh(1), socket(2), connect(2)  

AUTHORS

Tim Hockin <thockin@sun.com>
Luca Capello <luca@pca.it>

actsyncd

NAME

actsyncd - run actsync to synchronize newsgroups  

SYNOPSIS

Please see the actsync(8) manual page.  

SEE ALSO

actsync(8)

adjtimex

NAME

adjtimex - display or set the kernel time variables  

SYNOPSIS

adjtimex [option]...  

DESCRIPTION

This program gives you raw access to the kernel time variables. For a machine connected to the Internet, or equipped with a precision oscillator or radio clock, the best way to regulate the system clock is with ntpd(8). For a standalone or intermittently connected machine, you may use adjtimex instead to at least correct for systematic drift.

Anyone may print out the time variables, but only the superuser may change them.

If your computer can be connected to the net, you might run ntpd for at least several hours and use adjtimex --print to learn what values of tick and freq it settled on. Alternately, you could estimate values using the CMOS clock as a reference (see the --compare and --adjust switches). You could then add a line to rc.local invoking adjtimex to set those parameters each time you reboot.  

OPTIONS

Options may be introduced by either - or --, and unique abbreviations may be used. Here is a summary of the options, grouped by type. Explanations follow.

Get/Set Kernel Time Parameters

-p --print -t --tick val -f newfreq --frequency newfreq -o val --offset val -s adjustment --singleshot adjustment -m val --maxerr val -e val --esterror val -T val --timeconstant val -a[count] --adjust[=count]

Estimate Systematic Drifts

-c[count] --compare[=count] -i tim --interval tim -l file --logfile file -h timeserver --host timeserver -w --watch -r[file] --review[=file] -u --utc

Informative Output

--help -v --version

-p, --print

Print the current values of the kernel time variables. NOTE: The time is "raw", and may be off by up to one timer tick (10 msec). "status" gives the value of the time_status variable in the kernel. For Linux 1.0 and 1.2 kernels, the value is as follows:

0 clock is synchronized (so the kernel should periodically set the CMOS clock to match the system clock) 1 inserting a leap second at midnight 2 deleting a leap second at midnight 3 leap second in progress 4 leap second has occurred 5 clock not externally synchronized (so the kernel should leave the CMOS clock alone)

For Linux 2.0 kernels, the value is a sum of these:

1 PLL updates enabled 2 PPS freq discipline enabled 4 PPS time discipline enabled 8 frequency-lock mode enabled 16 inserting leap second 32 deleting leap second 64 clock unsynchronized 128 holding frequency 256 PPS signal present 512 PPS signal jitter exceeded 1024 PPS signal wander exceeded 2048 PPS signal calibration error 4096 clock hardware fault

-t val, --tick val

Set the number of microseconds that should be added to the system time for each kernel tick interrupt. There are supposed to be 100 ticks per second, so val should be close to 10000. Increasing val by 1 speeds up the system clock by about 100 ppm, or 8.64 sec/day. tick must be in the range 9000...11000 on Intel systems, or 900...1100 on Alpha systems.

-f newfreq, --frequency newfreq

Set the system clock frequency offset to newfreq. newfreq can be negative or positive, and gives a much finer adjustment than the --tick switch. The value is scaled such that newfreq = 1<<16 speeds up the system clock by about 1 ppm, or .0864 sec/day. Thus, --tick 10000 --frequency 6553600 is about the same as --tick 10001 --frequency 0. newfreq must be in the range -6553600...6553600, allowing maximum adjustments of plus or minus 100 ppm.

-s adj, --singleshot adj

Slew the system clock by adj usec. (Its rate is changed temporarily by about 1 part in 2000.)

-o adj, --offset adj

Add a time offset of adj usec. The kernel code adjusts the time gradually by adj, notes how long it has been since the last time offset, and then adjusts the frequency offset to correct for the apparent drift. adj must be in the range -512000...512000.

-m val, --maxerror val

Set maximum error (usec).

-e val, --esterror val

Set estimated error (usec). The maximum and estimated error are not used by the kernel. They are merely made available to user processes via the adjtimex(2) system call.

-t val, --timeconstant val

Set phase locked loop (PLL) time constant. val determines the bandwidth or "stiffness" of the PLL. The effective PLL time constant will be a multiple of (1 << val). For room-temperature quartz oscillators, David Mills recommends the value 2, which corresponds to a PLL time constant of about 900 sec and a maximum update interval of about 64 sec. The maximum update interval scales directly with the time constant, so that at the maximum time constant of 6, the update interval can be as large as 1024 sec.

Values of val between zero and 2 give quick convergence; values between 2 and 6 can be used to reduce network load, but at a modest cost in accuracy.

-c[count], --compare[=count]

Periodically compare the system clock with the CMOS clock. After the first two calls, print values for tick and frequency offset that would bring the system clock into approximate agreement with the CMOS clock. CMOS clock readings are adjusted for systematic drift using using the correction in /etc/adjtime --- see hwclock(8). The interval between comparisons is 10 seconds, unless changed by the --interval switch. The optional argument is the number of comparisons. (If the argument is supplied, the "=" is required.)

-a[count], --adjust[=count]

By itself, same as --compare, except the recommended values are actually installed after every other comparison. With --review, the tick and frequency are set to the least-squares estimates. (In the latter case, any count value is ignored.)

-i tim, --interval tim

Set the interval in seconds between clock comparisons for the --compare and --adjust options.

-u, --utc

The CMOS clock is set to UTC (universal time) rather than local time.

-l[file], --log[=file]

Save the current values of the system and CMOS clocks, and optionally a reference time, to file (default /var/log/clocks.log). The reference time is taken from a network timeserver (see the --host switch) or supplied by the user (see the --watch switch).

-h timeserver, --host timeserver

Use ntpdate to query the given timeserver for the current time. This will fail if timeserver is not running a Network Time Protocol (NTP) server, or if that server is not synchronized. Implies --log.

-w, --watch

Ask for a keypress when the user knows the time, then ask what that time was, and its approximate accuracy. Implies --log.

-r[file], --review[=file]

Review the clock log file (default /var/log/clocks.log) and estimate, if possible, the rates of the CMOS and system clocks. Calculate least-squares rates using all suitable log entries. Suggest corrections to adjust for systematic drift. With --adjust, the frequency and tick are set to the suggested values. (The CMOS clock correction is not changed.)

-h, --help

Print the program options.

-v, --version

Print the program version.

 

EXAMPLES

If your system clock gained 8 seconds in 24 hours, you could set the tick to 9999, and then it would lose 0.64 seconds a day (that is, 1 tick unit = 8.64 seconds per day). To correct the rest of the error, you could set the frequency offset to (1<<16)*0.64/.0864 = 485452. Thus, putting the following in rc.local would approximately correct the system clock:

adjtimex --tick 9999 --freq 485452

 

NOTES

adjtimex adjusts only the system clock --- the one that runs while the computer is powered up. To set or regulate the CMOS clock, see hwclock(8).  

AUTHORS

Steven S. Dick <ssd@nevets.oau.org>, Jim Van Zandt <jrv@vanzandt.mv.com>.  

SEE ALSO

date(1L), gettimeofday(2), settimeofday(2), hwclock(8), ntpdate(8), ntpd(8), /usr/src/linux/include/linux/timex.h, /usr/src/linux/include/linux/sched.h, /usr/src/linux/kernel/time.c, /usr/src/linux/kernel/sched.c

adsl-setup

NAME

adsl-setup - Shell script to configure Roaring Penguin PPPoE client  

SYNOPSIS

adsl-setup

 

DESCRIPTION

adsl-setup is a shell script which prompts you for various pieces of information and sets up an /etc/sysconfig/network-scripts/ifcfg-ppp0 configuration script for the adsl-start, adsl-stop and adsl-connect scripts.

 

AUTHOR

adsl-setup was written by David F. Skoll <dfs@roaringpenguin.com>.

The pppoe home page is http://www.roaringpenguin.com/pppoe/.

 

SEE ALSO

pppoe(8), adsl-start(8), adsl-stop(8), adsl-connect(8), pppd(8), pppoe.conf(5), adsl-status(8), pppoe-sniff(8), pppoe-relay(8), pppoe-server(8)

adsl-status

NAME

adsl-status - Shell script to report on status of PPPoE link  

SYNOPSIS

adsl-status [config_file]

 

DESCRIPTION

adsl-status is a shell script which checks the status of the PPPoE link established by the Roaring Penguin user-space PPPoE client. If you omit config_file, the default file /etc/sysconfig/network-scripts/ifcfg-ppp0 is used.

 

AUTHOR

adsl-status was written by David F. Skoll <dfs@roaringpenguin.com>.

The pppoe home page is http://www.roaringpenguin.com/pppoe/.

 

SEE ALSO

pppoe(8), adsl-start(8), adsl-connect(8), pppd(8), pppoe.conf(5), adsl-setup(8), adsl-stop(8), pppoe-sniff(8), pppoe-relay(8), pppoe-server(8)

afpd

NAME

afpd - AppleTalk Filing Protocol daemon  

SYNOPSIS

afpd [ -duptDTvI ] [ -f defaultvolumes ] [ -s systemvolumes ] [ -n nbpname ] [ -c maxconnections ] [ -g guest ] [ -P pidfile ] [ -S port ] [ -L message ] [ -F config ] [ -U uams ] [ -m umask ]  

DESCRIPTION

afpd provides an AppleTalk Filing Protocol (AFP) interface to the Unix file system. It is normally started at boot time from /etc/rc. The list of volumes offered to the user is generated from /etc/atalk//AppleVolumes.system and one of /etc/atalk//AppleVolumes.default, ~/AppleVolumes, or ~/.AppleVolumes.

The AppleVolumes files is used to specify volumes to mount and file name extension mappings. It is formatted as follows, one specification per line:

pathname [ volumename ]
.extension [ type [ creator ] ]

If volumename is unspecified, the last component of pathname is used. No two volumes may have the same name. If type is unspecified `????` is used. If creator is unspecified `UNIX` is used. The extension `.` sets the default creator and type for otherwise untyped Unix files. Blank lines and lines beginning with `#` are ignored.  

OPTIONS

-d

Specifies that the daemon not fork, and that a trace of all AFP commands be written to stdout.

-f defaultvolumes

Specifies that defaultvolumes should be read for a list of default volumes to offer, instead of /etc/atalk//AppleVolumes.default.

-s systemvolumes

Specifies that systemvolumes should be read for a list of volume that all users will be offered, instead of /etc/atalk//AppleVolumes.system.

-u

Read the user`s AppleVolumes file first. This option causes volume names in the user`s AppleVolumes file to override volume names in the system`s AppleVolumes file. The default is to read the system AppleVolumes file first. Note that this option doesn`t effect the precendence of filename extension mappings: the user`s AppleVolumes file always has precedence.

-n nbpname

Specifies that nbpname should be used for NBP registration, instead of the first component of the hostname in the local zone.

-c maxconnections

Specifies the maximum number of connections to allow for this afpd. The default is 5.

-g guest

Specifies the name of the guest account. The default is ``nobody``.

-P pidfile

Specifies the file in which afpd stores its process id.

-p

Prevents clients from saving their passwords. (Equivalent to -nosavepasswd in afpd.conf.)

-t

Allows clients to change their passwords. (Equivalent to -setpasswd in afpd.conf.)

-D

Use DDP (AppleTalk) as transport protocol. (Equivalent to -ddp in afpd.cond.)

-T

Use TCP/IP as transport protocol. (Equivalent to -tcp in afpd.conf.)

-S port

Specifies the port to register with when doing AFPoverTCP. Defaults to 548. (Equivalent to -port in afpd.conf.)

-L message

Specifies the login message that will be sent to clients. (Equivalent to -loginmsg in afpd.conf.)

-F config

Specifies the configuration file to use. (Defaults to /etc/atalk//afpd.conf.)

-U uams

Comma-separated list of UAMs to use for the authentication process. (Equivalent to -uamlist in afpd.conf.)

-I

Use a platform specific icon. (Equivalent to -icon in afpd.conf.)

-m umask

Use this umask for the creation of folders in Netatalk.

-v

Print version information and exit.

 

AUTHENTICATION

afpd currently understands three User Authentication Methods (UAMs): NoUserAuthent, or guest, Cleartxt passwrd, and Kerberos IV. If a user uses NoUserAuthent, s/he will only be offered default volumes to mount, and will only be able to read and write files that are permitted to the guest user. The -G option disables NoUserAuthent. With Cleartxt passwd and Kerberos IV, afpd offers the user all volumes listed in ~/AppleVolumes. The user may also read and write all files that s/he normally could. Cleartxt passwd is not recommended for AFS use. Kerberos IV is recommended for AFS use. A forth, depricated UAM is also included in the distribution, AFS Kerberos.  

CAVEATS

afpd`s Directory IDs are only fixed for the duration of a session. This means that Mac aliases won`t work correctly in all cases.

If a user renames a folder that has an application as its progeny, the APPL mapping for the application will not longer be available. This implies that double-clicking on one of the application`s documents will no longer launch the application. The APPL mapping will be rebuilt by the mac, the next time the Finder see the application.

If afpd is configured to downcase Macintosh filenames, Unix filenames with mixed case will be unavailable.

If carriage return/line feed translation is enabled, it is not safe to copy Unix binaries to a Macintosh.

It is not possible to move directories between devices.

When mounting the parent of an existing volume, the desktop database of the existing volume will not be available to the parent volume. The APPL mappings and icons of applications with the BNDL bit set will be generated in the parent volume as the applications are seen by the Finder.

If a user edits his ~/AppleVolumes so that his home directory is no longer offered, he will no longer be able to edit his ~/AppleVolumes from the Macintosh.

Unix files beginning with `.` are not accessible from the mac.

If the pathname in an ~/AppleVolumes file does not exist, the volume will not be offered in the Chooser.

Microsoft Word TEXT documents do not get carriage return/line feed translation. This is because MS Word uses a type other than TEXT while writing the document, then changes the type to TEXT. To allow users to edit their ~/AppleVolumes, afpd parses the files with either end of line character.

Unix filenames that are longer than 31 characters are inaccessible from the Macintosh.

 

SIGNALS

Signals that are sent to the main afpd process are propagated to the children, so all will be affected.

SIGHUP

The afpd process will send the message "The server is going down for maintenance." to the client and shut itself down in 5 minutes. New connections are not allowed. If this is sent to a child afpd, the other children are not affected. However, the main process will still exit, disabling all new connections.

SIGUSR1

If the --with-message-dir configure option was used, the afpd process will set the debug option and redirect the messages to /var/tmp/afpd-debug-pid. This should only be sent to a child afpd. Warning: If the --with-message-dir option was not used, this will kill the afpd process.

SIGUSR2

The afpd process will look in the msg directory for a file named message.pid. For each one found, a the contents will be sent as a message to the associated AFP client. The file is removed after the message is sent.

 

FILES

/etc/atalk//AppleVolumes.default

list of default volumes to mount

/etc/atalk//AppleVolumes.system

list of volumes to offer all users

~/AppleVolumes

user`s list of volumes to mount

/etc/atalk//msg/message.pid

contains messages to be sent to users.

/var/tmp/afpd-debug-pid

contains debug output, if triggered.

 

BUGS

A few calls from the AFP specification are not implemented, because the Macintosh does not use them.

alternatives

NAME

alternatives - maintain symbolic links determining default commands  

SYNOPSIS

alternatives [options] --install link name path priority [--slave link name path]... [--initscript service]

alternatives [options] --remove name path

alternatives [options] --set name path

alternatives [options] --auto name

alternatives [options] --display name

alternatives [options] --config name  

DESCRIPTION

alternatives creates, removes, maintains and displays information about the symbolic links comprising the alternatives system. The alternatives system is a reimplementation of the Debian alternatives system. It was rewritten primarily to remove the dependence on perl; it is intended to be a drop in replacement for Debian`s update-dependencies script. This man page is a slightly modified version of the man page from the Debian project.

It is possible for several programs fulfilling the same or similar functions to be installed on a single system at the same time. For example, many systems have several text editors installed at once. This gives choice to the users of a system, allowing each to use a different editor, if desired, but makes it difficult for a program to make a good choice of editor to invoke if the user has not specified a particular preference.

The alternatives system aims to solve this problem. A generic name in the filesystem is shared by all files providing interchangeable functionality. The alternatives system and the system administrator together determine which actual file is referenced by this generic name. For example, if the text editors ed(1) and nvi(1) are both installed on the system, the alternatives system will cause the generic name /usr/bin/editor to refer to /usr/bin/nvi by default. The system administrator can override this and cause it to refer to /usr/bin/ed instead, and the alternatives system will not alter this setting until explicitly requested to do so.

The generic name is not a direct symbolic link to the selected alternative. Instead, it is a symbolic link to a name in the alternatives directory, which in turn is a symbolic link to the actual file referenced. This is done so that the system administrator`s changes can be confined within the /etc directory: the FHS (q.v.) gives reasons why this is a Good Thing.

When each package providing a file with a particular functionality is installed, changed or removed, alternatives is called to update information about that file in the alternatives system. alternatives is usually called from the %post or %pre scripts in RPM packages.

It is often useful for a number of alternatives to be synchronised, so that they are changed as a group; for example, when several versions of the vi(1) editor are installed, the man page referenced by /usr/share/man/man1/vi.1 should correspond to the executable referenced by /usr/bin/vi. alternatives handles this by means of master and slave links; when the master is changed, any associated slaves are changed too. A master link and its associated slaves make up a link group.

Each link group is, at any given time, in one of two modes: automatic or manual. When a group is in automatic mode, the alternatives system will automatically decide, as packages are installed and removed, whether and how to update the links. In manual mode, the alternatives system will not change the links; it will leave all the decisions to the system administrator.

Link groups are in automatic mode when they are first introduced to the system. If the system administrator makes changes to the system`s automatic settings, this will be noticed the next time alternatives is run on the changed link`s group, and the group will automatically be switched to manual mode.

Each alternative has a priority associated with it. When a link group is in automatic mode, the alternatives pointed to by members of the group will be those which have the highest priority.

When using the --config option, alternatives will list all of the choices for the link group of which given name is the master link. You will then be prompted for which of the choices to use for the link group. Once you make a change, the link group will no longer be in auto mode. You will need to use the --auto option in order to return to the automatic state.  

TERMINOLOGY

Since the activities of alternatives are quite involved, some specific terms will help to explain its operation.

generic name

A name, like /usr/bin/editor, which refers, via the alternatives system, to one of a number of files of similar function.

symlink

Without any further qualification, this means a symbolic link in the alternatives directory: one which the system administrator is expected to adjust.

alternative

The name of a specific file in the filesystem, which may be made accessible via a generic name using the alternatives system.

alternatives directory

A directory, by default /etc/alternatives, containing the symlinks.

administrative directory

A directory, by default /var/lib/alternatives, containing alternatives` state information.

link group

A set of related symlinks, intended to be updated as a group.

master link

The link in a link group which determines how the other links in the group are configured.

slave link

A link in a link group which is controlled by the setting of the master link.

automatic mode

When a link group is in automatic mode, the alternatives system ensures that the links in the group point to the highest priority alternatives appropriate for the group.

manual mode

When a link group is in manual mode, the alternatives system will not make any changes to the system administrator`s settings.

 

OPTIONS

Exactly one action must be specified if alternatives is to perform any meaningful task. Any number of the common options may be specified together with any action.  

COMMON OPTIONS

--verbose

Generate more comments about what alternatives is doing.

--quiet

Don`t generate any comments unless errors occur. This option is not yet implemented.

--test

Don`t actually do anything, just say what would be done. This option is not yet implemented.

--help

Give some usage information (and say which version of alternatives this is).

--version

Tell which version of alternatives this is (and give some usage information).

--altdir directory

Specifies the alternatives directory, when this is to be different from the default.

--admindir directory

Specifies the administrative directory, when this is to be different from the default.

 

ACTIONS

--install link name path pri [--slave slink sname spath] [--initscript service]...

Add a group of alternatives to the system. name is the generic name for the master link, link is the name of its symlink, and path is the alternative being introduced for the master link. sname, slink and spath are the generic name, symlink name and alternative for a slave link, and service is the name of any associated initscript for the alternative. NOTE: --initscript is a Red Hat Linux specific option. Zero or more --slave options, each followed by three arguments, may be specified.

If the master symlink specified exists already in the alternatives system`s records, the information supplied will be added as a new set of alternatives for the group. Otherwise, a new group, set to automatic mode, will be added with this information. If the group is in automatic mode, and the newly added alternatives` priority is higher than any other installed alternatives for this group, the symlinks will be updated to point to the newly added alternatives.

If --initscript is used, the alternatives system will manage the initscript associated with the alternative via chkconfig, registering and unregistering the init script depending on which alternative is active.

NOTE: --initscript is a Red Hat Linux specific option.

--remove name path

Remove an alternative and all of its associated slave links. name is a name in the alternatives directory, and path is an absolute filename to which name could be linked. If name is indeed linked to path, name will be updated to point to another appropriate alternative, or removed if there is no such alternative left. Associated slave links will be updated or removed, correspondingly. If the link is not currently pointing to path, no links are changed; only the information about the alternative is removed.

--set name path

The symbolic link and slaves for link group name set to those configured for path, and the link group is set to manual mode. This option is not in the original Debian implementation.

--auto name

Switch the master symlink name to automatic mode. In the process, this symlink and its slaves are updated to point to the highest priority installed alternatives.

--display name

Display information about the link group of which name is the master link. Information displayed includes the group`s mode (auto or manual), which alternative the symlink currently points to, what other alternatives are available (and their corresponding slave alternatives), and the highest priority alternative currently installed.

 

FILES

/etc/alternatives/

The default alternatives directory. Can be overridden by the --altdir option.

/var/lib/alternatives/

The default administration directory. Can be overridden by the --admindir option.

 

EXIT STATUS

0

The requested action was successfully performed.

2

Problems were encountered whilst parsing the command line or performing the action.

 

DIAGNOSTICS

alternatives chatters incessantly about its activities on its standard output channel. If problems occur, alternatives outputs error messages on its standard error channel and returns an exit status of 2. These diagnostics should be self-explanatory; if you do not find them so, please report this as a bug.  

BUGS

If you find a bug, please report it using the Red Hat bug tracking system at http://bugzilla.redhat.com.

If you find any discrepancy between the operation of alternatives and this manual page, it is a bug, either in the implementation or the documentation; please report it. Any significant differences between this implementation and Debian`s is also a bug and should be reported, unless otherwise noted in this man page.  

AUTHOR

alternatives is copyright 2002 Red Hat, Inc.. It is free software; see the GNU General Public Licence version 2 or later for copying conditions. There is NO warranty.

This manual page is copyright 1997/98 Charles Briscoe-Smith and 2002 Red Hat, Inc. This is free documentation; see the GNU General Public Licence version 2 or later for copying conditions. There is NO WARRANTY.  

SEE ALSO

ln(1), FHS, the Filesystem Hierarchy Standard.

amanda

NAME

amanda - Advanced Maryland Automatic Network Disk Archiver  

SYNOPSIS

amdump config
amflush [ -f ] config
amcleanup config
amrecover [ config ] [ options ]
amrestore [ options ] tapedevice [ hostname [ diskname ]]
amlabel config label [ slot slot ]
amcheck [ options ] config
amadmin config command [ options ]
amtape config command [ options ]
amverify config
amrmtape [ options ] config label
amstatus config [ options ]
amoverview config [ options ]
amplot [ options ] amdump-files
amreport [ config ] [ options ]
amtoc [ options ] logfile
amcheckdb config
amgetconf [ config ] parameter
 

DESCRIPTION

Amanda is the "Advanced Maryland Automatic Network Disk Archiver". This manual page gives an overview of the Amanda commands and configuration files for quick reference.

Here are all the Amanda commands. Each one has its own manual page. See them for all the gory details.

amdump

Take care of automatic Amanda backups. This is normally executed by cron on a computer called the tape server host and requests backups of file systems located on backup clients. Amdump backs up all disks in the disklist file (discussed below) to tape or, if there is a problem, to a special holding disk. After all backups are done, amdump sends mail reporting failures and successes.

amflush

Flush backups from the holding disk to tape. Amflush is used after amdump has reported it could not write backups to tape for some reason. When this happens, backups stay in the holding disk. Run amflush after the tape problem is corrected to write backups from the holding disk to tape.

amcleanup

Clean up after an interrupted amdump. This command is only needed if amdump was unable to complete for some reason, usually because the tape server host crashed while amdump was running.

amrecover

Provides an interactive interface to browse the Amanda index files (backup image catalogues) and select which tapes to recover files from. It can also run amrestore and a restore program (e.g. tar) to actually recover the files.

amrestore

Read an Amanda tape, searching for requested backups. Amrestore is suitable for everything from interactive restores of single files to a full restore of all partitions on a failed disk.

amlabel

Write an Amanda format label onto a tape. All Amanda tapes must be labeled with amlabel. Amdump and amflush will not write to an unlabeled tape (see TAPE MANAGEMENT below).

amcheck

Verify the correct tape is mounted and all file systems on all backup client systems are ready to be backed up. Often run by cron before amdump to generate a mail warning that backups might fail unless corrective action is taken.

amadmin

Take care of administrative tasks like finding out which tapes are needed to restore a filesystem, forcing hosts to do full backups of selected disks and looking at schedule balance information.

amtape

Take care of tape changer control operations like loading particular tapes, ejecting tapes and scanning the tape storage slots.

amverify

Check Amanda backup tapes for errors.

amrmtape

Delete a tape from the Amanda databases.

amstatus

Report the status of a running or completed amdump.

amoverview

Display a chart of hosts and file systems backed up every run.

amplot

Generate utilization plots of Amanda runs for performance tuning.

amreport

Generate an Amanda summary E-mail report.

amtoc

Generate table of content files for Amanda tapes.

amcheckdb

Verify every tape Amanda knows about is consistent in the database.

amgetconf

Look up parameters in the Amanda configuration file.

 

CONFIGURATION

There are three user-editable files that control the behavior of Amanda. The first is amanda.conf, the main configuration file. It contains parameters to customize Amanda for the site. Second is the disklist file, which lists hosts and disk partitions to back up. Third is the tapelist file, which lists tapes that are currently active. These files are described in more detail in the following sections.

All files are stored in individual configuration directories under /etc/amanda. A site will often have more than one configuration. For example, it might have a normal configuration for everyday backups and an archive configuration for infrequent full archival backups. The configuration files would be stored under directories /etc/amanda/normal/ and /etc/amanda/archive/, respectively. Part of the job of an Amanda administrator is to create, populate and maintain these directories.

All log and database files generated by Amanda go in corresponding directories somewhere. The exact location is controlled by entries in amanda.conf. A typical location would be under /var/adm/amanda. For the above example, the files might go in /var/adm/amanda/normal/ and /var/adm/amanda/archive/.

As log files are no longer needed (no longer contain relevant information), Amanda cycles them out in various ways, depending on the type of file.

Detailed information about amdump runs are stored in files named amdump.NN where NN is a sequence number, with 1 being the most recent file. Amdump rotates these files each run, keeping roughly the last tapecycle (see below) worth of them.

The file used by amreport to generate the mail summary is named log.YYYYMMDD.NN where YYYYMMDD is the datestamp of the start of the amdump run and NN is a sequence number started at 0. At the end of each amdump run, log files for runs whose tapes have been reused are renamed into a subdirectory of the main log directory (see the logdir parameter below) named oldlog. It is up to the Amanda administrator to remove them from this directory when desired.

Index (backup image catalogue) files older than the full dump matching the oldest backup image for a given client and disk are removed by amdump at the end of each run.  

CONFIG FILE PARAMETERS

There are a number of configuration parameters that control the behavior of the Amanda programs. All have default values, so you need not specify the parameter in amanda.conf if the default is suitable.

Lines starting with # are ignored, as are blank lines. Comments may be placed on a line with a directive by starting the comment with a #. The remainder of the line is ignored.

Keywords are case insensitive, i.e. mailto and MailTo are treated the same.

Integer arguments may have one of the following (case insensitive) suffixes, some of which have a multiplier effect:

b byte bytes

Some number of bytes.

bps

Some number of bytes per second.

k kb kbyte kbytes kilobyte kilobytes

Some number of kilobytes (bytes*1024).

kps kbps

Some number of kilobytes per second (bytes*1024).

m mb meg mbyte mbytes megabyte megabytes

Some number of megabytes (bytes*1024*1024).

mps mbps

Some number of megabytes per second (bytes*1024*1024).

g gb gbyte gbytes gigabyte gigabytes

Some number of gigabytes (bytes*1024*1024*1024).

tape tapes

Some number of tapes.

day days

Some number of days.

week weeks

Some number of weeks (days*7).

The value inf may be used in most places where an integer is expected to mean an infinite amount.

Boolean arguments may have any of the values y, yes, t, true or on to indicate a true state, or n, no, f, false or off to indicate a false state. If no argument is given, true is assumed.

org "string"

Default: DailySet1. A descriptive name for the configuration. This string appears in the Subject line of mail reports. Each Amanda configuration should have a different string to keep mail reports distinct.

mailto "string"

Default: operators. A space separated list of recipients for mail reports.

dumpcycle int

Default: 10 days. The number of days in the backup cycle. Each disk will get a full backup at least this often. Setting this to zero tries to do a full backup each run.

Note that this parameter may also be set in a specific dumptype (see below). This value sets the default for all dumptypes so must appear in amanda.conf before any dumptypes are defined.

runspercycle int

Default: same as dumpcycle. The number of amdump runs in dumpcycle days. A value of 0 means the same value as dumpcycle. A value of -1 means guess the number of runs from the tapelist file, which is the number of tapes used in the last dumpcycle days / runtapes.

tapecycle int

Default: 15 tapes. The mininum number of tapes in the active tape cycle. You can have more tapes in your active tape cycle. It means that you must write at least tapecycle tape before a tape is overwritten. A tape marked as no-reuse is not in the active tape cycle.

Amanda will accept any tape for writting if it is not in the last tapecycle tapes used.

This must be at least one larger than the number of Amanda runs done during a dump cycle (see the dumpcycle parameter) times the number of tapes used per run (see the runtapes parameter).

For instance, if dumpcycle is set to 14 days, one Amanda run is done every day (Sunday through Saturday), and runtapes is set to one, then tapecycle must be at least 15 (14 days * one run/day * one tape/run + one tape).

In practice, there should be several extra tapes to allow for schedule adjustments or disaster recovery.

dumpuser "string"

Default: amanda. The login name Amanda uses to run the backups. The backup client hosts must allow access from the tape server host as this user via .rhosts or .amandahosts, depending on how the Amanda software was built.

printer "string"

Printer to use when doing tape labels. See the lbl-templ tapetype option.

tapedev "string"

Default: /dev/null. The path name of the non-rewinding tape device. Non-rewinding tape device names often have an `n` in the name, e.g. /dev/rmt/0mn, however this is operating system specific and you should consult that documentation for detailed naming information.

If a tape changer is configured (see the tpchanger option), this option might not be used.

If the null output driver is selected (see the OUTPUT DRIVERS section later for more information), programs such as amdump will run normally but all images will be thrown away. This should only be used for debugging and testing, and probably only with the record option set to no.

rawtapedev "string"

Default: /dev/null. The path name of the raw tape device. This is only used if Amanda is compiled for Linux machines with floppy tapes and is needed for QIC volume table operations.

tpchanger "string"

Default: none. The name of the tape changer. If a tape changer is not configured, this option is not used and should be commented out of the configuration file.

If a tape changer is configured, choose one of the changer scripts (e.g. chg-scsi) and enter that here.

changerdev "string"

Default: /dev/null. A tape changer configuration parameter. Usage depends on the particular changer defined with the tpchanger option.

changerfile "string"

Default: /usr/adm/amanda/log/changer-status. A tape changer configuration parameter. Usage depends on the particular changer defined with the tpchanger option.

runtapes int

Default: 1. The maximum number of tapes used in a single run. If a tape changer is not configured, this option is not used and should be commented out of the configuration file.

If a tape changer is configured, this may be set larger than one to let Amanda write to more than one tape.

Note that this is an upper bound on the number of tapes, and Amanda may use less.

Also note that as of this release, Amanda does not support true tape overflow. When it reaches the end of one tape, the backup image Amanda was processing starts over again on the next tape.

maxdumpsize int

Default: runtapes*tape_length. Maximum number of bytes the planner will schedule for a run.

taperalgo [first|firstfit|largest|largestfit|smallest|last]

Default: first. The algorithm use to choose which dump image to send to the taper.

first

First in first out.

firstfit

The first dump image that will fit on the current tape.

largest

The largest dump image.

largestfit

The largest dump image that will fit on the current tape.

smallest

The smallest dump image.

last

Last in first out.

labelstr "string" Default: .*. The tape label constraint regular expression. All tape labels generated (see amlabel(8)) and used by this configuration must match the regular expression. If multiple configurations are run from the same tape server host, it is helpful to set their labels to different strings (for example, "DAILY[0-9][0-9]*" vs. "ARCHIVE[0-9][0-9]*") to avoid overwriting each other`s tapes.

tapetype "string"

Default: EXABYTE. The type of tape drive associated with tapedev or tpchanger. This refers to one of the defined tapetypes in the config file (see below), which specify various tape parameters, like the length, filemark size, and speed of the tape media and device.

ctimeout int

Default: 30 seconds. Maximum amount of time that amcheck will wait for each client host.

dtimeout int

Default: 1800 seconds. Amount of idle time per disk on a given client that a dumper running from within amdump will wait before it fails with a data timeout error.

etimeout int

Default: 300 seconds. Amount of time per disk on a given client that the planner step of amdump will wait to get the dump size estimates. For instance, with the default of 300 seconds and four disks on client A, planner will wait up to 20 minutes for that machine. A negative value will be interpreted as a total amount of time to wait per client instead of per disk.

netusage int

Default: 300 Kbps. The maximum network bandwidth allocated to Amanda, in Kbytes per second. See also the interface section.

inparallel int

Default: 10. The maximum number of backups that Amanda will attempt to run in parallel. Amanda will stay within the constraints of network bandwidth and holding disk space available, so it doesn`t hurt to set this number a bit high. Some contention can occur with larger numbers of backups, but this effect is relatively small on most systems.

dumporder "string"

Default: tttTTTTTTT. The priority order of each dumper:

s: smallest size S: largest size t: smallest time T: largest time b: smallest bandwidth B: largest bandwidth

maxdumps int

Default: 1. The maximum number of backups from a single host that Amanda will attempt to run in parallel. See also the inparallel option.

Note that this parameter may also be set in a specific dumptype (see below). This value sets the default for all dumptypes so must appear in amanda.conf before any dumptypes are defined.

bumpsize int

Default: 10 Mbytes. The minimum savings required to trigger an automatic bump from one incremental level to the next. If Amanda determines that the next higher backup level will be this much smaller than the current level, it will do the next level. See also the bumpmult option.

bumpmult float

Default: 1.5. The bump size multiplier. Amanda multiplies bumpsize by this factor for each level. This prevents active filesystems from bumping too much by making it harder to bump to the next level. For example, with the default bumpsize and bumpmult set to 2.0, the bump threshold will be 10 Mbytes for level one, 20 Mbytes for level two, 40 Mbytes for level three, and so on.

bumpdays int

Default: 2 days. To insure redundancy in the dumps, Amanda keeps filesystems at the same incremental level for at least bumpdays days, even if the other bump threshold criteria are met.

diskfile "string"

Default: disklist. The file name for the disklist file holding client hosts, disks and other client dumping information.

infofile "string"

Default: /usr/adm/amanda/curinfo. The file or directory name for the historical information database. If Amanda was configured to use DBM databases, this is the base file name for them. If it was configured to use text formated databases (the default), this is the base directory and within here will be a directory per client, then a directory per disk, then a text file of data.

logdir "string"

Default: /usr/adm/amanda. The directory for the amdump and log files.

indexdir "string"

Default /usr/adm/amanda/index. The directory where index files (backup image catalogues) are stored. Index files are only generated for filesystems whose dumptype has the index option enabled.

tapelist "string"

Default: tapelist. The file name for the active tapelist file. Amanda maintains this file with information about the active set of tapes.

tapebufs int

Default: 20. The number of buffers used by the taper process run by amdump and amflush to hold data as it is read from the network or disk before it is written to tape. Each buffer is a little larger than 32 KBytes and is held in a shared memory region.

reserve number

Default: 100(percent). The amount of holding-disk space that should not be used for full backups if no tape is available. By default, when there is no tape to write to, degraded mode (incremental) backups will be performed to the holding disk. If full backups should also be allowed in this case, the amount of holding disk space reserved for incrementals should be lowered.

autoflush bool

Default: off. Whether an amdump run will flush the dump already on holding disk to tape.

amrecover_do_fsf bool

Default: off. Amrecover will call amrestore with the -f flag for faster positioning of the tape.

amrecover_check_label bool

Default: off. Amrecover will call amrestore with the -l flag to check the label.

amrecover_changer "string"

Default: ``. Amrecover will use the changer if you use `settape <STRING>` and that string is the same as the amrecover_changer setting.

columnspec "string"

Defines the width of columns amreport should use. String is a comma (`,`) separated list of triples. Each triple consists of three parts which are separated by a equal sign (`=`) and a colon (`:`) (see the example). These three parts specify:

+

the name of the column, which may be:

Compress (compression ratio) Disk (client disk name) DumpRate (dump rate in KBytes/sec) DumpTime (total dump time in hours:minutes) HostName (client host name) Level (dump level) OrigKB (original image size in KBytes) OutKB (output image size in KBytes) TapeRate (tape writing rate in KBytes/sec) TapeTime (total tape time in hours:minutes)

+

the amount of space to display before the column (used to get whitespace between columns).

+

the width of the column itself. If set to a negative value, the width will be calculated on demand to fit the largest entry in this column.

Here is an example:

columnspec "Disk=1:18,HostName=0:10,OutKB=1:7"

The above will display the disk information in 18 characters and put one space before it. The hostname column will be 10 characters wide with no space to the left. The output KBytes column is seven characters wide with one space before it.

includefile "string"

Default: none. The name of an amanda configuration file to include within the current file. Useful for sharing dumptypes, tapetypes and interface definitions among several configurations.

 

HOLDINGDISK SECTION

The amanda.conf file may define one or more holding disks used as buffers to hold backup images before they are written to tape. The syntax is:

holdingdisk name { holdingdisk-option holdingdisk-value ... }

Name is a logical name for this holding disk.

The options and values are:

comment "string"

Default: none. A comment string describing this holding disk.

directory "disk"

Default: /dumps/amanda. The path to this holding area.

use int

Default: 0 Gb. Amount of space that can be used in this holding disk area. If the value is zero, all available space on the file system is used. If the value is negative, Amanda will use all available space minus that value.

chunksize int

Default: 1 Gb. Holding disk chunk size. Dumps larger than the specified size will be stored in multiple holding disk files. The size of each chunk will not exceed the specified value. However, even though dump images are split in the holding disk, they are concatenated as they are written to tape, so each dump image still corresponds to a single continuous tape section.

If 0 is specified, Amanda will create holding disk chunks as large as ((INT_MAX/1024)-64) Kbytes.

Each holding disk chunk includes a 32 Kbyte header, so the minimum chunk size is 64 Kbytes (but that would be really silly).

Operating systems that are limited to a maximum file size of 2 Gbytes actually cannot handle files that large. They must be at least one byte less than 2 Gbytes. Since Amanda works with 32 Kbyte blocks, and to handle the final read at the end of the chunk, the chunk size should be at least 64 Kbytes (2 * 32 Kbytes) smaller than the maximum file size, e.g. 2047 Mbytes.

 

DUMPTYPE SECTION

The amanda.conf file may define multiple sets of backup options and refer to them by name from the disklist file. For instance, one set of options might be defined for file systems that can benefit from high compression, another set that does not compress well, another set for file systems that should always get a full backup and so on.

A set of backup options are entered in a dumptype section, which looks like this:

define dumptype name { dumptype-option dumptype-value ... }

Name is the name of this set of backup options. It is referenced from the disklist file.

Some of the options in a dumptype section are the same as those in the main part of amanda.conf. The main option value is used to set the default for all dumptype sections. For instance, setting dumpcycle to 50 in the main part of the config file causes all following dumptype sections to start with that value, but the value may be changed on a section by section basis. Changes to variables in the main part of the config file must be done before (earlier in the file) any dumptypes are defined.

The dumptype options and values are:

auth "string"

Default: bsd. Type of authorization to perform between tape server and backup client hosts. May be krb4 to use Kerberos-IV authorization.

comment "string"

Default: none. A comment string describing this set of backup options.

comprate float [, float ]

Default: 0.50, 0.50. The expected full and incremental compression factor for dumps. It is only used if Amanda does not have any history information on compression rates for a filesystem, so should not usually need to be set. However, it may be useful for the first time a very large filesystem that compresses very little is backed up.

compress [client|server] "string"

Default: client fast. If Amanda does compression of the backup images, it can do so either on the backup client host before it crosses the network or on the tape server host as it goes from the network into the holding disk or to tape. Which place to do compression (if at all) depends on how well the dump image usually compresses, the speed and load on the client or server, network capacity, holding disk capacity, availability of tape hardware compression, etc.

For either type of compression, Amanda also allows the selection of two styles of compression. Best is the best compression available, often at the expense of CPU overhead. Fast is often not as good a compression as best, but usually less CPU overhead.

So the compress options line may be one of:

compress none compress [client] fast compress [client] best compress server fast compress server best

Note that some tape devices do compression and this option has nothing to do with whether that is used. If hardware compression is used (usually via a particular tape device name or mt option), Amanda (software) compression should be disabled.

dumpcycle int

Default: 10 days. The number of days in the backup cycle. Each disk using this set of options will get a full backup at least this often. Setting this to zero tries to do a full backup each run.

exclude [ list|file ][[optional][ append ][ "string" ]+]

Default: file. There is two exclude list exclude file and exclude list. With exclude file , the string is a gnutar exclude expression. With exclude list , the string is a file name on the client containing gnutar exclude expression.

All exclude expression are concatenated in one file and passed to gnutar as a --exclude-from argument.

With the append keyword, the string are appended to the current value of the list, without it, the string overwrite the list.

If optional is specified for exclude list, then amcheck will not complain if the file doesn`t exist or is not readable.

For exclude list, If the file name is relative, the disk name being backed up is prepended. So if this is entered:

exclude list ".amanda.excludes"

the actual file use would be /var/.amanda.excludes for a backup of /var, /usr/local/.amanda.excludes for a backup of /usr/local, and so on.

holdingdisk "boolean"

Default: yes. Whether a holding disk should be used for these backups or whether they should go directly to tape. If the holding disk is a portion of another file system that Amanda is backing up, that file system should refer to a dumptype with holdingdisk set to no to avoid backing up the holding disk into itself.

ignore "boolean"

Default: no. Whether disks associated with this backup type should be backed up or not. This option is useful when the disklist file is shared among several configurations, some of which should not back up all the listed file systems.

include [ list|file ][[optional][ append ][ "string" ]+]

Default: file ".". There is two include list include file and include list. With include file , the string is a glob expression. With include list , the string is a file name on the client containing glob expression.

All include expression are expanded by amanda and concatenated in one file and passed to gnutar as a --files-from argument. They must start with "./" and containing no other "/".

With the append keyword, the string are appended to the current value of the list, without it, the string overwrite the list.

If optional is specified for include list, then amcheck will not complain if the file doesn`t exist or is not readable.

For include list, If the file name is relative, the disk name being backed up is prepended.

index "boolean"

Default: no. Whether an index (catalogue) of the backup should be generated and saved in indexdir. These catalogues are used by the amrecover utility.

kencrypt "boolean"

Default: no. Whether the backup image should be encrypted by Kerberos as it is sent across the network from the backup client host to the tape server host.

maxdumps "int"

Default: 1. The maximum number of backups from a single host that Amanda will attempt to run in parallel. See also the main section inparallel option.

maxpromoteday "int"

Default: 10000. The Maximum number of day for a promotion, set it 0 if you don`t want promotion, set it to 1 or 2 if your disk get overpromoted.

priority "string"

Default: medium. When there is no tape to write to, Amanda will do incremental backups in priority order to the holding disk. The priority may be high(2), medium(1), low(0) or a number of your choice.

program "string"

Default: DUMP. The type of backup to perform. Valid values are DUMP for the native operating system backup program, and GNUTAR to use GNU tar or to do Samba PC backups.

record "boolean"

Default: yes. Whether to ask the backup program to update its database (e.g. /etc/dumpdates for DUMP or /var/lib/amanda/gnutar-lists for GNUTAR) of time stamps. This is normally enabled for daily backups and turned off for periodic archival runs.

skip-full "boolean"

Default: no. If true and planner has scheduled a full backup, these disks will be skipped, and full backups should be run off-line on these days. It was reported that Amanda only schedules level 1 incrementals in this configuration; this is probably a bug.

skip-incr "boolean"

Default: no. If true and planner has scheduled an incremental backup, these disks will be skipped.

starttime "int"

Default: none. Backups will not start until after this time of day. The value should be hh*100+mm, e.g. 6:30PM (18:30) would be entered as 1830.

strategy "string"

Default: standard. Strategy to use when planning what level of backup to run next. Values are:

standard

The standard Amanda schedule.

nofull

Never do full backups, only level 1 incrementals.

noinc

Never do incremental backups, only full dumps.

skip

Never do backups (useful when sharing the disklist file).

incronly

Only do incremental dumps. `amadmin force` should be used to tell Amanda that a full dump has been performed off-line, so that it resets to level 1. It is similar to skip-full, but with incronly full dumps may be scheduled manually. Unfortunately, it appears that Amanda will perform full backups with this configuration, which is probably a bug.

The following dumptype entries are predefined by Amanda:

define dumptype no-compress { compress none } define dumptype compress-fast { compress client fast } define dumptype compress-best { compress client best } define dumptype srvcompress { compress server fast } define dumptype bsd-auth { auth bsd } define dumptype krb4-auth { auth krb4 } define dumptype no-record { record no } define dumptype no-hold { holdingdisk no } define dumptype no-full { skip-full yes }

In addition to options in a dumptype section, one or more other dumptype names may be entered, which make this dumptype inherit options from other previously defined dumptypes. For instance, two sections might be the same except for the record option:

define dumptype normal { comment "Normal backup, no compression, do indexing" no-compress index yes maxdumps 2 } define dumptype testing { comment "Test backup, no compression, do indexing, no recording" normal record no }

Amanda provides a dumptype named global in the sample amanda.conf file that all dumptypes should reference. This provides an easy place to make changes that will affect every dumptype.  

TAPETYPE SECTION

The amanda.conf file may define multiple types of tape media and devices. The information is entered in a tapetype section, which looks like this in the config file:

define tapetype name { tapetype-option tapetype-value ... }

Name is the name of this type of tape medium/device. It is referenced from the tapetype option in the main part of the config file.

The tapetype options and values are:

comment "string"

Default: none. A comment string describing this set of tape information.

filemark "int"

Default: 1000 bytes. How large a file mark (tape mark) is, measured in bytes. If the size is only known in some linear measurement (e.g. inches), convert it to bytes using the device density.

length "int"

Default: 2000 kbytes. How much data will fit on a tape.

Note that this value is only used by Amanda to schedule which backups will be run. Once the backups start, Amanda will continue to write to a tape until it gets an error, regardless of what value is entered for length (but see the OUTPUT DRIVERS section later for exceptions).

blocksize "int"

Default: 32 kbytes. How much data will be written in each tape record. The minimum blocksize value is 32 KBytes. The maximum blocksize value is 32 KBytes. The maximum is set during configure with --with-maxtapeblocksize.

file-pad "boolean"

Default: true. If true, every record, including the last one in the file, will have the same length. This matches the way Amanda wrote tapes prior to the availability of this parameter. It may also be useful on devices that only support a fixed blocksize.

Note that the last record on the tape probably includes trailing null byte padding, which will be passed back to gzip, compress or the restore program. Most programs just ignore this (although possibly with a warning).

If this parameter is false, the last record in a file may be shorter than the block size. The file will contain the same amount of data the dump program generated, without trailing null byte padding. When read, the same amount of data that was written will be returned.

speed "int"

Default: 200 bps. How fast the drive will accept data, in bytes per second. This parameter is not currently used by Amanda.

lbl-templ "string"

A PostScript template file used by amreport to generate labels. Several sample files are provided with the Amanda sources in the example directory. See the amreport(8) man page for more information.

In addition to options, another tapetype name may be entered, which makes this tapetype inherit options from another tapetype. For instance, the only difference between a DLT4000 tape drive using Compact-III tapes and one using Compact-IV tapes is the length of the tape. So they could be entered as:

define tapetype DLT4000-III { comment "DLT4000 tape drives with Compact-III tapes" length 12500 mbytes # 10 Gig tapes with some compression filemark 2000 kbytes speed 1536 kps } define tapetype DLT4000-IV { DLT4000-III comment "DLT4000 tape drives with Compact-IV tapes" length 25000 mbytes # 20 Gig tapes with some compression }

 

INTERFACE SECTION

The amanda.conf file may define multiple types of network interfaces. The information is entered in an interface section, which looks like this:

define interface name { interface-option interface-value ... }

Name is the name of this type of network interface. It is referenced from the disklist file.

Note that these sections define network interface characteristics, not the actual interface that will be used. Nor do they impose limits on the bandwidth that will actually be taken up by Amanda. Amanda computes the estimated bandwidth each file system backup will take based on the estimated size and time, then compares that plus any other running backups with the limit as another of the criteria when deciding whether to start the backup. Once a backup starts, Amanda will use as much of the network as it can leaving throttling up to the operating system and network hardware.

The interface options and values are:

comment "string"

Default: none. A comment string describing this set of network information.

use "int"

Default: 300 Kbps. The speed of the interface in Kbytes per second.

In addition to options, another interface name may be entered, which makes this interface inherit options from another interface. At the moment, this is of little use.  

DISKLIST FILE

The disklist file determines which disks will be backed up by Amanda. The file usually contains one line per disk:

hostname diskname [ diskdevice ] dumptype [ spindle [ interface ] ]

All pair [ hostname diskname ] must be unique.

Lines starting with # are ignored, as are blank lines. The fields have the following meanings:

hostname

The name of the host to be backed up. If diskdevice refers to a PC share, this is the host Amanda will run the Samba smbclient program on to back up the share.

diskname

The name of the disk (a label). In most case, you set your diskname to the diskdevice and you don`t set the diskdevice. If you want multiple entry with the same diskdevice, you must set a different diskname for each entry. It`s the diskname that you use on command line for any amanda command. Look at the example/disklist file for example.

diskdevice

Default: same as diskname. The name of the disk device to be backed up. It may be a full device name, a device name without the /dev/ prefix, e.g. sd0a, or a mount point such as /usr.

It may also refer to a PC share by starting the name with two (forward) slashes, e.g. //some-pc/home. In this case, the program option in the associated dumptype must be entered as GNUTAR. It is the combination of the double slash disk name and program GNUTAR in the dumptype that triggers the use of Samba.

dumptype

Refers to a dumptype defined in the amanda.conf file. Dumptypes specify backup related parameters, such as whether to compress the backups, whether to record backup results in /etc/dumpdates, the disk`s relative priority, etc.

spindle

Default: -1. A number used to balance backup load on a host. Amanda will not run multiple backups at the same time on the same spindle, unless the spindle number is -1, which means there is no spindle restriction.

interface

Default: local. The name of a network interface definition in the amanda.conf file, used to balance network load.

Instead of naming a dumptype, it is possible to define one in-line, enclosing dumptype options within curly braces, one per line, just like a dumptype definition in amanda.conf. Since pre-existing dumptypes are valid option names, this syntax may be used to customize dumptypes for particular disks.

A line break must follow the left curly bracket.

For instance, if a dumptype named normal is used for most disks, but use of the holding disk needs to be disabled for the file system that holds it, this would work instead of defining a new dumptype:

hostname diskname [ diskdevice ] { normal holdingdisk no } [ spindle [ interface ] ]

 

TAPE MANAGEMENT

The tapelist file contains the list of tapes in active use. This file is maintained entirely by Amanda and should not be created or edited during normal operation. It contains lines of the form:

YYYYMMDD label flags

Where YYYYMMDD is the date the tape was written, label is a label for the tape as written by amlabel and flags tell Amanda whether the tape may be reused, etc (see the reuse options of amadmin).

Amdump and amflush will refuse to write to an unlabeled tape, or to a labeled tape that is considered active. There must be more tapes in active rotation (see the tapecycle option) than there are runs in the backup cycle (see the dumpcycle option) to prevent overwriting a backup image that would be needed to do a full recovery.  

OUTPUT DRIVERS

The normal value for the tapedev parameter, or for what a tape changer returns, is a full path name to a non-rewinding tape device, such as /dev/nst0 or /dev/rmt/0mn or /dev/nst0.1 or whatever conventions the operating system uses. Amanda provides additional application level drivers that support non-tradition tape simulatation or features. To access a specific output driver, set tapedev (or configure your changer to return) a string of the form driver:driver-info where driver is one of the supported drivers and driver-info is optional additional information needed by the driver.

The supported drivers are:

tape

This is the default driver. The driver-info is the tape device name. Entering /dev/rmt/0mn is really a short hand for tape:/dev/rmt/0mn.

null

This driver throws away anything written to it and returns EOF for any reads except a special case is made for reading a label, in which case a "fake" value is returned that Amanda checks for and allows through regardless of what you have set in labelstr. The driver-info field is not used and may be left blank:

tapedev "null:"

The length value from the associated tapetype is used to limit the amount of data written. When the limit is reached, the driver will simulate end of tape.

NOTE: this driver should only be used for debugging and testing, and probably only with the record option set to no.

rait

Redundant Array of Inexpensive (?) Tapes. Reads and writes tapes mounted on multiple drives by spreading the data across N-1 drives and using the last drive for a checksum. See docs/RAIT for more information.

The driver-info field describes the devices to use. Curly braces indicate multiple replacements in the string. For instance:

tapedev "rait:/dev/rmt/tps0d{4,5,6}n"

would use the following devices:

/dev/rmt/tps0d4n
/dev/rmt/tps0d5n
/dev/rmt/tps0d6n

file

This driver emulates a tape device with a set of files in a directory. The driver-info field must be the name of an existing directory. The driver will test for a subdirectory of that named data and return offline until it is present. When present, the driver uses two files in the data subdirectory for each tape file. One contains the actual data. The other contains record length information.

The driver uses a file named status in the file device directory to hold driver status information, such as tape position. If not present, the driver will create it as though the device is rewound.

The length value from the associated tapetype is used to limit the amount of data written. When the limit is reached, the driver will simulate end of tape.

One way to use this driver with a real device such as a CD is to create a directory for the file device and one or more other directories for the actual data. Create a symlink named data in the file directory to one of the data directories. Set the tapetype length to whatever the medium will hold.

When Amanda fills the file device, remove the symlink and (optionally) create a new symlink to another data area. Use a CD writer software package to burn the image from the first data area.

To read the CD, mount it and create the data symlink in the file device directory.

 

AUTHORIZATION

Amanda processes on the tape server host run as the dumpuser user listed in amanda.conf. When they connect to a backup client, they do so with an Amanda-specific protocol. They do not, for instance, use rsh or ssh directly.

On the client side, the amandad daemon validates the connection using one of several methods, depending on how it was compiled and on options it is passed:

.rhosts

Even though Amanda does not use rsh, it can use .rhosts-style authentication and a .rhosts file.

.amandahosts

This is essentially the same as .rhosts authentication except a different file, with almost the same format, is used. This is the default mechanism built into Amanda.

The format of the .amandahosts file is:

hostname [ username ]

If username is ommitted, it defaults to the user running amandad, i.e. the user listed in the inetd or xinetd configuration file.

Kerberos

Amanda may use the Kerberos authentication system. Further information is in the docs/KERBEROS file that comes with an Amanda distribution.

For Samba access, Amanda needs a file on the Samba server (which may or may not also be the tape server) named /etc/amandapass with share names, (clear text) passwords and (optional) domain names, in that order, one per line, whitespace separated. By default, the user used to connect to the PC is the same for all PC`s and is compiled into Amanda. It may be changed on a host by host basis by listing it first in the password field followed by a percent sign and then the password. For instance:

//some-pc/home normalpw //another-pc/disk otheruser%otherpw

With clear text passwords, this file should obviously be tightly protected. It only needs to be readable by the Amanda user on the Samba server.

Further information is in the docs/SAMBA file that comes with an Amanda distribution.  

HOST & DISK EXPRESSION

All host and disk arguments to programs are special expression. The command apply to all disk that match your arguments. This section describe the matcher.

The matcher match by word, each word is a glob expression, word are separated by the separator `.` for host and `/` for disk. You can anchor the expression at left with a `^`. You can anchor the expression at right with a `$`. The matcher is case insensitive for host but is case sensitive for disk. A match succeed if all word in your expression match contiguous word in the host or disk.

. word separator for a host / word separator for a disk ^ anchor at left $ anchor at right ? match exactly one character except the separator * match zero or more characters except the separator ** match zero or more characters including the separator

Some examples:

EXPRESSION WILL MATCH WILL NOT MATCH hosta hosta hostb hoSTA.dOMAIna.ORG foo.hosta.org host host hosta host? hosta host hostb ho*na hoina ho.aina.org ho**na hoina ho.aina.org ^hosta hosta foo.hosta.org sda* /dev/sda1 /dev/sda12 /opt/ opt (disk) opt (host) .opt. opt (host) opt (disk) / / any other disk /usr /usr /usr/opt /usr$ /usr /usr/opt

 

DATESTAMP EXPRESSION

A datestamp expression is a range expression where we only match the prefix. Leading ^ is removed. Trailing $ force an exact match.

20001212-14 match all dates beginning with 20001212, 20001213 or 20001214 20001212-4 same as previous 20001212-24 match all dates between 20001212 and 20001224 2000121 match all dates that start with 2000121 (20001210-20001219) 2 match all dates that start with 2 (20000101-29991231) 2000-10 match all dates between 20000101-20101231 200010$ match only 200010

 

AUTHOR

James da Silva <jds@cs.umd.edu>
University of Maryland, College Park  

SEE ALSO

amadmin(8), amcheck(8), amcheckdb(8), amcleanup(8), amdd(8), amdump(8), amflush(8), amgetconf(8), amlabel(8), ammt(8), amoverview(8), amplot(8), amrecover(8), amreport(8), amrestore(8), amrmtape(8), amstatus(8), amtape(8), amtoc(8), amverify(8), amverifyrun(8)

amcheckdb

NAME

amcheckdb - check Amanda database for tape consistency  

SYNOPSIS

amcheckdb config  

DESCRIPTION

Amcheckdb verifies that every tape mentioned in the Amanda database is still valid in the tapelist file.

See the amanda(8) man page for more details about Amanda.  

EXAMPLE

This shows a normal response:

# amcheckdb DailySet1 Ready.

This shows tape DMP014 is still listed in the database but is no longer listed in the tapelist file:

# amcheckdb DailySet1 Tape DMP014 missing in /etc/amanda/DailySet1/tapelist Ready.

 

AUTHOR

Adrian T. Filipi-Martin <atf3r@cs.virginia.edu>  

SEE ALSO

amadmin(8), amrmtape(8), amanda(8)

amd

NAME

amd - automatically mount file systems  

SYNOPSIS

amd -H
amd [ -F conf_file ]
amd [ -nprvHS ] [ -a mount_point ] [ -c duration ] [ -d domain ] [ -k kernel-arch ] [ -l logfile ] [ -o op_sys_ver ] [ -t interval.interval ] [ -w interval ] [ -x log-option ] [ -y YP-domain ] [ -C cluster-name ] [ -D option ] [ -F conf_file ] [ -O op_sys_name ] [ -T tag ] [ directory mapname [ -map-options ] ] ...  

DESCRIPTION

Amd is a daemon that automatically mounts filesystems whenever a file or directory within that filesystem is accessed. Filesystems are automatically unmounted when they appear to have become quiescent.

Amd operates by attaching itself as an <FONT SIZE="-1">NFS</FONT> server to each of the specified directories. Lookups within the specified directories are handled by amd, which uses the map defined by mapname to determine how to resolve the lookup. Generally, this will be a host name, some filesystem information and some mount options for the given filesystem.

In the first form depicted above, amd will print a short help string. In the second form, if no options are specified, or the -F is used, amd will read configuration parameters from the file conf_file which defaults to /etc/amd.conf. The last form is described below.  

OPTIONS

-a temporary-directory

Specify an alternative location for the real mount points. The default is /a.

-c duration

Specify a duration, in seconds, that a looked up name remains cached when not in use. The default is 5 minutes.

-d domain

Specify the local domain name. If this option is not given the domain name is determined from the hostname.

-k kernel-arch

Specifies the kernel architecture. This is used solely to set the ${karch} selector.

-l logfile

Specify a logfile in which to record mount and unmount events. If logfile is the string syslog then the log messages will be sent to the system log daemon by syslog(3). The default syslog facility used is LOG_DAEMON. If you wish to change it, append its name to the log file name, delimited by a single colon. For example, if logfile is the string syslog:local7 then Amd will log messages via syslog(3) using the LOG_LOCAL7 facility (if it exists on the system).

-n

Normalize hostnames. The name refereed to by ${rhost} is normalized relative to the host database before being used. The effect is to translate aliases into ``official`` names.

-o op_sys_ver

Override the compiled-in version number of the operating system. Useful when the built in version is not desired for backward compatibility reasons. For example, if the build in version is ``2.5.1``, you can override it to ``5.5.1``, and use older maps that were written with the latter in mind.

-p

Print PID. Outputs the process-id of amd to standard output where it can be saved into a file.

-r

Restart existing mounts. Amd will scan the mount file table to determine which filesystems are currently mounted. Whenever one of these would have been auto-mounted, amd inherits it.

-t timeout.retransmit

Specify the NFS timeout interval, in tenths of a second, between NFS/RPC retries (for UDP only). The default is 0.8 seconds. The second value alters the restransmit counter, which defaults to 11 retransmissions. Both of these values are used by the kernel to communicate with amd. Useful defaults are supplied if either or both values are missing.

Amd relies on the kernel RPC retransmit mechanism to trigger mount retries. The values of these parameters change the overall retry interval. Too long an interval gives poor interactive response; too short an interval causes excessive retries.

-v

Version. Displays version and configuration information on standard error.

-w interval

Specify an interval, in seconds, between attempts to dismount filesystems that have exceeded their cached times. The default is 2 minutes.

-x options

Specify run-time logging options. The options are a comma separated list chosen from: fatal, error, user, warn, info, map, stats, all.

-y domain

Specify an alternative NIS domain from which to fetch the NIS maps. The default is the system domain name. This option is ignored if NIS support is not available.

-C cluster-name

Specify an alternative HP-UX cluster name to use.

-D option

Select from a variety of debug options. Prefixing an option with the strings no reverses the effect of that option. Options are cumulative. The most useful option is all. Since -D is only used for debugging other options are not documented here: the current supported set of options is listed by the -v option and a fuller description is available in the program source.

-F conf_file

Specify an amd configuration file to use. See amd.conf(5) for description of this file`s format. This configuration file is used to specify any options in lieu of typing many of them on the command line. The amd.conf file includes directives for every command line option amd has, and many more that are only available via the configuration file facility. The configuration file specified by this option is processed after all other options had been processed, regardless of the actual location of this option on the command line.

-H

Print help and usage string.

-O op_sys_name

Override the compiled-in name of the operating system. Useful when the built in name is not desired for backward compatibility reasons. For example, if the build in name is ``sunos5``, you can override it to ``sos5``, and use older maps which were written with the latter in mind.

-S

Do not lock the running executable pages of amd into memory. To improve amd`s performance, systems that support the plock(3) call, could lock the amd process into memory. This way there is less chance the operating system will schedule, page out, and swap the amd process as needed. This tends improves amd`s performance, at the cost of reserving the memory used by the amd process (making it unavailable for other processes). If this behavior is not desired, use the -S option.

-T tag

Specify a tag to use with amd.conf(5). All map entries tagged with tag will be processed. Map entries that are not tagged are always processed. Map entries that are tagged with a tag other than tag will not be processed.

 

FILES

/a

directory under which filesystems are dynamically mounted

/etc/amd.conf

default configuration file

 

CAVEATS

Some care may be required when creating a mount map.

Symbolic links on an NFS filesystem can be incredibly inefficient. In most implementations of NFS, their interpolations are not cached by the kernel and each time a symlink is encountered during a lookuppn translation it costs an RPC call to the NFS server. It would appear that a large improvement in real-time performance could be gained by adding a cache somewhere. Replacing symlinks with a suitable incarnation of the auto-mounter results in a large real-time speedup, but also causes a large number of process context switches.

A weird imagination is most useful to gain full advantage of all the features.  

SEE ALSO

amd.conf(5), amq(8), domainname(1), hostname(1), automount(8), mount(8), umount(8), mtab(5), syslog(3).

Amd - The 4.4 BSD Automounter  

AUTHORS

Jan-Simon Pendry <jsp@doc.ic.ac.uk>, Department of Computing, Imperial College, London, UK. Erez Zadok <ezk@cs.columbia.edu>, Department of Computer Science, Columbia University, New York, USA. Other authors and contributors to am-utils are listed in the AUTHORS file distributed with am-utils.

amdump

NAME

amdump - back up all disks in an Amanda configuration  

SYNOPSIS

amdump config [ host [ disk ]* ]*  

DESCRIPTION

Amdump switches to the appropriate Amanda configuration directory, e.g. /etc/amanda/config, then attempts to back up every disk specified by the amanda.conf file. Amdump is normally run by cron.

You can specify many host/disk expression, only disks that match an expression will be dumped. All disk are dumped if no expression are given.

If file /etc/amanda/config/hold exists, amdump will wait until it is removed before starting the backups. This allows scheduled backups to be delayed when circumstances warrant, for example, if the tape device is being used for some other purpose. While waiting, amdump checks for the hold file every minute.

See the amanda(8) man page for more details about Amanda.  

EXAMPLE

Here is a typical crontab entry. It runs amdump every weeknight at 1 a.m. as user bin:

0 1 * * 1-5 bin /usr/sbin/amdump DailySet1

Please see the crontab(5) or crontab(1) manual page for the correct crontab format for your system.  

MESSAGES

amdump: waiting for hold file to be removed

The "hold" file exists and amdump is waiting for it to be removed before starting backups.

amdump: amdump or amflush is already running, or you must run amcleanup

Amdump detected another amdump or amflush running, or the remains of a previous incomplete amdump or amflush run. This run is terminated. If the problem is caused by the remains of a previous run, you must execute amcleanup(8) and then rerun amdump.

 

AUTHOR

James da Silva <jds@cs.umd.edu>
University of Maryland, College Park  

SEE ALSO

amanda(8), amcheck(8), amcleanup(8), amrestore(8), amflush(8), cron(8)

amgetconf

NAME

amgetconf - look up amanda.conf variables  

SYNOPSIS

amgetconf [ config ] parameter  

DESCRIPTION

Amgetconf looks up parameters in amanda.conf, the Amanda configuration file, or from the build and runtime environment, and returns their corresponding value.

If config is not specified, amgetconf assumes it is being run from the configuration directory and that amanda.conf is present.

If parameter begins with build., the (case insensitive) string following the period is a build environment variable. Variables without a value (e.g. XFSDUMP on a system that does not support that type of file system) will not report an error and will return an empty string as the value. Flag variables (e.g. USE_AMANDAHOSTS) will return 1 if the flag is set or an empty string if it is not.

If parameter begins with dbopen., the string following the period is a program name and an Amanda debug file will be created for the caller. The name of the file is returned.

If parameter begins with dbclose., the string following the period is a program name previously used with dbopen., followed by a colon (:) and the previously opened file name.

See the amanda(8) man page for more details about Amanda.  

EXAMPLE

Find out the path to the log file directory:

% amgetconf DailySet1 logdir /etc/amanda/DailySet1

Find out the current tape type:

% amgetconf DailySet1 tapetype DLT4000-IV

Find out the default configuration directory:

% amgetconf DailySet1 build.CONFIG_DIR /etc/amanda

Create, use and close a debug file in a script:

% set debug_file = `amgetconf DailySet1 dbopen.myscript` % echo debug information >> $debug_file % amgetconf DailySet1 dbclose.myscript:$debug_file

 

MESSAGES

amgetconf: no such parameter "param"

Parameter param is not a known keyword (e.g. not a valid amanda.conf keyword). In this case, amgetconf will write "BUGGY" to stdout as the value.

 

SEE ALSO

amanda(8)

ammt

NAME

ammt - Amanda version of mt  

SYNOPSIS

ammt [ -d ] [ -f|-t device ] command [ count ]  

DESCRIPTION

Ammt provides just enough of the standard mt command for the needs of Amanda. This is handy when doing a full restore and the standard mt program has not yet been found.

Ammt also provides access to the Amanda output drivers that support various tape simulations.

See the amanda(8) man page for more details about Amanda. See the OUTPUT DRIVERS section of amanda(8) for more information on the Amanda output drivers.  

OPTIONS

-d

Turn on debugging output.

-f device

Access tape device device. If not specified, the TAPE environment variable is used.

-t device

Same as -f.

command count

Which command to issue, and an optional count of operations.

 

COMMANDS

Each command may be abbreviated to whatever length makes it unique.

eof|weof count

Write count (default: 1) end of file marks (tapemarks).

fsf count

Skip forward count (default: 1) files.

bsf count

Skip backward count (default: 1) files.

asf count

Position to file number count (default: 0) where zero is beginning of tape. This is the same as a rewind followed by a fsf count.

rewind

Rewind to beginning of tape.

offline|rewoffl

Rewind to beginning of tape and unload the tape from the drive.

status

Report status information about the drive. Which data reported, and what it means, depends on the underlying operating system, and may include:

ONLINE

Indicates the drive is online and ready.

OFFLINE

Indicates the drive is offline or not ready.

BOT

Indicates the drive is at beginning of tape.

EOT

Indicates the drive is at end of tape.

PROTECTED

Indicates the tape is write protected.

ds

Device status.

er

Error register.

fileno

Current tape file number.

blkno

Current tape block number file.

NOTE: many systems only report good data when a tape is in the drive and ready.

 

AUTHOR

Marc Mengel <mengel@fnal.gov>
John R. Jackson <jrj@purdue.edu>  

SEE ALSO

amanda(8)

amplot

NAME

amplot - visualize the behavior of Amanda  

SYNOPSIS

amplot [ -b ] [ -c ] [ -e ] [ -g ] [ -l ] [ -p ] [ -t T ] amdump_files
 

DESCRIPTION

Amplot reads an amdump output file that Amanda generates each run (e.g. amdump.1) and translates the information into a picture format that may be used to determine how your installation is doing and if any parameters need to be changed. Amplot also prints out amdump lines that it either does not understand or knows to be warning or error lines and a summary of the start, end and total time for each backup image.

Amplot is a shell script that executes an awk program (amplot.awk) to scan the amdump output file. It then executes a gnuplot program (amplot.g) to generate the graph. The awk program is written in an enhanced version of awk, such as GNU awk (gawk version 2.15 or later) or nawk.

During execution, amplot generates a few temporary files that gnuplot uses. These files are deleted at the end of execution.

See the amanda(8) man page for more details about Amanda.  

OPTIONS

-b

Generate b/w postscript file (need -p).

-c

Compress amdump_files after plotting.

-e

Extend the X (time) axis if needed.

-g

Direct gnuplot output directly to the X11 display (default).

-p

Direct postscript output to file YYYYMMDD.ps (opposite of -g).

-l

Generate landscape oriented output (need -p).

-t T

Set the right edge of the plot to be T hours.

The amdump_files may be in various compressed formats (compress, gzip, pact, compact).  

INTERPRETATION

The figure is divided into a number of regions. There are titles on the top that show important statistical information about the configuration and from this execution of amdump. In the figure, the X axis is time, with 0 being the moment amdump was started. The Y axis is divided into 5 regions:

QUEUES: How many backups have not been started, how many are waiting on space in the holding disk and how many have been transferred successfully to tape.

%BANDWIDTH: Percentage of allowed network bandwidth in use.

HOLDING DISK: The higher line depicts space allocated on the holding disk to backups in progress and completed backups waiting to be written to tape. The lower line depicts the fraction of the holding disk containing completed backups waiting to be written to tape including the file currently being written to tape. The scale is percentage of the holding disk.

TAPE: Tape drive usage.

%DUMPERS: Percentage of active dumpers.

The idle period at the left of the graph is time amdump is asking the machines how much data they are going to dump. This process can take a while if hosts are down or it takes them a long time to generate estimates.  

AUTHOR

Olafur Gudmundsson ogud@tis.com
Trusted Information Systems
formerly at University of Maryland, College Park  

BUGS

Reports lines it does not recognize, mainly error cases but some are legitimate lines the program needs to be taught about.  

SEE ALSO

amanda(8), amdump(8), gawk(1), nawk(1), awk(1), gnuplot(1), sh(1), compress(1), gzip(1)

amrecover

NAME

amrecover - Amanda index database browser  

SYNOPSIS

amrecover [ [ -C ] config ] [ -s index-server ] [ -t tape-server ] [ -d tape-device ]  

DESCRIPTION

Amrecover browses the database of Amanda index files to determine which tapes contain files to recover. Furthermore, it is able to recover files.

In order to restore files in place, you must invoke amrecover from the root of the backed up filesystem, or use lcd to move into that directory, otherwise a directory tree that resembles the backed up filesystem will be created in the current directory. See the examples below for details.

See the amanda(8) man page for more details about Amanda.  

OPTIONS

[ -C ] config

Amanda configuration (default: DailySet1).

-s index-server

Host that runs the index daemon (default: localhost).

-t tape-server

Host that runs the tape server daemon (default: localhost).

-d tape-device

Tape device to use on the tape server host (default: /dev/null).

 

COMMANDS

Amrecover connects to the index server and then presents a command line prompt. Usage is similar to an ftp client. The GNU readline library is used to provide command line history and editing if it was built in to amrecover.

The purpose of browsing the database is to build up a restore list of files to be extracted from the backup system. The following commands are available:

sethost hostname

Specifies which host to look at backup files for (default: the local host).

setdate YYYY-MM-DD

Set the date (default: today). File listing commands only return information on backup images for this day, for the day before with the next lower dump level, and so on, until the most recent level 0 backup on or before the specified date is encountered.

For example, if:

1996-07-01 was a level 0 backup 1996-07-02 through 1996-07-05 were level 1 backups 1996-07-06 through 1997-07-08 were level 2 backups

then if 1997-07-08 is the requested date, files from the following days would be used:

1997-07-08 (the latest level 2 backup) 1997-07-05 (the latest level 1 backup) 1997-07-01 (the latest level 0 backup)

Only the most recent version of a file will be presented.

The following abbreviated date specifications are accepted:

--MM-DD

dates in the current year

---DD

dates in the current month of the current year

setdisk diskname [ mountpoint ]

Specifies which disk to consider (default: the disk holding the working directory where amrecover is started). It can only be set after the host is set with sethost. Diskname is the device name specified in the amanda.conf or disklist configuration file. The disk must be local to the host. If mountpoint is not specified, all pathnames will be relative to the (unknown) mount point instead of full pathnames.

listdisk [diskdevice]

List all diskname

settape [[server]:][tapedev|default]

Specifies the host to use as the tape server, and which of its tape devices to use. If the server is omitted, but the colon is not, the server name reverts to localhost, the configure-time default. If the tape device is omitted, it remains unchanged. To use the default tape device selected by the tape server, the word default must be specified. If no argument is specified, or the argument is an empty string, no changes occur, and the current settings are displayed.

If you want amrecover to use your changer, the tapedev must be equal to the amrecover_changer setting on the server.

If you need to change the protocol (tape:, rait:, file:, null:) then you must specify the hostname.

settape localhost:file:/file1

You can change the tape device when amrecover ask you to load the tape:

Load tape DMP014 now Continue? [Y/n/t]: t Tape device: server2:/dev/nst2 Continue? [Y/n/t]: Y Using tape /dev/nst2 from server server2.

setmode mode

Set the extraction mode for Samba shares. If mode is smb, shares are sent to the Samba server to be restored back onto the PC. If mode is tar, they are extracted on the local machine the same way tar volumes are extracted.

mode

Displays the extracting mode for Samba shares.

history

Show the backup history of the current host and disk. Dates, levels, tapes and file position on tape of each backup are displayed.

pwd

Display the name of the current backup working directory.

cd dir

Change the backup working directory to dir. If the mount point was specified with setdisk, this can be a full pathname or it can be relative to the current backup working directory. If the mount point was not specified, paths are relative to the mount point if they start with "/", otherwise they are relative to the current backup working directory. The dir can be a shell style wildcards.

cdx dir

Like the cd command but allow regular expression.

lpwd

Display the amrecover working directory. Files will be restored under this directory, relative to the backed up filesystem.

lcd path

Change the amrecover working directory to path.

ls

List the contents of the current backup working directory. See the description of the setdate command for how the view of the directory is built up. The backup date is shown for each file.

add item1 [ item2 ... ]

Add the specified files or directories to the restore list. Each item may have shell style wildcards.

addx item1 [ item2 ... ]

Add the specified files or directories to the restore list. Each item may be a regular expression.

delete item1 [ item2 ... ]

Delete the specified files or directories from the restore list. Each item may have shell style wildcards.

deletex item1 [ item2 ... ]

Delete the specified files or directories from the restore list. Each item may be a regular expression.

list [ file ]

Display the contents of the restore list. If a file name is specified, the restore list is written to that file. This can be used to manually extract the files from the Amanda tapes with amrestore.

clear

Clear the restore list.

quit

Close the connection to the index server and exit.

exit

Close the connection to the index server and exit.

extract

Start the extract sequence (see the examples below). Make sure the local working directory is the root of the backed up filesystem, or another directory that will behave like that. Use lpwd to display the local working directory, and lcd to change it.

help

Display a brief list of these commands.

 

EXAMPLES

The following shows the recovery of an old syslog file.

# cd /var/log # ls -l syslog.7 syslog.7: No such file or directory # amrecover AMRECOVER Version 2.4.2. Contacting server on localhost ... 220 localhost AMANDA index server (2.4.2) ready. Setting restore date to today (1997-12-09) 200 Working date set to 1997-12-09. 200 Config set to DailySet1. 200 Dump host set to this-host.some.org. $CWD `/var/log` is on disk `/var` mounted at `/var`. 200 Disk set to /var. /var/log WARNING: not on root of selected filesystem, check man-page! amrecover> ls 1997-12-09 daemon.log 1997-12-09 syslog 1997-12-08 authlog 1997-12-08 sysidconfig.log 1997-12-08 syslog.0 1997-12-08 syslog.1 1997-12-08 syslog.2 1997-12-08 syslog.3 1997-12-08 syslog.4 1997-12-08 syslog.5 1997-12-08 syslog.6 1997-12-08 syslog.7 amrecover> add syslog.7 Added /log/syslog.7 amrecover> lpwd /var/log amrecover> lcd .. /var amrecover> extract Extracting files using tape drive /dev/null on host localhost The following tapes are needed: DMP014 Restoring files into directory /var Continue? [Y/n]: y Load tape DMP014 now Continue? [Y/n/t]: y set owner/mode for `.`? [yn] n amrecover> quit 200 Good bye. # ls -l syslog.7 total 26 -rw-r--r-- 1 root other 12678 Oct 14 16:36 syslog.7

If you do not want to overwrite existing files, create a subdirectory to run amrecover from and then move the restored files afterward.

# cd /var # (umask 077 ; mkdir .restore) # cd .restore # amrecover AMRECOVER Version 2.4.2. Contacting server on localhost ... ... amrecover> cd log /var/log amrecover> ls ... amrecover> add syslog.7 Added /log/syslog.7 amrecover> lpwd /var/.restore amrecover> extract Extracting files using tape drive /dev/null on host localhost ... amrecover> quit 200 Good bye. # mv -i log/syslog.7 ../log/syslog.7-restored # cd .. # rm -fr .restore

If you need to run amrestore by hand instead of letting amrecover control it, use the list command after browsing to display the needed tapes.

# cd /var/log # amrecover AMRECOVER Version 2.4.2. Contacting server on localhost ... ... amrecover> ls ... amrecover> add syslog syslog.6 syslog.7 Added /log/syslog Added /log/syslog.6 Added /log/syslog.7 amrecover> list TAPE DMP014 LEVEL 0 DATE 1997-12-08 /log/syslog.7 /log/syslog.6 TAPE DMP015 LEVEL 1 DATE 1997-12-09 /log/syslog amrecover> quit

The history command shows each tape that has a backup of the current disk along with the date of the backup, the level, the tape label and the file position on the tape. All active tapes are listed, not just back to the most recent full dump.

Tape file position zero is a label. The first backup image is in file position one.

# cd /var/log # amrecover AMRECOVER Version 2.4.2. Contacting server on localhost ... ... amrecover> history 200- Dump history for config "DailySet1" host "this-host.some.org" disk "/var" 201- 1997-12-09 1 DMP015 9 201- 1997-12-08 1 DMP014 11 201- 1997-12-07 0 DMP013 22 201- 1997-12-06 1 DMP012 16 201- 1997-12-05 1 DMP011 9 201- 1997-12-04 0 DMP010 11 201- 1997-12-03 1 DMP009 7 201- 1997-12-02 1 DMP008 7 201- 1997-12-01 1 DMP007 9 201- 1997-11-30 1 DMP006 6 ... amrecover> quit

 

ENVIRONMENT

PAGER

The ls and list commands will use $PAGER to display the file lists. Defaults to more if PAGER is not set.

 

AUTHOR

Alan M. McIvor <alan@kauri.auck.irl.cri.nz>  

SEE ALSO

amanda(8), amrestore(8), readline(3)

amrestore

NAME

amrestore - extract backup images from an Amanda tape  

SYNOPSIS

amrestore [ -r | -c | -C ] [ -b blocksize ] [ -f fileno ] [ -l label ] [ -p ] [ -h ] tapedevice | holdingfile [ hostname [ diskname [ datestamp [ hostname [ diskname [ datestamp ... ]]]]]]  

DESCRIPTION

Amrestore extracts backup images from the tape mounted on tapedevice or from the holding disk file holdingfile that match hostname, diskname and datestamp patterns given on the command line. The tape or holding file must be in a format written by the amdump or amflush program.

If diskname is not specified, all backups on the tape for the previous hostname are candidates. If datestamp is not specified, all backups on the tape for the previous hostname and diskname are candidates. If no hostname, diskname or datestamp are specified, every backup on the tape is a candidate.

Hostname and diskname are special expression descibe in the "HOST & DISK EXPRESSION" section of amanda(8). Datestamp are special expression describe in the "DATESTAMP EXPRESSION" section of amanda(8). For example, if diskname is "rz[23]a", it would match disks rz2a and rz3a.

Datestamp is useful if amflush writes multiple backup runs to a single tape.

Unless -p is used, candidate backup images are extracted to files in the current directory named:

hostname.diskname.datestamp.dumplevel

Amrestore doesn`t use a changer, it restore from the tape already loaded in the tapedevice.  

OPTIONS

-b

Set the blocksize used to read the tape or holding file. All holding files must be read with a blocksize of 32 KBytes. Amrestore should normally be able to determine the blocksize for tapes on its own and not need this parameter.

The default is 32 KBytes.

-f

Do a rewind followed by a fsf <fileno> before trying to restore an image.

-l

Check if we restoring from the tape with the right label

-p

Pipe output. The first matching backup image is sent to standard output, which is normally a pipe to restore or tar, then amrestore quits. It may be run again to continue selecting backups to process. Make sure you specify the no-rewind tapedevice when doing this.

Note: restore may report "short read" errors when reading from a pipe. Most versions of restore support a blocking factor option to let you set the read block size, and you should set it to 2. See the example below.

-c

Compress output using the fastest method the compression program provides. Amrestore normally writes output files in a format understood by restore or tar, even if the backups on the tape are compressed. With the -c or -C option, amrestore writes all files in compressed format, even if the backups on the tape are not compressed. Output file names will have a .Z or .gz extension depending on whether compress or gzip is the preferred compression program. This option is useful when the current directory disk is small.

-C

Compress output using the best method the compression program provides (may be very CPU intensive). See the notes above about the -c option.

-r

Raw output. Backup images are output exactly as they are on the tape, including the amdump headers. Output file names will have a .RAW extension. This option is only useful for debugging and other strange circumstances.

-h

Header output. The tape header block is output at the beginning of each file. This is like -r except -c or -C may also be used to compress the result. Amrecover uses the header to determine the restore program to use.

If a header is written (-r or -h), only 32 KBytes are output regardless of the tape blocksize. This makes the resulting image usable as a holding file.  

EXAMPLES

The following does an interactive restore of disk rz3g from host seine, to restore particular files. Note the use of the b option to restore, which causes it to read in units of two 512-byte blocks (1 Kbyte) at a time. This helps keep it from complaining about short reads.

% amrestore -p /dev/nrmt9 seine rz3g | restore -ivbf 2 -

The next example extracts all backup images for host seine. This is the usual way to extract all data for a host after a disk crash.

% amrestore /dev/nrmt9 seine

If the backup datestamp in the above example is 19910125 and seine has level 0 backups of disks rz1a and rz1g on the tape, these files will be created in the current directory:

seine.rz1a.19910125.0 seine.rz1g.19910125.0

You may also use amrestore to extract a backup image from a holding disk file that has not yet been flushed to tape:

% amrestore -p /amanda/20001119/seine.rz1a.2 | restore -ivbf 2 -

Amrestore may be used to generate a listing of images on a tape:

% mt -f /dev/nrmt9 rewind % amrestore -p /dev/nrmt9 no-such-host > /dev/null

This asks amrestore to find images for host no-such-host. It will not find any entries that match, but along the way will report each image it skips.  

CAVEATS

GNU tar must be used to restore files from backup images created with the GNUTAR dumptype. Vendor tar programs sometimes fail to read GNU tar images.  

AUTHOR

James da Silva <jds@cs.umd.edu>
University of Maryland, College Park  

SEE ALSO

amanda(8), amdump(8), amflush(8), tar(1) restore(8)

amstatus

NAME

amstatus - display the state of an Amanda run  

SYNOPSIS

amstatus [--config] config [--file amdumpfile ] [--summary] [--dumping] [--waitdumping] [--waittaper] [--dumpingtape] [--writingtape] [--finished] [--failed] [--estimate] [--gestimate] [--stats]  

DESCRIPTION

Amstatus gives the current state of the Amanda run specified by the config configuration. If there is no active amanda running, it summarizes the result of the last run. It may also be used to summarize the results of a previous run.

See the amanda(8) man page for more details about Amanda.  

OPTIONS

All options may be abbreviated to the shortest non-ambiguous sub-string. If no options are given, everything is displayed.

[--config] config

Specify the Amanda configuration you want to display the state for.

--file amdumpfile

Specify an alternate file instead of the amdump or amflush file.

--summary

Display a summary of the state of the run.

--dumping

Display all partitions that are dumping.

--waitdumping|wdumping

Display all partitions that are waiting to be dumped.

--waittaper|wtaper

Display all partitions dumped that are waiting to be written to tape.

--dumpingtape|dtape

Display all partitions that are dumping directly to tape.

--writingtape|wtape

Display all partitions that are writing to tape.

--finished

Display all partitions that are dumped and written to tape.

--failed|error

Display all partitions that failed.

--estimate

Display all partitions whose estimate is finished. Works only during the estimate phase.

--gestimate|gettingestimate

Display all partitions whose estimate is not finished. Works only during the estimate phase.

--stats|statistics

Display statistics about active-time of taper and dumpers.

 

SEE ALSO

amanda(8), amcheck(8), amdump(8), amrestore(8), amadmin(8)

amtapetype

NAME

amtapetype - generate a tapetype definition.  

SYNOPSIS

amtapetype [-h] [-c] [-b blocksize] [-e estsize] [-f tapedev] [-t typename]  

DESCRIPTION

Amtapetype generate a tapetype entry for amanda.  

OPTIONS

-h

Display an help message.

-c

Run only the hardware compression detection heuristic test and stop. This takes a few minutes only.

-b blocksize

record block size (default: 32k)

-e estsize

estimated tape size (default: 1g == 1024m)

-f tapedev

tape device name (default: $TAPE) The device to perform the test.

-t typename

tapetype name (default: unknown-tapetype)

 

EXAMPLE

Generate a tapetype definition for your tape device:

% amtapetype -f /dev/null

 

NOTES

Hardware compression is detected by measuring the writing speed difference of the tape drive when writing an amount of compressable and uncompresseable data. It does not rely on the status bits of the tape drive or the OS parameters. If your tape drive has very large buffers or is very fast, the program could fail to detect hardware compression status reliably.

During the first pass, it writes files that are estimated to be 1% of the expected tape capacity. It gets the expected capacity from the -e command line flag, or defaults to 1 GByte. In a perfect world (which means there is zero chance of this happening with tapes :-), there would be 100 files and 100 file marks.

During the second pass, the file size is cut in half. In that same fairyland world, this means 200 files and 200 file marks.

In both passes the total amount of data written is summed as well as the number of file marks written. At the end of the second pass, quoting from the code:

   * Compute the size of a filemark as the difference in data written
   * between pass 1 and pass 2 divided by the difference in number of
   * file marks written between pass 1 and pass 2.  ...

So if we wrote 1.0 GBytes on the first pass and 100 file marks, and 0.9 GBytes on the second pass with 200 file marks, those additional 100 file marks in the second pass took 0.1 GBytes and therefor a file mark is 0.001 GBytes (1 MByte).

Note that if the estimated capacity is wrong, the only thing that happens is a lot more (or less, but unlikely) files, and thus, file marks, get written. But the math still works out the same. The -e flag is there to keep the number of file marks down because they can be slow (since they force the drive to flush all its buffers to physical media).

All sorts of things might happen to cause the amount of data written to vary enough to generate a big file mark size guess. A little more "shoe shining" because of the additional file marks (and flushes), dirt left on the heads from the first pass of a brand new tape, the temperature/humidity changed during the multi-hour run, a different amount of data was written after the last file mark before EOT was reported, etc.

Note that the file mark size might really be zero for whatever device this is, and it was just the measured capacity variation that caused amtapetype to think those extra file marks in pass 2 actually took up space.

It also explains why amtapetype used to sometimes report a negative file mark size if the math happened to end up that way. When that happens now we just report it as zero.  

SEE ALSO

amanda(8)

amverify

NAME

amverify - check an Amanda tape for errors  

SYNOPSIS

amverify config [ slot [ runtapes ] ]  

DESCRIPTION

Amverify reads an Amanda format tape and makes sure each backup image can be processed by amrestore and, if possible, the appropriate restore program (e.g. tar).

Amverify runs amrestore on each file of the tape and pipes the output to a restore program (if available) with an option to create a catalogue of the backup. The catalogue itself is discarded. Only the success or failure of the operation itself is reported.

If the backup image cannot be processed by the restore program, e.g. if it was written on a different operating system, the image is sent through dd to /dev/null. This still determines if the tape is readable, but does not do any internal consistency check on the image.

If config is set up to use a tape changer, the slot argument may be used to choose the first tape to process. Otherwise, the current slot is used.

The runtapes configuration parameter determines how many tapes are processed unless it is specified on the command line.

See the amanda(8) man page for more details about Amanda.  

AUTHOR

Axel Zinser <fifi@icem.de>  

SEE ALSO

amrestore(8), amanda(8), amverifyrun(8)

anacron

NAME

anacron - runs commands periodically  

SYNOPSIS

anacron [-s] [-f] [-n] [-d] [-q] [-t anacrontab] [job] ...
anacron -u [-t anacrontab] [job] ...
anacron [-V|-h]  

DESCRIPTION

Anacron can be used to execute commands periodically, with a frequency specified in days. Unlike cron(8), it does not assume that the machine is running continuously. Hence, it can be used on machines that aren`t running 24 hours a day, to control daily, weekly, and monthly jobs that are usually controlled by cron.

When executed, Anacron reads a list of jobs from a configuration file, normally /etc/anacrontab (see anacrontab(5)). This file contains the list of jobs that Anacron controls. Each job entry specifies a period in days, a delay in minutes, a unique job identifier, and a shell command.

For each job, Anacron checks whether this job has been executed in the last n days, where n is the period specified for that job. If not, Anacron runs the job`s shell command, after waiting for the number of minutes specified as the delay parameter.

After the command exits, Anacron records the date in a special timestamp file for that job, so it can know when to execute it again. Only the date is used for the time calculations. The hour is not used.

When there are no more jobs to be run, Anacron exits.

Anacron only considers jobs whose identifier, as specified in the anacrontab matches any of the job command-line arguments. The job arguments can be shell wildcard patterns (be sure to protect them from your shell with adequate quoting). Specifying no job arguments, is equivalent to specifying "*" (That is, all jobs will be considered).

Unless the -d option is given (see below), Anacron forks to the background when it starts, and the parent process exits immediately.

Unless the -s or -n options are given, Anacron starts jobs immediately when their delay is over. The execution of different jobs is completely independent.

If a job generates any output on its standard output or standard error, the output is mailed to the user running Anacron (usually root).

Informative messages about what Anacron is doing are sent to syslogd(8) under facility cron, priority notice. Error messages are sent at priority error.

"Active" jobs (i.e. jobs that Anacron already decided to run and now wait for their delay to pass, and jobs that are currently being executed by Anacron), are "locked", so that other copies of Anacron won`t run them at the same time.  

OPTIONS

-f

Force execution of the jobs, ignoring the timestamps.

-u

Only update the timestamps of the jobs, to the current date, but don`t run anything.

-s

Serialize execution of jobs. Anacron will not start a new job before the previous one finished.

-n

Run jobs now. Ignore the delay specifications in the /etc/anacrontab file. This options implies -s.

-d

Don`t fork to the background. In this mode, Anacron will output informational messages to standard error, as well as to syslog. The output of jobs is mailed as usual.

-q

Suppress messages to standard error. Only applicable with -d.

-t anacrontab

Use specified anacrontab, rather than the default

-V

Print version information, and exit.

-h

Print short usage message, and exit.

 

SIGNALS

After receiving a SIGUSR1 signal, Anacron waits for running jobs, if any, to finish and then exits. This can be used to stop Anacron cleanly.  

NOTES

Make sure that the time-zone is set correctly before Anacron is started. (The time-zone affects the date). This is usually accomplished by setting the TZ environment variable, or by installing a /usr/lib/zoneinfo/localtime file. See tzset(3) for more information.  

FILES

/etc/anacrontab

Contains specifications of jobs. See anacrontab(5) for a complete description.

/var/spool/anacron

This directory is used by Anacron for storing timestamp files.

 

SEE ALSO

anacrontab(5), cron(8), tzset(3)

The Anacron README file.  

BUGS

Anacron never removes timestamp files. Remove unused files manually.

Anacron uses up to two file descriptors for each active job. It may run out of descriptors if there are more than about 125 active jobs (on normal kernels).

Mail comments, suggestions and bug reports to Sean `Shaleh` Perry <shaleh@(debian.org|valinux.com)>.  

AUTHOR

Anacron was originally conceived and implemented by Christian Schwarz <schwarz@monet.m.isar.de>.

The current implementation is a complete rewrite by Itai Tzur <itzur@actcom.co.il>.

The code base is currently maintained by Sean `Shaleh` Perry <shaleh@(debian.org|valinux.com)>.

apmd

NAME

apmd - Advanced Power Management (APM) daemon  

SYNOPSIS

apmd [ -c check_seconds ] [ -P proxy_cmd ] [ -p percent_to_log ] [ -qVvW ] [ -w warn_percent ] [ -? ] [deprecated options]  

DESCRIPTION

apmd is an APM monitoring daemon, and works in conjunction with the APM BIOS driver in the OS kernel. It can execute a command (normally a shell script) when certain events are reported by the driver, and will log, via syslogd(8), certain changes in system power status. When the available battery power becomes very low, it can alert all users on the system using several methods.

When the kernel APM driver notifies the daemon of a pending suspend or standby request, apmd will invoke the approprate command, log the event, sync(2) data to the disk, sleep briefly to help ensure all the data actually gets to the disk, and then tell the APM driver to continue its operation. However, for "critical" suspends (indicating an emergency shutdown) only the last step (telling the driver to continue) is performed.

Most uses of this daemon will use the proxy command to support power conservation activities. This command is either specified using the -P option, or /etc/apm/apmd_proxy by default. It is invoked with one or two arguments:

start

Invoked when the daemon starts. Normally sets system-wide power policy, such as IDE hard drive standby times, to account for whether battery power is in use.

stop

Invoked when the daemon stops. Normally undoes any policy settings done when the daemon started.

suspend [ system | user ]

Invoked when the APM driver reports that system suspension has been initiated. The second parameter indicates whether the BIOS or a user action (such as closing a laptop) initiated suspension.

The BIOS "suspend" mode aggressively conserves power, and normally involves shutting off power to all devices except the CPU core and memory, which is kept in a very low power mode. Most laptops can stay suspended, using battery power alone, for several days. ("Hibernation" is a kind of super-suspend, where all that state is written to disk and the machine uses even less power bcause it can turn off that CPU core, using no battery power at all. At this writing, Linux does not support hibernation.) PCMCIA devices should be manually suspended using cardctl(8), and some modular drivers may need to be unloaded.

standby [ system | user ]

Invoked when the APM driver reports that system standby has been initiated. The second parameter indicates whether the BIOS or a user action (such as invoking apm -s) caused this.

The BIOS "standby" mode slightly conserves power, and leaves the machine able to respond almost immediately to user activity. Most laptops can`t stay in standby mode for even a day, if they must rely on battery power. Normally, nothing needs to be done beyond what the BIOS itself will do.

resume [ suspend | standby | critical ]

Invoked when the APM driver reports that system has resumed normal operation. The second parameter indicates what sort of mode it was in before, either the "suspend" mode (possibly a "critical" suspend) or else "standby" mode.

The system clock must be updated to match the hardware clock; this will normally have been handled by the kernel`s APM driver. PCMCIA devices may need to be manually resumed from standby using cardctl(8), and some modular drivers may need to be reloaded or otherwise reinitialized. In the case of a critical suspend, system state may not have been completely saved due to an emergency shutdown; applications and drivers may be in a confused state.

change power

This presents a subset of the APM driver "power change" events, specifically those where AC power was added or removed. This will often modify the system wide power policy; for example, so that IDE hard drives aggressively enter standby mode when only battery power is available.

change battery

The APM driver has reported that the BIOS thinks the strength of one (or more) batteries is "low"; at least ten minutes of power should remain.

change capability

Some change in the power management capabilities of the system was reported. It may have been caused by operation of some setup utility, or by the arrival or removal of some devices.

This daemon issues a number of different log messages, most of which should be self explanatory. The messages emitted for battery status need some explanation, however. The information logged contains 4 fields after a "Battery" or "Charge" label:

1) Rate of discharge (percent/minute). Negative rates indicate charging.

2) Time since total charge or total discharge (hh:mm:ss). This value is only useful if it reflects the time since a 100% or 0% state has been reached. Otherwise, this time is in parentheses, and reflects the time since the last "important" apmd status change such as starting the daemon, changing from AC power to battery power, and so on.

3) Estimate of time left until total discharge (or total charge), assuming use similar to that since the last resume ( or since AC was connected). This time is calculated by apmd itself.

4) Parenthetically, the percent and length of remaining battery life, as estimated by the APM BIOS (which is often a conservative estimate from an intelligent battery itself). This particular information is provided with most messages from this daemon.

This daemon supports APM BIOS 1.2 events, though it does not support some of the advanced features such as multiple batteries. Also, there is no interaction yet with ACPI support as found in newer PC hardware.  

OPTIONS

-c seconds, --check seconds

Controls how many seconds to block on the /dev/apm_bios device. Normally the daemon blocks until the APM driver reports an event; this number may be changed to cause battery charge or discharge rates to be checked more often.

-P proxy_cmd, --apmd_proxy proxy_cmd

Identifies the command to invoke when certain APM driver events are reported. See above for information about the arguments to this script.

-p percent_change, --percentage percent_change

Every time the percentage of available power changes (discharge or recharge) by percent_change, log information. The default is 5. Use values greater than 100 to disable this feature.

-V, --version

Print the daemon`s version and exit.

-v, --verbose

Enables verbose mode, where each event reported by the APM driver is logged.

-W, --wall

In addition to logging low battery status (as determined either by the -w level or by the APM BIOS) using syslog(2), also use wall(1) to alert all users. This is most useful if syslogd(8) is not set up to write ALERT messages to all users. If both methods are used, more warnings will be made during the critical time period.

-w warn_percent, --warn warn_percent

When the battery is not being charged and the percentage of available power drops below warn_percent, log a warning at ALERT level to syslog(2). If the -W or --wall flag was given, the daemon will also use wall(1) to alert all users of impending doom. Give the warning each time the percentage changes. The default is 10. Use negative values to disable this feature.

-q, --quiet

Disables the warnings identified by the -W and -w options. (The APM BIOS on many machines will provide an audible warning when power is about to be used up, so those extra warnings may not be needed.)

-?, --help

Prints a usage message and exits.

New software should only use the proxy script, rather than the following now-deprecated options (most of which have never appeared in a production release). If they are provided, they take precedence over any proxy command invocation for each event.

-a ac_online_cmd, --ac_online ac_online_cmd

Provides a command to be run when AC power becomes available, though not when the daemon first starts.

-b ac_offline_cmd, --ac_offline ac_offline_cmd

Provides a command to be run when the machine is operating on battery power, though not when the daemon first starts.

-l low_battery_cmd, --low_battery low_battery_cmd

Provides a command to be run when the APM BIOS judges that battery power is "low".

-s pre_suspend_cmd, --pre_suspend pre_suspend_cmd

Provides a command to be run before suspending through the driver.

-r post_resume_cmd, --post_resume post_resume_cmd

Provides a command to be run after resuming through the driver.

-u, --utc

(This option is now completely ignored. Edit apmd_proxy instead.) This means the BIOS clock is set to UTC (GMT), so the daemon should pass the -u option to the clock or hwclock program when coming out of suspend or resume mode, or when responding to the BIOS update time event.

 

BUGS

The first status report printed after a power change may be inaccurate because the power change occured at a fractional percentage that was rounded to a full percentage. For example, say you are discharging the machine and have 50.9% power, which is reported as 50%. When you start to charge the machine, it will only have 0.1% left before the percentage flips to 51%, and the charge rate will be dramatically over-estimated.

There needs to be a more general hook to let other applications participate in system power management decisions and policies.

Multiple batteries are currently treated as if they were just one large one.  

FILES

/dev/apm_bios
/proc/apm
/etc/apmd/apmd_proxy  

AUTHOR

This program was written by Rik Faith (faith@cs.unc.edu) and may be freely distributed under the terms of the GNU General Public License. There is ABSOLUTELY NO WARRANTY for this program. The current maintainer is Avery Pennarun (apenwarr@worldvisions.ca).  

SEE ALSO

apm(1), xapm(1), cardctl(8), hdparm(8), syslogd(8)

apxs

NAME

apxs - APache eXtenSion tool

 

SYNOPSIS

 

apxs -g [ -S name=value ] -n modname
 

apxs -q [ -S name=value ] query ...
 

apxs -c [ -S name=value ] [ -o dsofile ] [ -I incdir ] [ -D name=value ] [ -L libdir ] [ -l libname ] [ -Wc,compiler-flags ] [ -Wl,linker-flags ] files ...
 

apxs -i [ -S name=value ] [ -n modname ] [ -a ] [ -A ] dso-file ...
 

apxs -e [ -S name=value ] [ -n modname ] [ -a ] [ -A ] dso-file ...
 

 

SUMMARY

 

apxs is a tool for building and installing extension modules for the Apache HyperText Transfer Protocol (HTTP) server. This is achieved by building a dynamic shared object (DSO) from one or more source or object files which then can be loaded into the Apache server under runtime via the LoadModule directive from mod_so.
 

So to use this extension mechanism your platform has to support the DSO feature and your Apache httpd binary has to be built with the mod_so module. The apxs tool automatically complains if this is not the case. You can check this yourself by manually running the command
 

$ httpd -l

 

The module mod_so should be part of the displayed list. If these requirements are fulfilled you can easily extend your Apache server`s functionality by installing your own modules with the DSO mechanism by the help of this apxs tool:
 

$ apxs -i -a -c mod_foo.c gcc -fpic -DSHARED_MODULE -I/path/to/apache/include -c mod_foo.c ld -Bshareable -o mod_foo.so mod_foo.o cp mod_foo.so /path/to/apache/modules/mod_foo.so chmod 755 /path/to/apache/modules/mod_foo.so [activating module `foo` in /path/to/apache/etc/httpd.conf] $ apachectl restart /path/to/apache/sbin/apachectl restart: httpd not running, trying to start [Tue Mar 31 11:27:55 1998] [debug] mod_so.c(303): loaded module foo_module /path/to/apache/sbin/apachectl restart: httpd started $ _

 

The arguments files can be any C source file (.c), a object file (.o) or even a library archive (.a). The apxs tool automatically recognizes these extensions and automatically used the C source files for compilation while just using the object and archive files for the linking phase. But when using such pre-compiled objects make sure they are compiled for position independent code (PIC) to be able to use them for a dynamically loaded shared object. For instance with GCC you always just have to use -fpic. For other C compilers consult its manual page or at watch for the flags apxs uses to compile the object files.
 

For more details about DSO support in Apache read the documentation of mod_so or perhaps even read the src/modules/standard/mod_so.c source file.
 

 

OPTIONS

   

Common Options

 
 

-n modname

This explicitly sets the module name for the -i (install) and -g (template generation) option. Use this to explicitly specify the module name. For option -g this is required, for option -i the apxs tool tries to determine the name from the source or (as a fallback) at least by guessing it from the filename.
  

 

Query Options

 
 

-q

Performs a query for apxs`s knowledge about certain settings. The query parameters can be one or more of the following strings: CC, CFLAGS, CFLAGS_SHLIB, INCLUDEDIR, LD_SHLIB, LDFLAGS_SHLIB, LIBEXECDIR, LIBS_SHLIB, SBINDIR, SYSCONFDIR, TARGET. .PP Use this for manually determining settings. For instance use .nf INC=-I`apxs -q INCLUDEDIR` .fi .PP inside your own Makefiles if you need manual access to Apache`s C header files.
  

 

Configuration Options

 
 

-S name=value

This option changes the apxs settings described above.
  

 

Template Generation Options

 
 

-g

This generates a subdirectory name (see option -n) and there two files: A sample module source file named mod_name.c which can be used as a template for creating your own modules or as a quick start for playing with the apxs mechanism. And a corresponding Makefile for even easier build and installing of this module.
  

 

DSO Compilation Options

 
 

-c

This indicates the compilation operation. It first compiles the C source files (.c) of files into corresponding object files (.o) and then builds a dynamically shared object in dsofile by linking these object files plus the remaining object files (.o and .a) of files. If no -o option is specified the output file is guessed from the first filename in files and thus usually defaults to mod_name.so.

-o dsofile

Explicitly specifies the filename of the created dynamically shared object. If not specified and the name cannot be guessed from the files list, the fallback name mod_unknown.so is used.

-D name=value

This option is directly passed through to the compilation command(s). Use this to add your own defines to the build process.

-I incdir

This option is directly passed through to the compilation command(s). Use this to add your own include directories to search to the build process.

-L libdir

This option is directly passed through to the linker command. Use this to add your own library directories to search to the build process.

-l libname

This option is directly passed through to the linker command. Use this to add your own libraries to search to the build process.

-Wc,compiler-flags

This option passes compiler-flags as additional flags to the compiler command. Use this to add local compiler-specific options.

-Wl,linker-flags

This option passes linker-flags as additional flags to the linker command. Use this to add local linker-specific options.
  

 

DSO Installation and Configuration Options

  
 

-i

This indicates the installation operation and installs one or more dynamically shared objects into the server`s modules directory.

-a

This activates the module by automatically adding a corresponding LoadModule line to Apache`s httpd.conf configuration file, or by enabling it if it already exists.

-A

Same as option -a but the created LoadModule directive is prefixed with a hash sign (#), i.e., the module is just prepared for later activation but initially disabled.

-e

This indicates the editing operation, which can be used with the -a and -A options similarly to the -i operation to edit Apache`s httpd.conf configuration file without attempting to install the module.
  

 

EXAMPLES

 

Assume you have an Apache module named mod_foo.c available which should extend Apache`s server functionality. To accomplish this you first have to compile the C source into a shared object suitable for loading into the Apache server under runtime via the following command:
 

$ apxs -c mod_foo.c gcc -fpic -DSHARED_MODULE -I/path/to/apache/include -c mod_foo.c ld -Bshareable -o mod_foo.so mod_foo.o $ _

 

Then you have to update the Apache configuration by making sure a LoadModule directive is present to load this shared object. To simplify this step apxs provides an automatic way to install the shared object in its "modules" directory and updating the httpd.conf file accordingly. This can be achieved by running:
 

$ apxs -i -a mod_foo.c cp mod_foo.so /path/to/apache/modules/mod_foo.so chmod 755 /path/to/apache/modules/mod_foo.so [activating module `foo` in /path/to/apache/etc/httpd.conf] $ _

 

This way a line named
 

LoadModule foo_module modules/mod_foo.so

 

is added to the configuration file if still not present. If you want to have this disabled per default use the -A option, i.e.
 

$ apxs -i -A mod_foo.c

 

For a quick test of the apxs mechanism you can create a sample Apache module template plus a corresponding Makefile via:
 

$ apxs -g -n foo Creating [DIR] foo Creating [FILE] foo/Makefile Creating [FILE] foo/mod_foo.c $ _

 

Then you can immediately compile this sample module into a shared object and load it into the Apache server:
 

$ cd foo $ make all reload apxs -c mod_foo.c gcc -fpic -DSHARED_MODULE -I/path/to/apache/include -c mod_foo.c ld -Bshareable -o mod_foo.so mod_foo.o apxs -i -a -n "foo" mod_foo.so cp mod_foo.so /path/to/apache/modules/mod_foo.so chmod 755 /path/to/apache/modules/mod_foo.so [activating module `foo` in /path/to/apache/etc/httpd.conf] apachectl restart /path/to/apache/sbin/apachectl restart: httpd not running, trying to start [Tue Mar 31 11:27:55 1998] [debug] mod_so.c(303): loaded module foo_module /path/to/apache/sbin/apachectl restart: httpd started $ _

 

You can even use apxs to compile complex modules outside the Apache source tree, like PHP3:
 

$ cd php3 $ ./configure --with-shared-apache=../apache-1.3 $ apxs -c -o libphp3.so mod_php3.c libmodphp3-so.a gcc -fpic -DSHARED_MODULE -I/tmp/apache/include -c mod_php3.c ld -Bshareable -o libphp3.so mod_php3.o libmodphp3-so.a $ _

 

because apxs automatically recognized C source files and object files. Only C source files are compiled while remaining object files are used for the linking phase.
 

archive

NAME

archive - Usenet article archiver  

SYNOPSIS

archive [ -a archive ] [ -c ] [ -f ] [ -i index ] [ -p newsgroups list ] [ -r ] [ input ]  

DESCRIPTION

Archive makes copies of files specified on its standard input. It is normally run either as a channel feed under innd(8), or by a script before expire(8) is run.

Archive reads the named input file, or standard input if no file is given. The input is taken as a set of lines. Blank lines and lines starting with a number sign (``#``) are ignored. All other lines should specify the token of an article to archive. Every article is retrieved from a token and the Xref: header is used to determine the target file in the archive directory. You can limit the targets taken from the Xref: header with the ``-p`` option.

Files are copied to a directory within the archive directory, <patharchive in inn.conf>. The default is to create a hierarchy that mimics the input files; intermediate directories will be created as needed. For example, if the input token represents article 2211 in the newsgroup comp.sources.unix, it will be copied to <patharchive in inn.conf>/comp/sources/unix/2211.)  

OPTIONS

-a archive

If the ``-a`` flag is used then its argument specifies the directory to archive in instead of the default.

-c

If the ``-c`` flag is used, then all directory names will be flattened out, replacing the slashes with periods; and all posts will be concatenated into a single file with the final component name being YYYYMM which means the local execution time of archive(8). In this case, on December 14, 1998, the file would be copied to <patharchive in inn.conf>/comp.sources.unix/199812. Note: The ``-c`` flag implies the ``-f`` flag.

-f

If the ``-f`` flag is used, then all directory names will be flattened out, replacing the slashes with periods. In this case, the file would be copied to <patharchive in inn.conf>/comp.sources.unix/2211.

-i

If the ``-i`` flag is used, then archive will append one line to the specified index file for each article that it copies. This line will contain the destination name and the Message-ID and Subject headers.

-p

Limits the targets taken from the Xref: header to the groups specified in the newsgroups list. The newsgroups list is a comma separated wildmat(3) list of newsgroups you wish to have archive handle.

-r

By default, archive sets its standard error to <pathlog in inn.conf>/errlog. To suppress this redirection, use the ``-r`` flag.

 

EXIT STATUS

If the input is exhausted, archive will exit with a zero status. If an I/O error occures, it will try to spool its input, copying it to a file. If there was no input filename, the standard input will be copied to <pathoutgoing in inn.conf>/archive and the program will exit. If an input filename was given, a temporary file named input.bch (if input is an absolute pathname) or <pathoutgoing in inn.conf>/input.bch (if the filename does not begin with a slash) is created. Once the input is copied, archive will try to rename this temporary file to be the name of the input file, and then exit.

 

EXAMPLES

A typical newsfeeds(5) entry to archive most source newsgroups is as follows:

source-archive :!*,*sources*,!*wanted*,!*.d :Tc,Wn :<PREFIX specified with --prefix at configure>/archive -f -i <patharchive in inn.conf>/INDEX

 

HISTORY

Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews. This is revision 1.7.2.1, dated 2000/08/17.  

SEE ALSO

inn.conf(5), newsfeeds(5).

arping

NAME

arping - send ARP REQUEST to a neighbour host  

SYNOPSIS

arping [ -AbDfhqUV] [ -c count] [ -w deadline] [ -s source] -I interface destination

 

DESCRIPTION

Ping destination on device interface by ARP packets, using source address source.  

OPTIONS

-A

The same as -U, but ARP REPLY packets used instead of ARP REQUEST.

-b

Send only MAC level broadcasts. Normally arping starts from sending broadcast, and switch to unicast after reply received.

-c count

Stop after sending count ARP REQUEST packets. With deadline option, arping waits for count ARP REPLY packets, until the timeout expires.

-D

Duplicate address detection mode (DAD). See RFC2131, 4.4.1. Returns 0, if DAD succeeded i.e. no replies are received

-f

Finish after the first reply confirming that target is alive.

-I interface

Name of network device where to send ARP REQUEST packets. This option is required.

-h

Print help page and exit.

-q

Quiet output. Nothing is displayed.

-s source

IP source address to use in ARP packets. If this option is absent, source address is:

*

In DAD mode (with option -D) set to 0.0.0.0.

*

In Unsolicited ARP mode (with options -U or -A) set to destination.

*

Otherwise, it is calculated from routing tables.

-U

Unsolicited ARP mode to update neighbours` ARP caches. No replies are expected.

-V

Print version of the program and exit.

-w deadline

Specify a timeout, in seconds, before arping exits regardless of how many packets have been sent or received. In this case arping does not stop after count packet are sent, it waits either for deadline expire or until count probes are answered.

 

SEE ALSO

ping(8), clockdiff(8), tracepath(8).  

AUTHOR

arping was written by Alexey Kuznetsov <kuznet@ms2.inr.ac.ru>.  

SECURITY

arping requires CAP_NET_RAWIO capability to be executed. It is not recommended to be used as set-uid root, because it allows user to modify ARP caches of neighbour hosts.  

AVAILABILITY

arping is part of iputils package and the latest versions are available in source form for anonymous ftp ftp://ftp.inr.ac.ru/ip-routing/iputils-current.tar.gz.

arptables

NAME

arptables - administration tool for arp packet filtering  

SYNOPSIS

arptables [-t table] -[AD] chain rule-specification [options]
arptables [-t table] -I chain [rulenum] rule-specification [options]
arptables [-t table] -R chain rulenum rule-specification [options]
arptables [-t table] -D chain rulenum [options]
arptables [-t table] -[LFZ] [chain] [options]
arptables [-t table] -N chain
arptables [-t table] -X [chain]
arptables [-t table] -P chain target [options]
arptables [-t table] -E old-chain-name new-chain-name  

DESCRIPTION

Arptables is used to set up, maintain, and inspect the tables of ARP packet filter rules in the Linux kernel. Several different tables may be defined. Each table contains a number of built-in chains and may also contain user-defined chains.

Each chain is a list of rules which can match a set of packets. Each rule specifies what to do with a packet that matches. This is called a `target`, which may be a jump to a user-defined chain in the same table.

 

TARGETS

A firewall rule specifies criteria for a packet, and a target. If the packet does not match, the next rule in the chain is the examined; if it does match, then the next rule is specified by the value of the target, which can be the name of a user-defined chain or one of the special values ACCEPT, DROP, QUEUE, or RETURN.

ACCEPT means to let the packet through. DROP means to drop the packet on the floor. QUEUE means to pass the packet to userspace (if supported by the kernel). RETURN means stop traversing this chain and resume at the next rule in the previous (calling) chain. If the end of a built-in chain is reached or a rule in a built-in chain with target RETURN is matched, the target specified by the chain policy determines the fate of the packet.  

TABLES

There is normally one table ("filter") included in the arptable_filter module. Which tables are present at any time depends on the kernel configuration options and which modules are present.

-t, --table table

This option specifies the packet matching table which the command should operate on. If the kernel is configured with automatic module loading, an attempt will be made to load the appropriate module for that table if it is not already there.

The tables are as follows:

filter

This is the default table (if no -t option is passed). It contains the built-in chains INPUT (for ARP packets entering the box), OUTPUT (for locally-generated ARP packets).

 

OPTIONS

The options that are recognized by arptables can be divided into several different groups.  

COMMANDS

These options specify the specific action to perform. Only one of them can be specified on the command line unless otherwise specified below. For all the long versions of the command and option names, you need to use only enough letters to ensure that arptables can differentiate it from all other options.

-A, --append chain rule-specification

Append one or more rules to the end of the selected chain. When the source and/or destination names resolve to more than one address, a rule will be added for each possible address combination.

-D, --delete chain rule-specification

-D, --delete chain rulenum

Delete one or more rules from the selected chain. There are two versions of this command: the rule can be specified as a number in the chain (starting at 1 for the first rule) or a rule to match.

-I, --insert chain [rulenum] rule-specification

Insert one or more rules in the selected chain as the given rule number. So, if the rule number is 1, the rule or rules are inserted at the head of the chain. This is also the default if no rule number is specified.

-R, --replace chain rulenum rule-specification

Replace a rule in the selected chain. If the source and/or destination names resolve to multiple addresses, the command will fail. Rules are numbered starting at 1.

-L, --list [chain]

List all rules in the selected chain. If no chain is selected, all chains are listed. As every other arptables command, it applies to the specified table (filter is the default).
Please note that it is often used with the -n option, in order to avoid long reverse DNS lookups. It is legal to specify the -Z (zero) option as well, in which case the chain(s) will be atomically listed and zeroed. The exact output is affected by the other arguments given. The exact rules are suppressed until you use

 arptables -L -v

-F, --flush [chain]

Flush the selected chain (all the chains in the table if none is given). This is equivalent to deleting all the rules one by one.

-Z, --zero [chain]

Zero the packet and byte counters in all chains. It is legal to specify the -L, --list (list) option as well, to see the counters immediately before they are cleared. (See above.)

-N, --new-chain chain

Create a new user-defined chain by the given name. There must be no target of that name already.

-X, --delete-chain [chain]

Delete the optional user-defined chain specified. There must be no references to the chain. If there are, you must delete or replace the referring rules before the chain can be deleted. If no argument is given, it will attempt to delete every non-builtin chain in the table.

-P, --policy chain target

Set the policy for the chain to the given target. See the section TARGETS for the legal targets. Only built-in (non-user-defined) chains can have policies, and neither built-in nor user-defined chains can be policy targets.

-E, --rename-chain old-chain new-chain

Rename the user specified chain to the user supplied name. This is cosmetic, and has no effect on the structure of the table.

-h

Help. Give a (currently very brief) description of the command syntax.

 

PARAMETERS

The following parameters make up a rule specification (as used in the add, delete, insert, replace and append commands).

-s, --source [!] address[/mask]

Source specification. Address can be either a network name, a hostname (please note that specifying any name to be resolved with a remote query such as DNS is a really bad idea), a network IP address (with /mask), or a plain IP address. The mask can be either a network mask or a plain number, specifying the number of 1`s at the left side of the network mask. Thus, a mask of 24 is equivalent to 255.255.255.0. A "!" argument before the address specification inverts the sense of the address. The flag --src is an alias for this option.

-d, --destination [!] address[/mask]

Destination specification. See the description of the -s (source) flag for a detailed description of the syntax. The flags --dst , --tgt and --target are aliases for this option.

-z, --source-hw [!] hwaddr[mask]

Specify the source hardware (MAC) address of the packet. hwaddr (and mask, if specified) must consist of one or more 8-bit hexidecimal numbers, separated by `:` characters. If the mask is not specified, it defaults to a number of 0xff octets equal to the length of the hwaddr specified, then 0s. The flags --source-mac , --src-hw , and --src-mac are aliases for this option.

-y, --target-hw [!] hwaddr[mask]

Specify the target hardware (MAC) address of the packet. This is similar to the --src-hw option. The flags --target-mac , --tgt-hw , --tgt-mac , --dst-hw , and --dst-mac are all aliases for this option.

-i, --in-interface [!] name

Name of an interface via which a packet is going to be received (only for packets entering the INPUT chain). When the "!" argument is used before the interface name, the sense is inverted. If the interface name ends in a "+", then any interface which begins with this name will match. If this option is omitted, any interface name will match.

-o, --out-interface [!] name

Name of an interface via which a packet is going to be sent (for packets entering the OUTPUT chain). When the "!" argument is used before the interface name, the sense is inverted. If the interface name ends in a "+", then any interface which begins with this name will match. If this option is omitted, any interface name will match.

-a, --arhln [!] value[mask]

Specify the hardware address length of the packet. Both the value and mask must be 8-bit hexidecimal numbers. Note that packets with an incorrect hardware address length field may be dropped by the lower-level layers of the network stack, which may limit the usefulness of this option.

-p, --arpop [!] value[mask]

Specify the arp operation field of the packet. The value may be either a 16-bit hexidecimal number or one of the names "Request", "Reply", "Request_Reverse", "Reply_Reverse", "DRARP_Request", "DRARP_Reply", "DRARP_Error", "InARP_Request", or "ARP_NAK". The mask (if specified) must be a 16-bit hexidecicmal number.

-H, --arhrd [!] value[mask]

Specify the hardware type field of the packet. The value may be either a 16-bit hexidecimal number or the name "Ethernet". The mask (if specified) must be a 16-bit hexidecimal number.

-w, --arpro [!] value[value]

Specify the protocol type field of the packet. The value may be eithe a 16-bit hexidecimal numebr or the name "IPV4". The mask (if specified) must be a 16-bit hexidecimal number.

-j, --jump target

This specifies the target of the rule; i.e., what to do if the packet matches it. The target can be a user-defined chain (other than the one this rule is in), or one of the special builtin targets which decide the fate of the packet immediately. Unlike iptables, extensions are not yet implemented. If this option is omitted in a rule, then matching the rule will have no effect on the packet`s fate, but the counters on the rule will be incremented.

-c, --set-counters PKTS BYTES

This enables the administrator to initialize the packet and byte counters of a rule (during INSERT, APPEND, REPLACE operations).

 

OTHER OPTIONS

The following additional options can be specified:

-v, --verbose

Verbose output. This option makes the list command show the interface name, the rule options (if any), and the TOS masks. The packet and byte counters are also listed, with the suffix `K`, `M` or `G` for 1000, 1,000,000 and 1,000,000,000 multipliers respectively (but see the -x flag to change this). For appending, insertion, deletion and replacement, this causes detailed information on the rule or rules to be printed.

-n, --numeric

Numeric output. IP addresses and port numbers will be printed in numeric format. By default, the program will try to display them as host names, network names, or services (whenever applicable).

-x, --exact

Expand numbers. Display the exact value of the packet and byte counters, instead of only the rounded number in K`s (multiples of 1000) M`s (multiples of 1000K) or G`s (multiples of 1000M). This option is only relevant for the -L command.

--line-numbers

When listing rules, add line numbers to the beginning of each rule, corresponding to that rule`s position in the chain.

--modprobe=command

When adding or inserting rules into a chain, use command to load any necessary modules (targets, match extensions, etc).

 

MANGLE OPTIONS

The kernel mangle module supports the following options

--mangle-ip-s IP address

Change the source IP address of the packet to the specified value.

--mangle-ip-d IP address

Change the destination IP address of the packet to the specified value.

--mangle-hw-s hardware address

CHange the source hardware (MAC) address of the packet to the specified value.

--mangle-hw-d hardware address

Change the destination hardware (MAC) address of the packet to the specified value.

--mangle-target target

Disposition of the packet. Valid targets are DROP, CONTINUE, or ACCEPT. If no --mangle-target option is specified, the default is ACCEPT.

 

EXAMPLES

Let`s say you have a machine with two ip addresses aaaa and bbbb. Address aaaa is only for the use of machine cccc. No other machine should be allowed to connect to it. Iptables rules are configured to enforce this requirement.

# Configure iptables to NAT any attempt to use aaaa on # outgoing packets to machines other than cccc to use # bbbb instead iptables -t nat -A POSTROUTING -s aaaa ! -d cccc -j SNAT --to bbbb # Ignore arp requests from machines other than cccc for # address aaaa. arptables -A IN ! -s cccc -d aaaa -j DROP # Mangle any outgoing requests from address aaaa to any # machine but cccc to use address bbbb instead. arptables -A OUT -s aaaa ! -d cccc -j mangle --mangle-ip-s bbbb

 

DIAGNOSTICS

Various error messages are printed to standard error. The exit code is 0 for correct functioning. Errors which appear to be caused by invalid or abused command line parameters cause an exit code of 2, and other errors cause an exit code of 1.  

BUGS

The -L -v output is excessively wide.

The short option names were chosen at random.

Well... the counters are not reliable on sparc64.

 

SEE ALSO

arptables-save(8), arptables-restore(8), iptables(8), iptables-save(8), iptables-restore(8), ip6tables(8), ip6tables-save(8), ip6tables-restore(8).

See http://www.netfilter.org/.  

AUTHORS

Jay Fenlason <fenlason@redhat.com> wrote arptables, which was based on the iptables code by Rusty Russell, in early consultation with Michael Neuling.

The iptables man page was written by Herve Eychenne <rv@wallfire.org>, Jay Fenlason <fenlason@redhat.com> adapted it for arptables.

arptables-save

NAME

arptables-save - Save ARP Tables  

SYNOPSIS

arptables-save [-c] [-t table]
 

DESCRIPTION

arptables-save is used to dump the contents of an ARP Table in easily parseable format to STDOUT. Use I/O-redirection provided by your shell to write to a file.

-c, --counters

include the current values of all packet and byte counters in the output

-t, --table tablename

restrict output to only one table. If not specified, output includes all

available tables.

 

BUGS

None known as of arptables-jf-0.0.0 release  

AUTHOR

Harald Welte <laforge@gnumonks.org>  

SEE ALSO

arptables-restore(8), arptables(8)

atalkd

NAME

atalkd - AppleTalk RTMP, NBP, ZIP, and AEP manager  

SYNOPSIS

/usr/sbin/atalkd [ -f configfile ] [ -1 | -2 ]  

DESCRIPTION

atalkd is responsible for all user level AppleTalk network management. This includes routing, name registration and lookup, zone lookup, and the AppleTalk Echo Protocol (similar to ping(8)). atalkd is typically started at boot time, out of /etc/rc. It first reads from its configuration file, /etc/atalk//atalkd.conf. If there is no configuration file, atalkd will attempt to configure all available interfaces and will create a configuration file. The file consists of a series of interfaces, one per line. Lines with `#` in the first column are ignored, as are blank lines. The syntax is

interface [ -seed ] [ -phase number ] [ -net net-range ] [ -addr address ] [ -zone zonename ] ...

Note that all field except the interface are optional. The loopback interface is configured automatically. If -seed is specified, all other fields must be present. Also, atalkd will exit during bootstrapping, if a router disagrees with its seed information. If -seed is not given, all other information may be overriden during auto-configuration. If no -phase option is given, the default phase as given on the command line is used (the default is 2). If -addr is given and -net is not, a net-range of one is assumed.

The first -zone directive for each interface is the ``default`` zone. Under Phase 1, there is only one zone. Under Phase 2, all routers on the network are configured with the default zone and must agree. atalkd maps ``*`` to the default zone of the first interface. Note: The default zone for a machine is determined by the configuration of the local routers; to appear in a non-default zone, each service, e.g. afpd, must individually specify the desired zone. See also nbp_name(3).  

ROUTING

If you are connecting a netatalk router to an existing AppleTalk internet, you should first contact your local network administrators to obtain appropriate network addresses.

atalkd can provide routing between interfaces by configuring multiple interfaces. Each interface must be assigned a unique net-range between 1 and 65279 (0 and 65535 are illegal, and addresses between 65280 and 65534 are reserved for startup). It is best to choose the smallest useful net-range, i.e. if you have three machines on an Ethernet, don`t chose a net-range of 1000-2000. Each net-range may have an arbitrary list of zones associated with it.  

EXAMPLE

Below is an example configuration file for a sun4/40. The machine has two interfaces, ``le0`` and ``le1``. The ``le0`` interface is configured automatically from other routers on the network. The machine is the only router for the ``le1`` interface.

le0 le1 -seed -net 9461-9471 -zone netatalk -zone Argus

atalkd automatically acts as a router if there is more than one interface.  

FILES

/etc/atalk//atalkd.conf

configuration file

 

BUGS

On some systems, atalkd can not be restarted.

atrun

NAME

atrun - run jobs queued for later execution  

SYNOPSIS

atrun [-l load_avg] [-d]  

DESCRIPTION

atrun runs jobs queued by at(1). It is a shell script invoking /usr/sbin/atd with the -s option, and is provided for backward compatibility with older installations.  

SEE ALSO

at(1), atd(8).  

AUTHOR

At was mostly written by Thomas Koenig, ig25@rz.uni-karlsruhe.de.

autofs

NAME

/etc/rc.d/init.d/autofs - Control Script for automounter  

SYNOPSIS

/etc/rc.d/init.d/autofs start|stop|reload  

DESCRIPTION

autofs control the operation of the automount(8) daemons running on the Linux system. Usually autofs is invoked at system boot time with the start parameter and at shutdown time with the stop parameter. The autofs script can also manually be invoked by the system administrator to shut down, restart or reload the automounters.  

OPERATION

autofs will consult a configuration file /etc/auto.master (see auto.master(5)) to find mount points on the system. For each of those mount points a automount(8) process is started with the appropriate parameters. You can check the active mount points for the automounter with the /etc/rc.d/init.d/autofs status command. After the auto.master configuration file is processed the autofs script will check for an NIS map with the same name. If such a map exists then that map will be processed in the same way as the auto.master map. The NIS map will be processed last. /etc/rc.d/init.d/autofs reload will check the current auto.master map against running daemons. It will kill those daemons whose entries have changed and then start daemons for new or changed entries. If a map is modified then the change will become effective immediately. If the auto.master map is modified then the autofs script must be rerun to activate the changes. /etc/rc.d/init.d/autofs status will display the current configuration and a list of currently running automount daemons.  

SEE ALSO

automount(8), autofs(5), auto.master(5).  

AUTHOR

This manual page was written by Christoph Lameter <chris@waterf.org>, for the Debian GNU/Linux system. Edited by H. Peter Anvin <hpa@transmeta.com>.

automount

NAME

automount - configure mount points for autofs  

SYNOPSIS

automount [options] mount-point map-type[,format] map [map-options]  

DESCRIPTION

The automount program is used to configure a mount point for autofs, the inlined Linux automounter. automount works by taking a base mount-point and map file, and using these (combined with other options) to automatically mount filesystems within the base mount-point when they are accessed in any way. The filesystems are then autounmounted after a period of inactivity.  

OPTIONS

-p, --pid-file

Write the pid of the daemon to the specified file.

-t, --timeout

Set the minimum timeout, in seconds, until directories are unmounted. The default is 5 minutes. Setting the timeout to zero disables unmounts completely.

-v, --verbose

Enables printing of general status and progress messages.

-d, --debug

Enables printing of general status and progress messages as well as debuging messages.

-g, --ghost

Request that directories in the automount be shown but not mounted until accesssed. The wildcard map is not ghosted.

-V, --version

Display the version number, then exit.

 

ARGUMENTS

automount takes at least three arguments. Mandatory arguments include mount-point, map-type and map. Both mandatory and optional arguments are described below.

mount-point

Base location for autofs-mounted filesystems to be attached. This is a directory name which must already exist.

map-type

Type of map used for this invocation of automount. The following are valid map types:

file

The map is a regular text file.

program

The map is an executable program, which is passed a key on the command line and returns an entry on stdout if successful.

yp

The map is a NIS (YP) database.

nisplus

The map is a NIS+ database.

hesiod

The map is a hesiod database whose filsys entries are used for maps.

ldap

map names are of the form [//servername/]basedn, where the optional servername is the name of the LDAP server to query, and basedn is the DN to do a subtree search under. Two LDAP schema are supported. The i automountMap and the nisMap (RFC 2307) object classes. Entries in the automountMap schema are automount objects in the specified subtree, where the cn attribute is the key (the wildcard key is "/"), and the automountInformation attribute contains the information used by the automounter. Documentation on the schema used by this module is available online at http://docs.sun.com/source/806-4251-10/mapping.htm. RFC 2307 schema entries are nisObject objects and use the cn attribute as the key and the nisMapEntry contains information used by the automounter.

format Format of the map data; currently the only formats

recognized are sun, which is a subset of the Sun automounter map format, and hesiod, for hesiod filesys entries. If the format is left unspecified, it defaults to sun for all map types except hesiod.

map

Location of mapfile to use. This is an absolute UNIX pathname in the case for maps of types file or program, and the name of a database in the case for maps of type yp, nisplus, or hesiod.

options

Any remaining command line arguments without leading dashes (-) are taken as options (-o) to mount. Arguments with leading dashes are considered options for the maps.

The sun format supports the following options:

-Dvariable=value

Replace variable with value in map substitutions.

-strict

Treat errors when mounting file systems as fatal. This is important when multiple file systems should be mounted (`multimounts`). If this option is given, no file system is mounted at all if at least one file system can`t be mounted.

 

NOTES

If the automount daemon catches signal USR1, it will unmount all currently unused autofs-mounted filesystems and continue running (forced expire). If it catches signals TERM or USR2 it will unmount all unused autofs-mounted filesystems and exit if all filesystems were unmounted. Busy filesystems will not be unmounted. The daemon also responds to a HUP signal which triggers an update of maps for which ghosting is implemented (currently FILE and NIS maps). If the autofs directory itself is busy when the daemon is signalled with an exit signal then the daemon will exit without unmounting the autofs filesystem. The filesystem is left in a catatonic (non-functional) state, and can be unmounted when it becomes unused.  

SEE ALSO

autofs(5), mount(8).  

BUGS

A whole slew of missing desirable features (see TODO file).

The documentation leaves a lot to be desired.

Please report other bugs along with a detailed description to <autofs@linux.kernel.org>. To join this mailing list, send a message with the line "subscribe autofs" to <majordomo@linux.kernel.org>.  

AUTHOR

H. Peter Anvin <hpa@transmeta.com>

avmcapictrl

NAME

avmcapictrl - Add, reset or remove active AVM cards and load firmware  

SYNOPSIS

avmcapictrl add <portbase> <irq> <type>
avmcapictrl load <bootcode> [<contrnr> [<protocol>

    [P2P | <dn1>:<spid1> [<dn2>:<spid2>]]]]
avmcapictrl reset [contrnr]
avmcapictrl remove [contrnr]
avmcapictrl trace [contrnr] [off|short|on|full|shortnodata|nodata]
avmcapictrl addcard <driver> <portbase> <irq> [ <membase> [ <cardnr> ] ]  

DESCRIPTION

avmcapictrl is used to register active AVM ISA cards kernelcapi system and therewith to the isdn system. You need it also to upload the firmware to any active AVM card. If an error occure please also check the kernel error messages by using the command dmesg(8).

 

COMMANDS

add <portbase> <irq> <type>

is used to add a ISA card to the kernel-capi2.0 system. The portbase can have the values 0x150, 0x250, 0x300 and 0x340 for the B1 ISA cards, look at the jumper on the card. For a T1-ISA (HEMA) card you can select an wide range of ports.
irq can be selected from the following values:
3, 4, 5, 6, 7, 9, 10, 11, 12 and 15.
type can be B1 or T1.

load <bootcode> [<contrnr> [<protocol>

[P2P | <dn1>:<spid1> [<dn2>:<spid2>]]]] is used to load the firmware to a card bootcode is a t4-file. The actual versions of the t4-files for the different d-channel protocols can be found at ftp://ftp.avm.de/cardware/b1/linux/firmware.
You need different t4-files for different d channel protocols: b1-1tr6.t4 for 1TR6, b1.t4 for DSS1 and
b1-usa.t4 for 5ESS and NI1 (DSS1 is also supported).
For M1/M2 PCMCIA cards you need m1-s10.t4 or m1-s4.t4 depending on the handy type used.
contrnr is the number of the controller (card) starting from 1.
protocol can be DSS1, CT1, VN3, AUSTEL, 5ESS or NI1.
P2P point to point
DN1:SPID1 DN2:SPID2 is for the american protocols 5ESS and NI1.

reset [contrnr]

is used to reset a card if loading has failed. This function only make sence if card is not successfully loaded.
contrnr is the number of the controller (card) starting from 1.

remove [contrnr]

is used to remove a card previous added. You can also remove automatic added cards (for example a B1-PCI card).
contrnr is the number of the controller (card) starting from 1.

trace [contrnr] [off|short|on|full|shortnodata|nodata]

is used to trace CAPI2.0 messages. The trace will be done as kernel messages, see dmesg(8).
contrnr is the number of the controller (card) starting from 1.
off switch traceing off
short switch one line per CAPI2.0 message tracing on
on | full switch on full decode tracing
shortnodata switch on line per CAPI2.0 message tracing on, but exclude DATA_B3_IND and DATA_B3_REQ messages.
on | full switch on full decode tracing, but exclude DATA_B3_IND and DATA_B3_REQ messages.

addcard <driver> <portbase> <irq> [ <membase> [ <cardnr> ] ]

is used to add a card, this is more generic than add.
driver currently b1isa or t1isa
portbase can have the values 0x150, 0x250, 0x300 and 0x340 for the b1isa driver, look at the jumper on the card. For t1isa driver you can select an wide range of ports.
irq can be selected from the following values: 3, 4, 5, 6, 7, 9, 10, 11, 12 and 15.
membase memory address if needed by driver
cardnr only usefull with driver t1isa

 

AUTHOR

Carsten Paeth <calle@calle.in-berlin.de>

 

SEE ALSO

ttyI(4), isdnctrl(8), isdninfo(4). dmesg(8). syslogd(8).

batcher

NAME

batcher - article batching backend for InterNetNews  

SYNOPSIS

batcher [ -a arts ] [ -A total_arts ] [ -b size ] [ -B total_size ] [ -i string ] [ -N num_batches ] [ -p process ] [ -r ] [ -s separator ] [ -S alt_spool ] [ -v ] host [ input ]  

DESCRIPTION

Batcher reads uses a list of files to prepare news batches for the specified host. It is normally invoked by a script run out of cron(8) that uses shlock(1) to lock the host name, followed by a ctlinnd(8) command to flush the batchfile.

Batcher reads the named input file, or standard input if no file is given. Relative pathnames are interpreted from the <pathoutgoing in inn.conf> directory. The input is taken as a set of lines. Blank lines and lines starting with a number sign (``#``) are ignored. All other lines should consist of one or two fields separated by a single space. The first field is the name of a file holding an article; if it is not an an absolute pathname it is taken relative to the news spool directory, <patharticles in inn.conf>. The second field, if present, specifies the size of the article in bytes.  

OPTIONS

-S

The ``-S`` flag may be used to specify an alternate spool directory to use if the article is not found; this would normally be an NFS-mounted spool directory of a master server with longer expiration times.

-r

By default, the program sets its standard error to <pathlog in inn.conf>/errlog. To suppress this redirection, use the ``-r`` flag.

-v

Upon exit, batcher reports statistics via syslog(3). If the ``-v`` flag is used, they will also be printed on the standard output.

-b

Batcher collects the text of the named articles into batches. To limit the size of each batch, use the ``-b`` flag. The default size is 60 kilobytes. Using ``-b0`` allows unlimited batch sizes.

-a

To limit the number of articles in each batch, use the ``-a`` flag. The default is no limit. A new batch will be started when either the byte count or number of articles written exceeds the specified limits.

-B

To limit the total number of bytes written for all batches, use the ``-B`` flag.

-A

To limit the total number of articles that can be batched use the ``-A`` flag.

-N

To limit the total number of batches that should be created use the ``-N`` flag.

In all three cases, the default is zero, which is taken to mean no limit.

-i string

A batch starts with an identifying line to specify the unpacking method to be used on the receiving end. When the ``-i`` flag is used, the initial string, string, followed by a newline, will be output at the start of every batch. The default is to have no initial string.

-s

Each article starts with a separator line to indicate the size of the article. To specify the separator use the ``-s`` flag. This is a sprintf(3) format string which can have a single ``%ld`` parameter which will be given the size of the article. If the separator is not empty, then the string and a newline will be output before every article. The default separator is ``#! rnews %ld``.

-p

By default, batches are written to standard output, which is not useful when more than one output batch is created. Use the ``-p`` flag to specify the shell command that should be created (via popen(3)) whenever a new batch is started. The process is a sprintf format string which can have a single ``%s`` parameter which will be given the host name. A common value is:

( echo `#! cunbatch` ; exec compress ) | uux - -r -z %s!rnews

 

EXIT STATUS

If the input is exhausted, batcher will exit with a zero status. If any of the limits specified with the ``-B,`` ``-A,`` or ``-N`` flags is reached, or if there is an error writing the batch, then batcher will try to spool the input, copying it to a file. If there was no input filename, the standard input will be copied to <pathoutgoing in inn.conf>/host and the program will exit. If an input filename was given, a temporary file named input.bch (if input is an absolute pathname) or <pathoutgoing in inn.conf>/input.bch (if the filename does not begin with a slash) is created. Once the input is copied, batcher will try to rename this temporary file to be the name of the input file, and then exit.

Upon receipt of an interrupt or termination signal, batcher will finish sending the current article, close the batch, and then rewrite the batchfile according as described in the previous paragraph.  

HISTORY

Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews. This is revision 1.5.6.1, dated 2000/08/17.  

SEE ALSO

ctlinnd(8), inn.conf(5), newsfeeds(5), shlock(1).

belkinunv

NAME

belkinunv - Driver for Belkin "Universal UPS" and compatible  

NOTE

This man page only documents the hardware-specific features of the belkin driver. For information about the core driver, see nutupsdrv(8).

 

SUPPORTED HARDWARE

The belkinunv driver is known to work with the Belkin Universal UPS models F6C800-UNV and F6C120-UNV, and is expected to work with other Belkin Universal UPS models. The driver only supports serial communication, not USB.

The Trust UPS and older Belkin units are not supported by this driver, and neither are the Belkin Home Office models (F6H500-SER and so forth). However, some Belkin models, such as the Regulator Pro, are supported by the belkin(8) driver, and the Home Office models are supported using the genericups(8) driver with upstype=7.

 

SOFT SHUTDOWN WORKAROUND

One problem with the Belkin Universal UPS is that it cannot enter a soft shutdown (shut down the load until AC power returns) unless the batteries are completely depleted. Thus, one cannot just shut off the UPS after operating system shutdown; it will not come back on when the power comes back on. Therefore, the belkinunv driver should never be used with the -k option. Instead, the -x wait option is provided as a workaround.

When called with the -x wait option, belkinunv behaves as a standalone program (i.e., it does not fork into the background). It performs one simple task: it connects to the UPS, waits for AC power to return, and then exits with status 0.

This is meant to be used in a shutdown script as follows: during a shutdown, after all filesystems have been remounted read-only, and just before the system would normally be halted: check /etc/killpower (or similar) to see if this shutdown was caused by upsmon(8), and if yes, call belkinunv -x wait. If AC power comes back on, belkinunv exits, and things should be arranged so that the system reboots in this case. If AC power does not come back on, the UPS will eventually run out of batteries, kill the computer`s power supply, and go into soft shutdown mode, which means everything will reboot properly when the power returns. In either case, a deadlock is avoided.

In addition, if an optional integer argument is given to the -x wait option, this causes belkinunv to wait not only for AC power to be present, but also for the battery charge to reach the given level. I use this as part of my startup scripts, to ensure that the batteries are sufficiently charged before the computer continues booting. This should be put very early in the startup script, before any filesystems are mounted read/write, and before any filesystem checks are performed.

Several other -x options are provided to fine-tune this behavior. See OPTIONS below for detailed descriptions. See EXAMPLES below for examples of how to use belkinunv in shutdown and startup scripts.

 

OPTIONS

See also nutupsdrv(8) for generic options. Never use the -k option with this driver; it does not work properly.

-x wait[=level]

When this option is used, belkinunv does not fork into the background, but behaves as a standalone program. It connects to the UPS and waits until AC power is present. If level is specified, it also waits until the battery charge reaches at least the given level in percent. Then, and only then, belkinunv exits. In addition, while belkinunv runs in this mode, it displays a status line with information on the UPS status and battery level. This is intended for use in the computer`s shutdown and startup scripts, as described under SOFT SHUTDOWN WORKAROUND above.

-x nohang

This option only has an effect when used in conjunction with the -x wait option. It causes belkinunv to exit if a connection with the UPS cannot be established or is lost, instead of retrying forever, which is the default behavior. The -x nohang option should be used in a startup script, to ensure the computer remains bootable even if the UPS has been disconnected during the power failure (for instance, you attached your computer to a generator, carried it to a neighbor`s house, or whatever).

-x flash

This option only has an effect when used in conjunction with the -x wait option. It causes the UPS load to be shut off for a short time ("flashed") just after the AC power has returned and the requested battery level (if any) has been attained. This is useful if slaves are attached to this UPS; the flash will cause all of them to reboot. Note that, due to the design of the Belkin UPS hardware, the load shutdown lasts ca. 1-2 minutes; a shorter flash cannot be performed reliably. Also, the computers will reboot at the scheduled time, on battery power if necessary, even if AC power fails again in the meantime. This should not be a problem, as your startup scripts can catch this situation.

-x silent

This option only has an effect when used in conjunction with the -x wait option. It suppresses the status line which belkinunv would normally print.

-x dumbterm

This option only has an effect when used in conjunction with the -x wait option. It changes the way in which belkinunv prints its status line. Normally, terminal control sequences are used to overwrite the same line with new status information, each time the status is updated. This may not work on all terminals. If the -x dumbterm option is given, each status update is written on a new line.

 

VARIABLES:

battery.charge

battery.runtime

not supported by all hardware.

battery.voltage

battery.voltage.nominal

driver.version.internal

input.frequency

input.frequency.nominal

e.g. 60 for 60Hz

input.sensitivity               

writable: normal/medium/low

input.transfer.high

writable: high transfer voltage point in V

input.transfer.low

writable: low transfer voltage point in V

input.voltage

input.voltage.maximum

input.voltage.minimum

input.voltage.nominal

output.frequency

output.voltage

ups.beeper.enable

writable. Values: yes/no. This variable determines whether the panel beeper is on or off. Note that the beeper is automatically turned back on at the next event (AC failure, battery test, etc). It can be turned off when it is already beeping. Also, the beeper can`t be turned off during a critical event (low battery).

ups.firmware

ups.load

ups.model

ups.power.nominal

e.g. 800 for an 800VA system

ups.status

a list of flags; see STATUS FLAGS below.

ups.temperature

not supported by all hardware.

ups.test.result

ups.timer.restart

time to restart (read only)

ups.timer.shutdown

time to shutdown (read only). This is always a multiple of 60 seconds.

ups.type

ONLINE/OFFLINE/LINEINT. This describes the basic layout of this UPS (for GUI clients which want to draw an animated picture of power flow). An offline UPS has a direct connection from AC input to AC output, and also a connection from AC input to the battery, and from the battery to AC output. An online UPS lacks the direct connection from AC input to AC output, whereas a line interactive UPS lacks the connection from AC input to the battery.

 

COMMANDS:

beeper.on, beeper.off

turn the panel beeper on or off. Note that the beeper is automatically turned back on at the next event (AC failure, battery test, etc). It can be turned off when it is already beeping. Also, the beeper can`t be turned off during a critical event (low battery).

reset.input.minmax

reset the variables input.voltage.minimum and input.voltage.maximum.

shutdown.reboot

shut down load immediately for ca. 1-2 minutes

shutdown.reboot.graceful

after 40-second delay, shut down load for ca. 1-2 minutes

shutdown.stayoff

shut down load immediately and stay off. The only way it can be turned back on is by manually pressing the front panel button.

test.battery.start, test.battery.stop

start/stop 10-second battery test

test.failure.start, test.failure.stop

start/stop "deep" battery test

 

STATUS FLAGS:

OB

load is on battery, including during tests

OFF

load is off

OL

load is online

ACFAIL

AC failure. Note that this refers to the AC input, and thus it is not the same as "OB". An AC failure can occur at any time, for instance, during a battery test, or when the UPS load is off.

OVER

overload

OVERHEAT

overheat

COMMFAULT

UPS fault

LB

low battery

CHRG

charging

DEPLETED

the battery is depleted. When the UPS raises this flag, it simultaneously switches off the load.

RB

replace battery

 

EXAMPLES

Here is an example for how belkinunv should be used in a computer`s shutdown script. These commands should go in the very last part of the shutdown script, after all file systems have been mounted read-only, and just before the computer halts. Note that belkinunv must be installed in a directory which is still readable at that point.

# NEAR END OF SHUTDOWN SCRIPT: # if shutdown was caused by UPS, perform Belkin UPS workaround. if [ -f /etc/killpower ] ; then echo "Waiting for AC power, or for UPS batteries to run out..." /usr/bin/belkinunv -x wait /dev/ttyS1 # we get here if the power came back on. Reboot. echo "Power is back. Rebooting..." reboot fi

And here is an example of how to use belkinunv in the startup script. These commands should go near the beginning of the startup script, before any file systems are mounted read/write, and before any file system integrity checks are done.

# NEAR BEGINNING OF STARTUP SCRIPT: # if we are recovering from a power failure, wait for the UPS to # charge to a comfortable level before writing anything to disk if [ -f /etc/killpower ] ; then echo "Waiting for UPS battery charge to reach 60%..." /usr/bin/belkinunv -x wait=60 -x nohang /dev/ttyS1 fi

 

EXIT STATUS

When used normally, belkinunv forks into the background and its diagnostics are the same as for all NUT drivers, see nutupsdrv(8).

When used with the -x wait option, the exit status is normally 0. If the -x nohang option has also been specified, an exit status of 1 indicates that communication with the UPS was lost. If the -x flash option has been specified, an exit status of 2 indicates that the timed shutdown has failed.  

EXTRA ARGUMENTS

This driver does not support any extra settings in ups.conf(5).  

SEE ALSO

 

The documentation for the protocol used by this UPS:

belkin-universal-ups.html

 

The core driver:

nutupsdrv(8)

 

Internet resources:

The NUT (Network UPS Tools) home page: http://www.networkupstools.org/

 

AUTHOR

Peter Selinger <selinger@users.sourceforge.net>

bestups

NAME

bestups - Driver for Best Power / SOLA (Phoenixtec protocol) UPS equipment  

NOTE

This man page only documents the hardware-specific features of the bestups driver. For information about the core driver, see nutupsdrv(8).

 

SUPPORTED HARDWARE

bestups was designed to monitor Best Power UPS hardware like the Fortress, Fortress Telecom, Axxium Rackmount and Patriot Pro. It also recognizes and supports SOLA units such as the 325, 520 and 620.

Other UPS hardware using the Phoenixtec protocol should also work, but they will generate a warning since their battery information is not known.

This driver does not support some older Best/SOLA units.

 

EXTRA ARGUMENTS

This driver supports the following optional settings in the ups.conf(5):

nombattvolt=num

Override the nominal battery voltage which is normally determined by asking the hardware. This is useful if your UPS constantly reports battery.charge values just below 100% even when it`s completely charged.

If you have this problem, set this to whatever battery.voltage reports when the UPS is known to be completely charged with a good battery.

The author`s Best Fortress 750 uses nombattvolt=27.4.

 

BUGS

The battery charge percentage value (in battery.charge) is derived from the voltage data that the UPS returns, since the UPS doesn`t return that value directly. On some hardware, the charge will remain at 100% for a long time and then drops quickly shortly before the battery runs out. You can confirm from the battery.voltage readings that this is a problem with the UPS and not this driver.

Similarly, the float from the charger in some models forces the battery charge percentage back up to 100% immedately after the UPS goes back on-line, so you can`t tell when it is really recharged.

Finally, some models give one value for the battery`s nominal voltage and yet actually have a nominal voltage slightly below that. This leads to things such as the perpetual 98.7% charge on the author`s Fortress 750, even when it`s been charging for weeks. You can use nombattvolt= in ups.conf(8) to fix this.

 

AUTHOR

Russell Kroll

 

SEE ALSO

 

The core driver:

nutupsdrv(8)

 

Internet resources:

The NUT (Network UPS Tools) home page: http://www.networkupstools.org/

blkid

NAME

blkid - command-line utility to locate/print block device attributes  

SYNOPSIS

blkid ]... [ -h ] [ [ -c cachefile ] -s savecachefile ] [ -p ] [ -t token ]... [ -v ] [ device ... ]  

DESCRIPTION

The blkid program is the command-line interface to working with libuuid(3) library. It can determine the type of content (e.g. filesystem, swap) a block device holds, and also attributes (tokens, NAME=value pairs) from the content metadata (e.g. LABEL or UUID fields).

blkid has two main forms of operation: either searching for a device with a specific NAME=value pair, or displaying NAME=value pairs for one or more devices.  

OPTIONS

-c

<cachefile> Read from cachefile instead of reading from the default cache file /etc/blkid.tab. If you want to start with a clean cache (i.e. don`t report devices previously scanned but not necessarily available at this time), specify /dev/null.

-h

Display a usage message and exit.

-p

Probe all available devices. This is the default when displaying tokens. When searching for a token normally the cache file is used to locate the device and only that device is probed (to ensure cache coherency) and all devices are probed only if the token cannot be found in the cache.

-s

tag tag is of the form NAME and the resulting token is shown for each (specified) device that has such a tag. It is possible to specify multiple tag options. If no tag is specified, then all tokens are shown for all (specified) devices. In order to just refresh the cache without showing any tokens use -s none with no other options.

-t

token token is of the form NAME=value and that specific token is searched for in the cache or among all visible block devices and additionally any specified devices. If that token is not found, no output is shown. Common values for NAME include TYPE, LABEL, and UUID.

-v

Display version number and exit.

 

RETURN VALUE

The UUID of the form 1b4e28ba-2fa1-11d2-883f-b9a761bde3fb (in printf(3) format "%08x-%04x-%04x-%04x-%012x") is output to the standard output.

-w

<writecachefile> Write the device cache to writecachefile instead of writing it to the default cache file /etc/blkid.tab. If you don`t want to save the cache to the default file, specify /dev/null. If not specified it will be the same file as that given by the -c option.

<device>

Display tokens from only the specified device. It is possible to give multiple <device> options on the command line. If none is given, all devices which appear in /proc/partitions are shown, if they are recognized.

 

RETURN CODE

If the specified token was found, or if any tags were shown from (specified) devices 0 is returned. If the specified token was not found, or no (specified) devices could be identified return 2. For usage or other errors return 4.  

AUTHOR

blkid was written by Andreas Dilger for libblkid.  

AVAILABILITY

blkid is part the e2fsprogs package since version 1.26 and is available from http://e2fsprogs.sourceforge.net.  

SEE ALSO

libblkid(3)

bootparamd

NAME

bootparamd - boot parameter server  

SYNOPSIS

rpc.bootparamd [-d ] [-s ] [-r router ] [-f file ]  

DESCRIPTION

bootparamd is a server process that provides information to diskless clients necessary for booting. It consults the /etc/bootparams file to find the information it needs.

This version will allow the use of aliases on the hostname in the /etc/bootparams file. The returned hostname to the whoami request done by the booting client will be the name that appears in /etc/bootparams and not the canonical name. In this way you can keep the answer short enough so that machines that cannot handle long hostnames won`t fail during boot.  

OPTIONS

-d

Display debugging information.

-s

Log the debugging information to syslog.

-r router

The default router (a machine or an IP-address). This defaults to the machine running the server.

-f file

The file to use as boot parameter file instead of /etc/bootparams.

 

FILES

/etc/bootparams  

BUGS

You may find the syslog loggings too verbose.  

AUTHOR

Written by Klas Heggemann <klas@nada.kth.se>

buffchan

NAME

buffchan - buffered file-writing backend for InterNetNews  

SYNOPSIS

buffchan [ -b ] [ -c lines ] [ -C seconds ] [ -d directory ] [ -f fields ] [ -m map ] [ -p pidfile ] [ -l lines ] [ -L seconds ] [ -r ] [ -s file_format ] [ -u ]  

DESCRIPTION

Buffchan reads lines from standard input and copies certain fields in each line into files named by other fields within the line. Buffchan is intended to be called by innd(8) as an exploder feed.  

OPTIONS

-b

Once buffchan opens a file it keeps it open. The input must therefore never specify more files than can the number of available descriptors can keep open. If the ``-b`` flag is used, the program will allocate a buffer and attach it to the file using setbuf(3).

-c

If the ``-c`` flag is used with a number n, then buffchan will close, and re-open, a file after every n lines are written to a file.

-C

Similarly, the ``-C`` flag may be used to specify that all files should be closed and re-opened every n seconds.

-d

The ``-d`` flag may be used to specify a directory the program should change to before starting. If this flag is used, then the default for the ``-s`` flag is changed to be a simple ``%s.``

-f

Buffchan input is interpreted as a set of lines. Each line contains a fixed number of initial fields, followed by a variable number of filename fields. All fields in a line are separated by whitespace. The default number of initial fields is one; the ``-f`` flag may be used to specify a different number of fields.

-m

See filechan(8) for an example.

-p

If the ``-p`` flag is used, the program will write a line containing its process ID (in text) to the specified file.

-l

If the ``-l`` flag is used with a number n, then buffchan will call fflush(3) after every n lines are written to a file.

-L

If the ``-L`` flag is used with a number n, then all files will be flushed every n seconds.

-r

By default, the program sets its standard error to <pathlog in inn.conf>/errlog.

To suppress this redirection, use the ``-r`` flag.

-s

After the initial fields, each remaining field names a file to write. The ``-s`` flag may be used to specify a format string that maps the field to a file name. This is a sprintf(3) format string which should have a single ``%s`` parameter which will be given the field. The default value is <pathoutgoing in inn.conf>/%s. See the description of this flag in filechan(8).

-u

If the ``-u`` flag is used, the program will request unbuffered output.

Buffchan can be invoked as an exploder feed (see newsfeeds(5)). As such, if a line starts with an exclamation point it will be treated as a command. There are three commands, described below:

flush

The ``flush`` command closes and re-opens all open files; ``flush xxx`` which flushes only the specified site. These are analogous to the ctlinnd(8) ``flush`` command, and can be achieved by doing a ``send "flush xxx"`` command. Applications can tell that the ``flush`` has completed by renaming the file before issuing the command; buffchan has completed the command when the original filename re-appears. If <$ac_cv_func_fchmod in config.cache> is ``yes``, then buffchan also changes the access permissions of the file from read-only for everyone to read-write for owner and group as it flushes or closes each output file. It will change the modes back to read-only if it re-opens the same file.

drop

The ``drop`` command is similar to the ``flush`` command except that any files are not re-opened. If given an argument, then the specified site is dropped, otherwise all sites are dropped. (Note that the site will be restarted if the input stream mentions the site.) When a ctlinnd ``drop site`` command is sent, innd will automatically forward the command to buffchan if the site is a funnel that feeds into this exploder. To drop all sites, use the ctlinnd ``send buffchan-site drop`` command.

readmap

The map file (specified with the ``-m`` flag) is reloaded.

 

HISTORY

Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews. This is revision 1.6.6.1, dated 2000/08/17.  

SEE ALSO

ctlinnd(8), filechan(8), inn.conf(5), innd(8), newsfeeds(5).

capiinfo

NAME

capiinfo - Show supported features of all installed CAPI2.0 controllers  

SYNOPSIS

capiinfo  

DESCRIPTION

The capiinfo program checks how many controllers are installed and calls CAPI_GET_PROFILE for each of them. Also it sends a FACILITY_REQ capi message to get the information for the facilities supported by each controller. The information is shown on STDOUT.

 

SEE ALSO

capiinit(8)
http://www.capi.org/ (CAPI 2.0 specification)

 

AUTHORS

Carsten Paeth (calle@calle.in-berlin.de)

cardctl

NAME

cardctl - PCMCIA card control utility

 

SYNOPSIS

cardctl [-V] command [socket]
cardctl [-c config] [-f scheme] [-s stab] scheme [name]

 

DESCRIPTION

Cardctl is used to monitor and control the state of PCMCIA sockets. If a socket number is specified, the command will be applied to just one socket; otherwise, all sockets will be affected.

Cardctl is also used to select between multiple PCMCIA configuration schemes. The current scheme name is passed to the device option scripts as part of the ``device address``, so the scripts can use it to choose between different setups.

If cardctl is executed by root, all commands are available. If it is executed by an unpriviledged user, only the informational commands are accessible.

Some commands may not work or give misleading results if cardmgr is not running.

 

COMMANDS

status

Display the current socket status flags.

config

Display the socket configuration, including power settings, interrupt and I/O window settings, and configuration registers.

ident

Display card identification information, including product identification strings, manufacturer ID codes, and function ID codes.

info

Much like the ident command, but its output is formatted as a series of Bourne-stype shell variable definitions for use in scripts.

suspend

Shut down and then disable power for a socket.

resume

Restore power to a socket, and re-configure for use.

reset

Send a reset signal to a socket, subject to approval by any drivers already bound to the socket.

eject

Notify all client drivers that this card will be ejected, then cut power to the socket.

insert

Notify all client drivers that this card has just been inserted.

scheme

If no scheme name is given, cardctl will display the current PCMCIA configuration scheme. If a scheme name is given, cardctl will unconfigure all PCMCIA devices, and reconfigure for the new scheme.

 

OPTIONS

-V

Show version information and exit.

-c config

Look for the card configuration database and card configuration scripts in the specified directory, instead of /etc/pcmcia.

-f scheme

Use the specified file to keep track of the current configuration scheme, instead of /var/lib/pcmcia/scheme.

-s stab

Read current socket information from the specified file, instead of /var/lib/pcmcia/stab.

 

AUTHOR

David Hinds - dahinds@users.sourceforge.net  

SEE ALSO

cardmgr(8).

cfdisk

NAME

cfdisk - Curses based disk partition table manipulator for Linux  

SYNOPSIS

cfdisk [ -agvz ] [ -c cylinders ] [ -h heads ] [ -s sectors-per-track ] [ -P opt ] [ device ]  

DESCRIPTION

cfdisk is a curses based program for partitioning any hard disk drive. Typical values of the device argument are:

/dev/hda [default] /dev/hdb /dev/sda /dev/sdb /dev/sdc /dev/sdd

In order to write the partition table cfdisk needs something called the `geometry` of the disk: the number of `heads` and the number of `sectors per track`. Linux does not use any geometry, so if the disk will not be accessed by other operating systems, you can safely accept the defaults that cfdisk chooses for you. The geometry used by cfdisk is found as follows. First the partition table is examined, to see what geometry was used by the previous program that changed it. If the partition table is empty, or contains garbage, or does not point at a consistent geometry, the kernel is asked for advice. If nothing works 255 heads and 63 sectors/track is assumed. The geometry can be overridden on the command line or by use of the `g` command. When partitioning an empty large modern disk, picking 255 heads and 63 sectors/track is always a good idea. There is no need to set the number of cylinders, since cfdisk knows the disk size.

Next, cfdisk tries to read the current partition table from the disk drive. If it is unable to figure out the partition table, an error is displayed and the program will exit. This might also be caused by incorrect geometry information, and can be overridden on the command line. Another way around this problem is with the -z option. This will ignore the partition table on the disk.

The main display is composed of four sections, from top to bottom: the header, the partitions, the command line and a warning line. The header contains the program name and version number followed by the disk drive and its geometry. The partitions section always displays the current partition table. The command line is the place where commands and text are entered. The available commands are usually displayed in brackets. The warning line is usually empty except when there is important information to be displayed. The current partition is highlighted with reverse video (or an arrow if the -a option is given). All partition specific commands apply to the current partition.

The format of the partition table in the partitions section is, from left to right: Name, Flags, Partition Type, Filesystem Type and Size. The name is the partition device name. The flags can be Boot, which designates a bootable partition or NC, which stands for "Not Compatible with DOS or OS/2". DOS, OS/2 and possibly other operating systems require the first sector of the first partition on the disk and all logical partitions to begin on the second head. This wastes the second through the last sector of the first track of the first head (the first sector is taken by the partition table itself). cfdisk allows you to recover these "lost" sectors with the maximize command (m). Note: fdisk(8) and some early versions of DOS create all partitions with the number of sectors already maximized. For more information, see the maximize command below. The partition type can be one of Primary or Logical. For unallocated space on the drive, the partition type can also be Pri/Log, or empty (if the space is unusable). The filesystem type section displays the name of the filesystem used on the partition, if known. If it is unknown, then Unknown and the hex value of the filesystem type are displayed. A special case occurs when there are sections of the disk drive that cannot be used (because all of the primary partitions are used). When this is detected, the filesystem type is displayed as Unusable. The size field displays the size of the partition in megabytes (by default). It can also display the size in sectors and cylinders (see the change units command below). If an asterisks (*) appears after the size, this means that the partition is not aligned on cylinder boundaries.  

DOS 6.x WARNING

The DOS 6.x FORMAT command looks for some information in the first sector of the data area of the partition, and treats this information as more reliable than the information in the partition table. DOS FORMAT expects DOS FDISK to clear the first 512 bytes of the data area of a partition whenever a size change occurs. DOS FORMAT will look at this extra information even if the /U flag is given -- we consider this a bug in DOS FORMAT and DOS FDISK.

The bottom line is that if you use cfdisk or fdisk to change the size of a DOS partition table entry, then you must also use dd to zero the first 512 bytes of that partition before using DOS FORMAT to format the partition. For example, if you were using cfdisk to make a DOS partition table entry for /dev/hda1, then (after exiting fdisk or cfdisk and rebooting Linux so that the partition table information is valid) you would use the command "dd if=/dev/zero of=/dev/hda1 bs=512 count=1" to zero the first 512 bytes of the partition. Note:

BE EXTREMELY CAREFUL if you use the dd command, since a small typo can make all of the data on your disk useless.

For best results, you should always use an OS-specific partition table program. For example, you should make DOS partitions with the DOS FDISK program and Linux partitions with the Linux fdisk or Linux cfdisk program.

 

COMMANDS

cfdisk commands can be entered by pressing the desired key (pressing Enter after the command is not necessary). Here is a list of the available commands:

b

Toggle bootable flag of the current partition. This allows you to select which primary partition is bootable on the drive.

d

Delete the current partition. This will convert the current partition into free space and merge it with any free space immediately surrounding the current partition. A partition already marked as free space or marked as unusable cannot be deleted.

g

Change the disk geometry (cylinders, heads, or sectors-per-track). WARNING: This option should only be used by people who know what they are doing. A command line option is also available to change the disk geometry. While at the change disk geometry command line, you can choose to change cylinders (c), heads (h), and sectors per track (s). The default value will be printed at the prompt which you can accept by simply pressing the Enter key, or you can exit without changes by pressing the ESC key. If you want to change the default value, simply enter the desired value and press Enter. The altered disk parameter values do not take effect until you return the main menu (by pressing Enter or ESC at the change disk geometry command line. If you change the geometry such that the disk appears larger, the extra sectors are added at the end of the disk as free space. If the disk appears smaller, the partitions that are beyond the new last sector are deleted and the last partition on the drive (or the free space at the end of the drive) is made to end at the new last sector.

h

Print the help screen.

m

Maximize disk usage of the current partition. This command will recover the the unused space between the partition table and the beginning of the partition, but at the cost of making the partition incompatible with DOS, OS/2 and possibly other operating systems. This option will toggle between maximal disk usage and DOS, OS/2, etc. compatible disk usage. The default when creating a partition is to create DOS, OS/2, etc. compatible partitions.

n

Create new partition from free space. If the partition type is Primary or Logical, a partition of that type will be created, but if the partition type is Pri/Log, you will be prompted for the type you want to create. Be aware that (1) there are only four slots available for primary partitions and (2) since there can be only one extended partition, which contains all of the logical drives, all of the logical drives must be contiguous (with no intervening primary partition). cfdisk next prompts you for the size of the partition you want to create. The default size, equal to the entire free space of the current partition, is display in megabytes. You can either press the Enter key to accept the default size or enter a different size at the prompt. cfdisk accepts size entries in megabytes (M) [default], kilobytes (K), cylinders (C) and sectors (S) by entering the number immediately followed by one of (M, K, C or S). If the partition fills the free space available, the partition is created and you are returned to the main command line. Otherwise, the partition can be created at the beginning or the end of the free space, and cfdisk will ask you to choose where to place the partition. After the partition is created, cfdisk automatically adjusts the other partition`s partition types if all of the primary partitions are used.

p

Print the partition table to the screen or to a file. There are several different formats for the partition that you can choose from:

r

Raw data format (exactly what would be written to disk)

s

Partition table in sector order format

t

Partition table in raw format

The raw data format will print the sectors that would be written to disk if a write command is selected. First, the primary partition table is printed, followed by the partition tables associated with each logical partition. The data is printed in hex byte by byte with 16 bytes per line.

The partition table in sector order format will print the partition table ordered by sector number. The fields, from left to right, are the number of the partition, the partition type, the first sector, the last sector, the offset from the first sector of the partition to the start of the data, the length of the partition, the filesystem type (with the hex value in parenthesis), and the flags (with the hex value in parenthesis). In addition to the primary and logical partitions, free and unusable space is printed and the extended partition is printed before the first logical partition.

If a partition does not start or end on a cylinder boundary or if the partition length is not divisible by the cylinder size, an asterisks (*) is printed after the non-aligned sector number/count. This usually indicates that a partition was created by an operating system that either does not align partitions to cylinder boundaries or that used different disk geometry information. If you know the disk geometry of the other operating system, you could enter the geometry information with the change geometry command (g).

For the first partition on the disk and for all logical partitions, if the offset from the beginning of the partition is not equal to the number of sectors per track (i.e., the data does not start on the first head), a number sign (#) is printed after the offset. For the remaining partitions, if the offset is not zero, a number sign will be printed after the offset. This corresponds to the NC flag in the partitions section of the main display.

The partition table in raw format will print the partition table ordered by partition number. It will leave out all free and unusable space. The fields, from left to right, are the number of the partition, the flags (in hex), the starting head, sector and cylinder, the filesystem ID (in hex), the ending head, sector and cylinder, the starting sector in the partition and the number of sectors in the partition. The information in this table can be directly translated to the raw data format.

The partition table entries only have 10 bits available to represent the starting and ending cylinders. Thus, when the absolute starting (ending) sector number is on a cylinder greater than 1023, the maximal values for starting (ending) head, sector and cylinder are printed. This is the method used by OS/2, and thus fixes the problems associated with OS/2`s fdisk rewriting the partition table when it is not in this format. Since Linux and OS/2 use absolute sector counts, the values in the starting and ending head, sector and cylinder are not used.

q

Quit program. This will exit the program without writing any data to disk.

t

Change the filesystem type. By default, new partitions are created as Linux partitions, but since cfdisk can create partitions for other operating systems, change partition type allows you to enter the hex value of the filesystem you desire. A list of the know filesystem types is displayed. You can type in the filesystem type at the prompt or accept the default filesystem type [Linux].

u

Change units of the partition size display. It will rotate through megabytes, sectors and cylinders.

W

Write partition table to disk (must enter an upper case W). Since this might destroy data on the disk, you must either confirm or deny the write by entering `yes` or `no`. If you enter `yes`, cfdisk will write the partition table to disk and the tell the kernel to re-read the partition table from the disk. The re-reading of the partition table works is most cases, but I have seen it fail. Don`t panic. It will be correct after you reboot the system. In all cases, I still recommend rebooting the system--just to be safe.

Up Arrow

Down Arrow

Move cursor to the previous or next partition. If there are more partitions than can be displayed on a screen, you can display the next (previous) set of partitions by moving down (up) at the last (first) partition displayed on the screen.

CTRL-L

Redraws the screen. In case something goes wrong and you cannot read anything, you can refresh the screen from the main command line.

?

Print the help screen.

All of the commands can be entered with either upper or lower case letters (except for Writes). When in a sub-menu or at a prompt to enter a filename, you can hit the ESC key to return to the main command line.

 

OPTIONS

-a

Use an arrow cursor instead of reverse video for highlighting the current partition.

-g

Do not use the geometry given by the disk driver, but try to guess a geometry from the partition table.

-v

Print the version number and copyright.

-z

Start with zeroed partition table. This option is useful when you want to repartition your entire disk. Note: this option does not zero the partition table on the disk; rather, it simply starts the program without reading the existing partition table.

-c cylinders

-h heads

-s sectors-per-track

Override the number of cylinders, heads and sectors per track read from the BIOS. If your BIOS or adapter does not supply this information or if it supplies incorrect information, use these options to set the disk geometry values.

-P opt

Prints the partition table in specified formats. opt can be one or more of "r", "s" or "t". See the print command (above) for more information on the print formats.

 

EXIT STATUS

0: No errors; 1: Invocation error; 2: I/O error; 3: cannot get geometry; 4: bad partition table on disk.  

SEE ALSO

fdisk(8), mkfs(8), parted(8), sfdisk(8)  

BUGS

The current version does not support multiple disks.  

AUTHOR

Kevin E. Martin (martin@cs.unc.edu)

chat

NAME

chat - Automated conversational script with a modem  

SYNOPSIS

chat [ options ] script  

DESCRIPTION

The chat program defines a conversational exchange between the computer and the modem. Its primary purpose is to establish the connection between the Point-to-Point Protocol Daemon (pppd) and the remote`s pppd process.  

OPTIONS

-f <chat file>

Read the chat script from the chat file. The use of this option is mutually exclusive with the chat script parameters. The user must have read access to the file. Multiple lines are permitted in the file. Space or horizontal tab characters should be used to separate the strings.

-t <timeout>

Set the timeout for the expected string to be received. If the string is not received within the time limit then the reply string is not sent. An alternate reply may be sent or the script will fail if there is no alternate reply string. A failed script will cause the chat program to terminate with a non-zero error code.

-r <report file>

Set the file for output of the report strings. If you use the keyword REPORT, the resulting strings are written to this file. If this option is not used and you still use REPORT keywords, the stderr file is used for the report strings.

-e

Start with the echo option turned on. Echoing may also be turned on or off at specific points in the chat script by using the ECHO keyword. When echoing is enabled, all output from the modem is echoed to stderr.

-E

Enables environment variable substituion within chat scripts using the standard $xxx syntax.

-v

Request that the chat script be executed in a verbose mode. The chat program will then log the execution state of the chat script as well as all text received from the modem and the output strings sent to the modem. The default is to log through the SYSLOG; the logging method may be altered with the -S and -s flags.

-V

Request that the chat script be executed in a stderr verbose mode. The chat program will then log all text received from the modem and the output strings sent to the modem to the stderr device. This device is usually the local console at the station running the chat or pppd program.

-s

Use stderr. All log messages from `-v` and all error messages will be sent to stderr.

-S

Do not use the SYSLOG. By default, error messages are sent to the SYSLOG. The use of -S will prevent both log messages from `-v` and error messages from being sent to the SYSLOG.

-T <phone number>

Pass in an arbitary string, usually a phone number, that will be substituted for the T substitution metacharacter in a send string.

-U <phone number 2>

Pass in a second string, usually a phone number, that will be substituted for the U substitution metacharacter in a send string. This is useful when dialing an ISDN terminal adapter that requires two numbers.

script

If the script is not specified in a file with the -f option then the script is included as parameters to the chat program.

 

CHAT SCRIPT

The chat script defines the communications.

A script consists of one or more "expect-send" pairs of strings, separated by spaces, with an optional "subexpect-subsend" string pair, separated by a dash as in the following example:

ogin:-BREAK-ogin: ppp ssword: hello2u2

This line indicates that the chat program should expect the string "ogin:". If it fails to receive a login prompt within the time interval allotted, it is to send a break sequence to the remote and then expect the string "ogin:". If the first "ogin:" is received then the break sequence is not generated.

Once it received the login prompt the chat program will send the string ppp and then expect the prompt "ssword:". When it receives the prompt for the password, it will send the password hello2u2.

A carriage return is normally sent following the reply string. It is not expected in the "expect" string unless it is specifically requested by using the character sequence.

The expect sequence should contain only what is needed to identify the string. Since it is normally stored on a disk file, it should not contain variable information. It is generally not acceptable to look for time strings, network identification strings, or other variable pieces of data as an expect string.

To help correct for characters which may be corrupted during the initial sequence, look for the string "ogin:" rather than "login:". It is possible that the leading "l" character may be received in error and you may never find the string even though it was sent by the system. For this reason, scripts look for "ogin:" rather than "login:" and "ssword:" rather than "password:".

A very simple script might look like this:

ogin: ppp ssword: hello2u2

In other words, expect ....ogin:, send ppp, expect ...ssword:, send hello2u2.

In actual practice, simple scripts are rare. At the vary least, you should include sub-expect sequences should the original string not be received. For example, consider the following script:

ogin:--ogin: ppp ssword: hello2u2

This would be a better script than the simple one used earlier. This would look for the same login: prompt, however, if one was not received, a single return sequence is sent and then it will look for login: again. Should line noise obscure the first login prompt then sending the empty line will usually generate a login prompt again.  

COMMENTS

Comments can be embedded in the chat script. A comment is a line which starts with the # (hash) character in column 1. Such comment lines are just ignored by the chat program. If a `#` character is to be expected as the first character of the expect sequence, you should quote the expect string. If you want to wait for a prompt that starts with a # (hash) character, you would have to write something like this:

# Now wait for the prompt and send logout string
`# ` logout

 

SENDING DATA FROM A FILE

If the string to send starts with an at sign (@), the rest of the string is taken to be the name of a file to read to get the string to send. If the last character of the data read is a newline, it is removed. The file can be a named pipe (or fifo) instead of a regular file. This provides a way for chat to communicate with another program, for example, a program to prompt the user and receive a password typed in.

 

ABORT STRINGS

Many modems will report the status of the call as a string. These strings may be CONNECTED or NO CARRIER or BUSY. It is often desirable to terminate the script should the modem fail to connect to the remote. The difficulty is that a script would not know exactly which modem string it may receive. On one attempt, it may receive BUSY while the next time it may receive NO CARRIER.

These "abort" strings may be specified in the script using the ABORT sequence. It is written in the script as in the following example:

ABORT BUSY ABORT `NO CARRIER` `` ATZ OK ATDT5551212 CONNECT

This sequence will expect nothing; and then send the string ATZ. The expected response to this is the string OK. When it receives OK, the string ATDT5551212 to dial the telephone. The expected string is CONNECT. If the string CONNECT is received the remainder of the script is executed. However, should the modem find a busy telephone, it will send the string BUSY. This will cause the string to match the abort character sequence. The script will then fail because it found a match to the abort string. If it received the string NO CARRIER, it will abort for the same reason. Either string may be received. Either string will terminate the chat script.  

CLR_ABORT STRINGS

This sequence allows for clearing previously set ABORT strings. ABORT strings are kept in an array of a pre-determined size (at compilation time); CLR_ABORT will reclaim the space for cleared entries so that new strings can use that space.  

SAY STRINGS

The SAY directive allows the script to send strings to the user at the terminal via standard error. If chat is being run by pppd, and pppd is running as a daemon (detached from its controlling terminal), standard error will normally be redirected to the file /var/log/ppp/connect-errors.

SAY strings must be enclosed in single or double quotes. If carriage return and line feed are needed in the string to be output, you must explicitely add them to your string.

The SAY strings could be used to give progress messages in sections of the script where you want to have `ECHO OFF` but still let the user know what is happening. An example is:

ABORT BUSY
ECHO OFF
SAY "Dialling your ISP... "
`` ATDT5551212
TIMEOUT 120
SAY "Waiting up to 2 minutes for connection ... "
CONNECT ``
SAY "Connected, now logging in ...
ogin: account
ssword: pass
$ SAY "Logged in OK ... etc ...

This sequence will only present the SAY strings to the user and all the details of the script will remain hidden. For example, if the above script works, the user will see:

Dialling your ISP...
Waiting up to 2 minutes for connection ... Connected, now logging in ...
Logged in OK ...

 

REPORT STRINGS

A report string is similar to the ABORT string. The difference is that the strings, and all characters to the next control character such as a carriage return, are written to the report file.

The report strings may be used to isolate the transmission rate of the modem`s connect string and return the value to the chat user. The analysis of the report string logic occurs in conjunction with the other string processing such as looking for the expect string. The use of the same string for a report and abort sequence is probably not very useful, however, it is possible.

The report strings to no change the completion code of the program.

These "report" strings may be specified in the script using the REPORT sequence. It is written in the script as in the following example:

REPORT CONNECT ABORT BUSY `` ATDT5551212 CONNECT `` ogin: account

This sequence will expect nothing; and then send the string ATDT5551212 to dial the telephone. The expected string is CONNECT. If the string CONNECT is received the remainder of the script is executed. In addition the program will write to the expect-file the string "CONNECT" plus any characters which follow it such as the connection rate.  

CLR_REPORT STRINGS

This sequence allows for clearing previously set REPORT strings. REPORT strings are kept in an array of a pre-determined size (at compilation time); CLR_REPORT will reclaim the space for cleared entries so that new strings can use that space.  

ECHO

The echo options controls whether the output from the modem is echoed to stderr. This option may be set with the -e option, but it can also be controlled by the ECHO keyword. The "expect-send" pair ECHO ON enables echoing, and ECHO OFF disables it. With this keyword you can select which parts of the conversation should be visible. For instance, with the following script:

ABORT `BUSY`
ABORT `NO CARRIER`

OK ATD1234567
c
ECHO ON
CONNECT c
ogin: account

all output resulting from modem configuration and dialing is not visible, but starting with the CONNECT (or BUSY) message, everything will be echoed.  

HANGUP

The HANGUP options control whether a modem hangup should be considered as an error or not. This option is useful in scripts for dialling systems which will hang up and call your system back. The HANGUP options can be ON or OFF.
When HANGUP is set OFF and the modem hangs up (e.g., after the first stage of logging in to a callback system), chat will continue running the script (e.g., waiting for the incoming call and second stage login prompt). As soon as the incoming call is connected, you should use the HANGUP ON directive to reinstall normal hang up signal behavior. Here is an (simple) example script:

ABORT `BUSY`

OK ATD1234567
c
CONNECT c
`Callback login:` call_back_ID
HANGUP OFF
ABORT "Bad Login"
`Callback Password:` Call_back_password
TIMEOUT 120
CONNECT c
HANGUP ON
ABORT "NO CARRIER"
ogin:--BREAK--ogin: real_account
etc ...

 

TIMEOUT

The initial timeout value is 45 seconds. This may be changed using the -t parameter.

To change the timeout value for the next expect string, the following example may be used:

ATZ OK ATDT5551212 CONNECT TIMEOUT 10 ogin:--ogin: TIMEOUT 5 assword: hello2u2

This will change the timeout to 10 seconds when it expects the login: prompt. The timeout is then changed to 5 seconds when it looks for the password prompt.

The timeout, once changed, remains in effect until it is changed again.  

SENDING EOT

The special reply string of EOT indicates that the chat program should send an EOT character to the remote. This is normally the End-of-file character sequence. A return character is not sent following the EOT. The EOT sequence may be embedded into the send string using the sequence ^D.  

GENERATING BREAK

The special reply string of BREAK will cause a break condition to be sent. The break is a special signal on the transmitter. The normal processing on the receiver is to change the transmission rate. It may be used to cycle through the available transmission rates on the remote until you are able to receive a valid login prompt. The break sequence may be embedded into the send string using the K sequence.  

ESCAPE SEQUENCES

The expect and reply strings may contain escape sequences. All of the sequences are legal in the reply string. Many are legal in the expect. Those which are not valid in the expect sequence are so indicated.

``

Expects or sends a null string. If you send a null string then it will still send the return character. This sequence may either be a pair of apostrophe or quote characters.

\b

represents a backspace character.

\c

Suppresses the newline at the end of the reply string. This is the only method to send a string without a trailing return character. It must be at the end of the send string. For example, the sequence helloc will simply send the characters h, e, l, l, o. (not valid in expect.)

\d

Delay for one second. The program uses sleep(1) which will delay to a maximum of one second. (not valid in expect.)

\K

Insert a BREAK (not valid in expect.)

\n

Send a newline or linefeed character.

\N

Send a null character. The same sequence may be represented by . (not valid in expect.)

\p

Pause for a fraction of a second. The delay is 1/10th of a second. (not valid in expect.)

\q

Suppress writing the string to the SYSLOG file. The string ?????? is written to the log in its place. (not valid in expect.)

\r

Send or expect a carriage return.

\s

Represents a space character in the string. This may be used when it is not desirable to quote the strings which contains spaces. The sequence `HI TIM` and HIsTIM are the same.

\t

Send or expect a tab character.

\T

Send the phone number string as specified with the -T option (not valid in expect.)

\U

Send the phone number 2 string as specified with the -U option (not valid in expect.)

\\

Send or expect a backslash character.

\ddd

Collapse the octal digits (ddd) into a single ASCII character and send that character. (some characters are not valid in expect.)

^C

Substitute the sequence with the control character represented by C. For example, the character DC1 (17) is shown as ^Q. (some characters are not valid in expect.)

 

ENVIRONMENT VARIABLES

Environment variables are available within chat scripts, if the -E option was specified in the command line. The metacharacter $ is used to introduce the name of the environment variable to substitute. If the substition fails, because the requested environment variable is not set, nothing is replaced for the variable.  

TERMINATION CODES

The chat program will terminate with the following completion codes.

0

The normal termination of the program. This indicates that the script was executed without error to the normal conclusion.

1

One or more of the parameters are invalid or an expect string was too large for the internal buffers. This indicates that the program as not properly executed.

2

An error occurred during the execution of the program. This may be due to a read or write operation failing for some reason or chat receiving a signal such as SIGINT.

3

A timeout event occurred when there was an expect string without having a "-subsend" string. This may mean that you did not program the script correctly for the condition or that some unexpected event has occurred and the expected string could not be found.

4

The first string marked as an ABORT condition occurred.

5

The second string marked as an ABORT condition occurred.

6

The third string marked as an ABORT condition occurred.

7

The fourth string marked as an ABORT condition occurred.

...

The other termination codes are also strings marked as an ABORT condition.

Using the termination code, it is possible to determine which event terminated the script. It is possible to decide if the string "BUSY" was received from the modem as opposed to "NO DIAL TONE". While the first event may be retried, the second will probably have little chance of succeeding during a retry.  

SEE ALSO

Additional information about chat scripts may be found with UUCP documentation. The chat script was taken from the ideas proposed by the scripts used by the uucico program.

uucico(1), uucp(1)  

COPYRIGHT

The chat program is in public domain. This is not the GNU public license. If it breaks then you get to keep both pieces.

chkconfig

NAME

chkconfig - updates and queries runlevel information for system services

 

SYNOPSIS

chkconfig --list [name]
chkconfig --add name
chkconfig --del name
chkconfig [--level levels] name <on|off|reset>
chkconfig [--level levels] name

 

DESCRIPTION

chkconfig provides a simple command-line tool for maintaining the /etc/rc[0-6].d directory hierarchy by relieving system administrators of the task of directly manipulating the numerous symbolic links in those directories.

This implementation of chkconfig was inspired by the chkconfig command present in the IRIX operating system. Rather than maintaining configuration information outside of the /etc/rc[0-6].d hierarchy, however, this version directly manages the symlinks in /etc/rc[0-6].d. This leaves all of the configuration information regarding what services init starts in a single location.

chkconfig has five distinct functions: adding new services for management, removing services from management, listing the current startup information for services, changing the startup information for services, and checking the startup state of a particular service.

When chkconfig is run without any options, it displays usage information. If only a service name is given, it checks to see if the service is configured to be started in the current runlevel. If it is, chkconfig returns true; otherwise it returns false. The --level option may be used to have chkconfig query an alternative runlevel rather than the current one.

If one of on, off, or reset is specified after the service name, chkconfig changes the startup information for the specified service. The on and off flags cause the service to be started or stopped, respectively, in the runlevels being changed. The reset flag resets the startup information for the service to whatever is specified in the init script in question.

By default, the on and off options affect only runlevels 2, 3, 4, and 5, while reset affects all of the runlevels. The --level option may be used to specify which runlevels are affected.

Note that for every service, each runlevel has either a start script or a stop script. When switching runlevels, init will not re-start an already-started service, and will not re-stop a service that is not running.

 

OPTIONS

--level levels

Specifies the run levels an operation should pertain to. It is given as a string of numbers from 0 to 7. For example, --level 35 specifies runlevels 3 and 5.

--add name

This option adds a new service for management by chkconfig. When a new service is added, chkconfig ensures that the service has either a start or a kill entry in every runlevel. If any runlevel is missing such an entry, chkconfig creates the appropriate entry as specified by the default values in the init script. Note that default entries in LSB-delimited `INIT INFO` sections take precedence over the default runlevels in the initscript.

--del name

The service is removed from chkconfig management, and any symbolic links in /etc/rc[0-6].d which pertain to it are removed.

Note that future package installs for this service may run chkconfig --add, which will re-add such links. To disable a service, run chkconfig name off.

--list name

This option lists all of the services which chkconfig knows about, and whether they are stopped or started in each runlevel. If name is specified, information in only display about service name.

 

RUNLEVEL FILES

Each service which should be manageable by chkconfig needs two or more commented lines added to its init.d script. The first line tells chkconfig what runlevels the service should be started in by default, as well as the start and stop priority levels. If the service should not, by default, be started in any runlevels, a - should be used in place of the runlevels list. The second line contains a description for the service, and may be extended across multiple lines with backslash continuation.

For example, random.init has these three lines:

# chkconfig: 2345 20 80 # description: Saves and restores system entropy pool for # higher quality random number generation.

This says that the random script should be started in levels 2, 3, 4, and 5, that its start priority should be 20, and that its stop priority should be 80. You should be able to figure out what the description says; the causes the line to be continued. The extra space in front of the line is ignored.

 

SEE ALSO

init(8) ntsysv(8) serviceconf(8)

 

AUTHOR

Erik Troan <ewt@redhat.com>

chk_cyrus

NAME

chk_cyrus - perform a consistancy check of the cyrus mailstore  

SYNOPSIS

chk_cyrus [ -C config-file ] [ -P partition ] [ -M mailbox ]  

DESCRIPTION

Chk_cyrus is used to perform a consistancy check on the cyrus datastore, and output a list of files/directories that are expected to exist, but do not. Status messagess are output to stderr, the list of files/directories is output to stdout. This list can be passed to a backup program to aid a partial restoral, for instance.

Chk_cyrus reads its configuration options out of the imapd.conf(5) file unless specified otherwise by -C.  

OPTIONS

-C config-file

Read configuration options from config-file.

-P partition

Run the consistancy check for only the given partition. May not be specified with -M. -M mailbox Run the consistancy check for only the given mailbox. May not be specified with -P.

 

FILES

/etc/imapd.conf

 

SEE ALSO

imapd.conf(5), cyrus-master(8)

cleanfeed

NAME

Cleanfeed - spam filter for Usenet news servers  

SYNOPSIS

INN: Installed as filter_innd.pl, location is configured into INN at compile time.

Highwind servers: <command line> -program cleanfeed -body

NNTPRelay: ExternalFilter=c:/perl/bin/perl.exe c:/news/cleanfeed.pl  

DESCRIPTION

A spam filter for Usenet servers. Cleanfeed blocks spam on the way into your server, before it is written to disk or propagated to outbound feeds. It can also block binaries in non-binary newsgroups and includes several other features to keep your newsfeed clean.

Cleanfeed currently works with INN, Cyclone, Typhoon, Breeze, and NNTPRelay servers. See my webpage (listed at the end of this document) for pointers to information about using Cleanfeed with CNews, Diablo, Collabra, or INN versions earlier than 1.5.1.  

USAGE

For all versions, place the cleanfeed.conf configuration file somewhere, then edit the Cleanfeed source file and change the $config_dir option at the top to point to the directory where the config file lives.

<FONT SIZE="-1">INN</FONT>

Install the filter file (called cleanfeed) as filter_innd.pl, and cleanfeed.conf, in the location you specified in config.data (<FONT SIZE="-1">INN</FONT> 1.7.2 and earlier) or when configuring <FONT SIZE="-1">INN</FONT> 2.x (usually the bin/filter directory under the installation root). Make sure both files are readable by the news user. Once in place, the filter is loaded with the command ctlinnd reload filter.perl meow. Filtering can be turned on with ctlinnd perl y and turned off with ctlinnd perl n.

Cyclone/Typhoon/Breeze

Add the -program <file> and -body options to the bin/start script, where <file> is the location and name of the Cleanfeed program. Restart the server. Cleanfeed will run as an external process (standalone mode). <FONT SIZE="-1">IMPORTANT</FONT>: make sure both cleanfeed and cleanfeed.conf are readable by the news user! Double-check the permissions as this is a fairly common mistake!

NNTPRelay

Find the ExternalFilter directive in config.txt and make it look like:

ExternalFilter=c:/perl/bin/perl.exe c:/news/cleanfeed.pl

Cleanfeed will run as an external process (standalone mode).

More detailed installation instructions are provided later in this document.  

CONFIGURATION OPTIONS

Configuration is accomplished by setting the various options in the cleanfeed.conf configuration file. This file is evaluated as Perl code, so comments can be included in the usual Perl # syntax. A sample default file is included with the distribution.

If you would rather not use cleanfeed.conf, you can set its location to ``undef`` in the source and edit the configuration variables directly in the source file.

cleanfeed.conf has two sections (which define perl hashes): %config_local and %config_append. Entries in %config_local will override the default settings of the same name in the Cleanfeed source. Entries in %config_append can be used to add to most of the default regular expressions, for items such as badguys, bin_allowed, poison_groups, etc. Settings in %config_append for these items will be appended to the default regexps, seperated by ``|`` (or).

If you want to completely override the default regexps for these options, rather than just add to the defaults, you can add an entry for them into the %config_local section of cleanfeed.conf.

All of this is done quite blindly, so if you do anything odd, be careful. (Cleanfeed will remove the common mistake of including two ``|`` (or) signs in a row.) All config options are exposed to %config_local, including any that may not be present in the sample file. Only the defined list of options are exposed to %config_append.

Options that are on/off or yes/no should be set to 1 for on/yes, or 0 for off/no.

First, you need to tell Cleanfeed which news server software you are using. At the top of the file, set the appropriate variable to 1. For INN, set $inn; for Cyclone, Typhoon, or Breeze, set $highwind; and for NNTPRelay, set $nntprelay. Ensure the other two (the ones you`re not using) are set to 0.  

General Settings

aggressive

Set this to 0 to disable all content-based filters. Helpful to please paranoid lawyers, or paranoid customers.

active_file

Set this to the full path to an active file, to allow Cleanfeed to know what groups are moderated. This is normally your server`s active file, but it doesn`t have to be; it is possible, for example, to run Cyclone with no active file, but give one to Cleanfeed anyway.

 

<FONT SIZE="-1">MD5</FONT> Body Filter Settings

do_md5

When turned on, the <FONT SIZE="-1">MD5</FONT> <FONT SIZE="-1">EMP</FONT> checks will be done. This should be left on unless you have a really good reason to turn it off. If you`re running Hippo along with Cleanfeed, you might feel Cleanfeed`s <FONT SIZE="-1">MD5</FONT> checks are redundant and want to turn them off, for example. It would probably be better to leave it on with the history turned down, instead.

md5maxmultiposts

Start rejecting articles after we have seen this many copies, according to the <FONT SIZE="-1">MD5</FONT> checksum filter.

MD5History

How many articles to remember for <FONT SIZE="-1">MD5-</FONT>based <FONT SIZE="-1">EMP</FONT> comparison. Since the <FONT SIZE="-1">MD5</FONT> filter is not prone to false positives, setting this higher is a good idea to catch more spam, if you have the <FONT SIZE="-1">RAM</FONT> to spare.

MD5maxlife

When a spam is identified by the <FONT SIZE="-1">MD5</FONT> <FONT SIZE="-1">EMP</FONT> filter, it is saved for continual rejection. MD5maxlife specifies how long, in hours, to keep a saved <FONT SIZE="-1">MD5</FONT> id which is no longer getting any hits. (A spam id which is still getting matches will be saved regardless of age.) 24 hours works well.

fuzzy_md5

When turned on, the message bodies will be munged up a bit before <FONT SIZE="-1">MD5</FONT> checksums are generated. Whitespace and other non-alphanumeric characters are stripped and letters are forced to lowercase, as well as a couple other bits of treachery to try to defeat the ``hashbuster`` spam-bots. This adds a bit of ``fuzziness`` to the <FONT SIZE="-1">MD5</FONT> filter, and results in a performance hit as well.

Since the smarter spammers have discovered hashbusting, I recommend that this be turned on.

fuzzy_max_length

Sets the maximum amount of lines for an article body to be subject to the fuzzy_md5 munging (above). This keeps extremely large articles out of those nasty regular expressions.

md5_skips_followups

Determines whether the <FONT SIZE="-1">MD5</FONT> filter checks articles with References headers. The default is to skip them. Setting this option to 0 will result in all articles passing through the <FONT SIZE="-1">MD5</FONT> filter, which can result in a major performance hit, but does close another hole in the filter. If you turn this off, you should increase MD5history as well to avoid shortening your ``window``.

MD5HistSize

The maximum allowed size of the <FONT SIZE="-1">EMP</FONT> memory for the <FONT SIZE="-1">MD5-</FONT>checksum <FONT SIZE="-1">EMP</FONT> filter. Use this as a ``sanity check`` to prevent a sudden burst of spam from eating up all of your memory. It should be set high enough so that you normally never hit this number; use the MD5MaxLife to expire the hash instead.

 

Header-Based <FONT SIZE="-1">EMP</FONT> Filter Settings

do_phl

Turns on the <FONT SIZE="-1">NNTP</FONT>-Posting-Host/Lines <FONT SIZE="-1">EMP</FONT> filter. This filter identifies spam by identical posting-host headers and article sizes in a short period of time. You really don`t want to turn this off.

do_fsl

Turns on the From/Subject/Lines <FONT SIZE="-1">EMP</FONT> filter. This filter identifies spam by identical From and Subject headers and article sizes in a short period of time. This is the one that gets the least number of hits these days, so you won`t lose much by shutting it off.

maxmultiposts

Start rejecting articles after we have seen this many copies, according to the header-based <FONT SIZE="-1">EMP</FONT> filter. Since false positives are somewhat more likely with this filter than with <FONT SIZE="-1">MD5</FONT>, this should be set appropriately higher to reduce the odds.

ArticleHistory

How many ids to remember for header-based <FONT SIZE="-1">EMP</FONT> comparison. Setting this higher will catch more spam because there will be a larger ``window`` to look at. Larger settings will also consume more memory and have a (small) impact on performance, as well as slightly increase the chance of a false positive (since the sample size will be larger). Most articles will actually take up two entries in this history because there are two different header-based filters.

EMPmaxlife

Same as MD5maxlife but for the header-based <FONT SIZE="-1">EMP</FONT> filter.

EMPHistSize

Same as MD5HistSize but for the header-based <FONT SIZE="-1">EMP</FONT> filter. If you are running the header-based filter but not the <FONT SIZE="-1">MD5</FONT> filter for whatever reason, set this high.

 

Excessive Crosspost Settings

maxgroups

Reject articles crossposted so that followups will be to more than this many newsgroups.

low_xpost_maxgroups

Specify a special, lower crosspost limit for certain groups, specifed by regular expression in low_xpost_groups (below). Useful for being more strict in groups plagued by crossposting, such as sex, binaries, and jobs groups. (Replaces the old tfjmaxgroups option.)

 

Misplaced Binaries Filter

block_binaries

Enables blocking of binary posts in non-binary newsgroups. Which newsgroups allow binaries is configured with bin_allowed (below).

max_encoded_lines

Sets the number of uuencoded or base64-encoded lines to allow before considering a post to be a binary. This should be set high enough to pass regular <FONT SIZE="-1">PGP</FONT> signatures. (Those satanic Netscape crypto-sigs can die along with the other binaries.) Default is 15 lines, which may be a little low if you are lenient, which you`re not.

binaries_in_mod_groups

If set, binaries are allowed in spite of block_binaries if they are posted only to moderated groups (requires active_file).

 

<FONT SIZE="-1">HTML</FONT>

block_mime_html

Enables blocking of <FONT SIZE="-1">MIME</FONT>-encapsulated <FONT SIZE="-1">HTML</FONT> posts. This does <FONT SIZE="-1">NOT</FONT> affect straight text/html or multipart/alternative posts of the type created by misconfigured Netscape and Microsoft ``newsreaders``, but <FONT SIZE="-1">ONLY</FONT> posts which are <FONT SIZE="-1">MIME</FONT>-encapsulated <FONT SIZE="-1">HTML</FONT>, a favorite format of sex spammers which often sneaks in under the <FONT SIZE="-1">EMP</FONT> radar.

block_html

Enables blocking of <FONT SIZE="-1">HTML</FONT> and multipart/alternative posts. You can specify group patterns where <FONT SIZE="-1">HTML</FONT> is allowed by setting html_allowed (below).

 

Cancel Message Filtering

block_late_cancels

If turned on, cancels for recently rejected articles will be rejected. Set the window with MIDmaxlife (below). This will result in a huge number of rejections if you have multiple full feeds and you aren`t backlogging. If you are concerned about your downstream sites receiving the cancels, leave this off. If you need a performance boost, turn it on.

MIDmaxlife

How long to remember rejected message-ids so cancels for these posts can later be rejected. Specified in hours. This only has an effect if block_late_cancels is enabled (above).

 

Disabling Other Filters

do_scoring_filter

Enables the (new) ``scoring`` filter. You probably want to leave this on, even if you need to turn of aggressive mode (turning off aggressive mode will disable the content-based parts of the scoring filter).

do_mid_filter (<FONT SIZE="-1">INN</FONT> only)

Enables the message-id filter. This requires an additional patch to <FONT SIZE="-1">INN</FONT> 1.7.2, which is included with Cleanfeed (but optional). The patch adds a new Perl hook to check message-id`s during the <FONT SIZE="-1">NNTP</FONT> <FONT SIZE="-1">CHECK</FONT> transaction, and decide whether to refuse the article. There is a patch for this for <FONT SIZE="-1">INN</FONT> 2.0 which may get incorporated into the <FONT SIZE="-1">INN</FONT> distribution at some point. The default is off.

do_bot_checks

Enables the filters that check for spam bot signatures. The only reason you would ever want to turn this off is if you`ve written your own version, or something. Otherwise, leave it on.

do_supersedes_filter

Enables the Excessive Supersedes filter, to catch rogue Supersedes attacks. This filter begins dropping articles with Supersedes headers if too many appear from the same posting-host in a short time. Moderated groups are given a higher limit (if active_file is set), as is news.answers. Default is on.

check_supersedes_path

If set, bad_cancel_paths will also be applied to Supersedes articles. Articles with Supersedes headers, where a path element matches the regexp in bad_cancel_paths, will be dropped. Default is on.

drop_useless_controls

If set, all control messages of types sendsys, senduuname, and version will be dropped. These are no longer useful and are a hole for denial-of-service attacks due to the way <FONT SIZE="-1">INN</FONT> and some other servers handle them. On by default.

drop_ihave_sendme

If set, control messages of types ihave and sendme will be dropped. See drop_useless_controls. If you use these types of control messages, turn this off. If you`re not sure, then you`re not using them.

drop_control_with_supersedes

Drops any and all control messages which contain a Supersedes header. Since control messages are not passed through the same filters as regular messages, a rogue Supersedes attack can use control messages to avoid filtering; this option closes this hole. Legitimate control messages don`t have Supersedes headers. On by default.

 

Hash-Trimming

trimcycles

The <FONT SIZE="-1">EMP</FONT> memories are trimmed every trimcycles times through the filter.

EMPstarttrimming

Tells the filter not to waste time trimming the <FONT SIZE="-1">EMP</FONT> memories until they have this many entries. Just a minor performance enhancement during the first hours the filter is running or when you first start innd.

 

Logging

verbose

When turned on, verbose logging to news.notice will happen; spam domains will be listed, etc. When off, only general messages will be logged, making the news.daily summaries less interesting but much shorter and more to the point. (There is, alas, no way to shut off news.notice logging entirely.) (news.notice only applies to <FONT SIZE="-1">INN</FONT>.) Note that this will not reduce the number of log entries, but only their verbosity.

logfile (Standalone Mode)

If set to the path to a file, this will enable logging of message-ids of all articles processed by the filter. Rejections will be logged with the reason for rejection. Note that this will create a very large logfile which you will need to rotate or delete (see max_log_size, below).

reportfile (Standalone Mode)

If set to the path to a file, this will enable generation of a simple report of articles accepted and rejected. The report file will contain one entry per line with the start time, end time, number of articles accepted, and number of articles rejected, tab-separated.

log_accepts (Standalone Mode)

When using the above logfiles, this setting determines whether articles accepted should be logged. When disabled, only rejections will be logged.

max_log_size (Standalone Mode)

The size at which to rotate the logfile. This will be replaced by time-based rotation at some point.

statfile

If this is set to the full path of a file, a crude stats file will be written each time the filter is reloaded with ctlinnd reload filter.perl meow (for <FONT SIZE="-1">INN</FONT>) or whenever the Cleanfeed process receives a <FONT SIZE="-1">SIGUSR1</FONT> (for standalone mode). The file shows how many entries are present in each of the <FONT SIZE="-1">EMP</FONT> histories, <FONT SIZE="-1">MID</FONT> history and excessive supersedes history; timer information if enabled (see timer_info); and the contents of all configuration settings. Posting-hosts in for each supersedes entry will be listed, along with their counts; these are not being rejected unless they are over the threshold. The default for this is undef, which disables creation of the stat file.

More comprehensive stats are planned for the future.

 

Timing Info

timer_info

When enabled, Cleanfeed will generate timing statistics telling you how many articles per second are being examined by the filter and being accepted by the filter. This information will appear in the statfile if this is enabled, and in the output of <FONT SIZE="-1">INN</FONT>`s ctlinnd mode if the mode.patch is applied to <FONT SIZE="-1">INN</FONT>. Note that the accepted/second rate is not necessarily the rate at which your server is accepting articles; articles can be rejected by the server after Cleanfeed passes them, for example if they are posted to groups not in your active file.

timer_interval

The period over which to average timing information, in seconds. The default is 600 seconds, or 5 minutes.

 

Debugging

debug_batch_directory

Specifies a directory where debugging ``batchfiles`` can be written. See the Hacker`s Guide in this document for more information.

debug_batch_size

The maximum size of a debugging batchfile before it gets rotated. Rotation is done by renaming the file to file.1, file.2, etc., using the lowest number that doesn`t already exist.

 

Regular Expressions

You can add to most of these regular expressions in the %config_append section of cleanfeed.conf; settings you add there will be added to the defaults, rather than overriding them. If you want to completely override the default settings you can add entries for these to the %config_local section instead.

bin_allowed

This is a regular expression telling the anti-binary filter in which newsgroups binaries are allowed. If all groups in the Newsgroups header match this pattern, binaries are allowed through the filter. (This obviously has no effect when the binary filter is disabled.) If the binary filter is enabled and this is set to a null string (by overriding the default in the local config) the result will be blocking all binaries regardless of where they are posted.

poison_groups

If any groups in the Newsgroups header match this regexp, the article will be rejected. Thus you can reject crossposts to certain groups even if they are also posted to groups you carry.

html_allowed

This is a regular expression telling the anti-<FONT SIZE="-1">HTML</FONT> filter in which newsgroups <FONT SIZE="-1">HTML</FONT> and multipart/alternative posts are allowed. This only has an effect if block_html is turned on (above). The default (to allow <FONT SIZE="-1">HTML</FONT> in microsoft.* groups) can be added to in cleanfeed.conf.

If you don`t want to allow <FONT SIZE="-1">HTML</FONT> anywhere, not even the microsoft.* groups, override this setting in the local configuration and set it to a null string or undef.

md5exclude

If an article is posted only to groups matching this regexp, the <FONT SIZE="-1">MD5</FONT> <FONT SIZE="-1">EMP</FONT> filter will not be applied. Useful for ``test`` groups where it`s okay for lots of the posts to be the same.

allexclude

If an article is posted only to groups matching this regexp, <FONT SIZE="-1">NO</FONT> checks are applied at all.

low_xpost_groups

If a group matches this regular expression, it gets a special crosspost limit, set in low_xpost_maxgroups, rather than the general crosspost limit set in maxgroups. This is useful for groups plagued by excessive crossposting, such as sex, binaries, and jobs groups. The default is to limit crossposts to 6 groups in test, forsale, and jobs groups. Setting this to a null string, or undef, will disable this feature.

badguys

This is a monster regular expression containing domains of known spammers. Only the ``middle`` part of the domains are listed; these are checked as email addresses in From headers by appending a list of top-level domains to the end, and as URLs by prepending http:// and an optional ``www.``. If you modify this list, be very careful not to end up with ``||`` in there (two ``or`` signs in a row); this will match every single post that comes through, which is Bad.

baddomainpat

If a post contains a <FONT SIZE="-1">URL</FONT> for a site whose domain name matches this pattern (in .com, .net, and .nu TLDs only) the post will be rejected. For example, there are hundreds of spamming porn sites whose domain names begin or end with ``xxx``. This prevents us from having to keep up with their nonsense. Yes, it`s a little aggressive, but it works.

exempt

Regular expression of <FONT SIZE="-1">NNTP</FONT>-Posting-Hosts that are exempt from the posting-host-based <FONT SIZE="-1">EMP</FONT> filter. This is for high-output systems where all posts contain the same <FONT SIZE="-1">NNTP</FONT>-Posting-Host header, such as <FONT SIZE="-1">AOL</FONT>, which if not exempted would end up hitting the posting-host <FONT SIZE="-1">EMP</FONT> filter with all of their posts. There aren`t many of these out there; a ``regular`` multi-user system does not present a problem because the filter doesn`t kick in until it sees a large number of posts from the same posting-host and also of the same length, in a short period of time.

supersedes_exempt

Regular expression of <FONT SIZE="-1">NNTP</FONT>-Posting-Hosts that are exempt from the excessive supersedes filter. Generally this will be systems which post a lot of FAQs.

bad_cancel_paths

Cancel messages will be rejected if the Path header contains elements matching this regular expression. Also applied to the <FONT SIZE="-1">NNTP</FONT>-Posting-Host. If check_supersedes_path is set, this will also be checked against the Path header of articles with Supersedes headers. This list contains sites which are or have recently been the source of rogue cancel attacks.

refuse_messageids (<FONT SIZE="-1">INN</FONT> only)

If you have do_mid_filter (above) enabled, and you have the optional message-id patch applied to <FONT SIZE="-1">INN</FONT> (or otherwise have obtained the hook for filter_messageid in <FONT SIZE="-1">INN</FONT> 2.0), this regular expression will be applied to message-ids as they are offered to your server, and they will be refused if it matches.

net_abuse_groups

spam_report_groups

These regular expressions are used to exempt certain groups from certain filters; for example, groups expected to contain spam reports, example spams, NoCeM notices, etc. These are not in cleanfeed.conf; if you need to add to them please let me know.

After modifying the filter file, always check for mistakes by typing:

perl -cw filter_innd.pl (or cleanfeed or whatever you called it)

There should be no errors and no warnings.

You can check cleanfeed.conf with:

perl -cw cleanfeed.conf

You will get several warnings about variables being used only once; these can be ignored.

If you are running <FONT SIZE="-1">INN</FONT>, you can modify the file and reload it with ctlinnd reload filter.perl meow while the server is running. The configuration in f<cleanfeed.conf> will be reloaded at this time as well.

With the Highwind servers, modifying the program will require a server restart (use the bin/restart script). Note that this will result in all connections (including newsreader clients) being dropped. This is not my fault. :)

When in standalone mode, configuration from cleanfeed.conf can be reloaded by sending Cleanfeed a <FONT SIZE="-1">SIGHUP</FONT>.

I have no idea what NNTPRelay does, but I`m guessing it needs a restart as well.

<FONT SIZE="-1">IMPORTANT</FONT> <FONT SIZE="-1">NOTE</FONT>: A common mistake is not setting file permissions on cleanfeed/filter_innd.pl, cleanfeed.conf, and cleanfeed.local so that they are readable by the news user. Please double-check your permissions! If Cleanfeed is running, and fails to successfully load cleanfeed.conf, it will use the default settings instead of those you specified in the config file.  

INSTALLATION - INN

These instructions assume you have the Perl hooks compiled into INN. If you don`t, you will need to add them and rebuild the INN distribution before proceeding.

With INN, Perl is embedded into the innd program. The filter file defines subroutines that are called by innd at the appropriate times.  

<FONT SIZE="-1">SYSTEM</FONT> <FONT SIZE="-1">REQUIREMENTS</FONT>

In order to run Cleanfeed with <FONT SIZE="-1">INN</FONT>, you will need:

*

<FONT SIZE="-1">INN</FONT> 1.5.1 or later (1.7.2+insync1.1d or 2.1 recommended)

*

Perl 5.004 or later

*

Perl hooks compiled into <FONT SIZE="-1">INN</FONT>

*

The <FONT SIZE="-1">MD5</FONT> Perl module

<FONT SIZE="-1">INN</FONT> is available from:
    http://www.isc.org/inn.html

The Insync distribution of <FONT SIZE="-1">INN</FONT> (highly recommended if you aren`t running <FONT SIZE="-1">INN</FONT> 2.1) is available from:
    http://www.insync.net/~aos/inn.html

The <FONT SIZE="-1">MD5</FONT> Perl module is available from:
    http://www.perl.com/<FONT SIZE="-1">CPAN</FONT>-local/modules/by-module/<FONT SIZE="-1">MD5</FONT>/

Perl itself is available from the Perl home page:
    http://www.perl.com/  

<FONT SIZE="-1">PATCHES</FONT> <FONT SIZE="-1">AND</FONT> <FONT SIZE="-1">STUFF</FONT>

<FONT SIZE="-1">INN</FONT> 2.0 includes everything you need to run Cleanfeed, except the <FONT SIZE="-1">MD5</FONT> Perl module.

With earlier versions, Cleanfeed requires some patches to <FONT SIZE="-1">INN</FONT> in order to function properly.

If you are running <FONT SIZE="-1">INN</FONT> 1.7.2+insync1.1d, you already have the original filter.patch and the dynamic-load.patch; You need only apply the upgrade.patch.

None of these patches are against <FONT SIZE="-1">INN</FONT> 2.1; the ``extra feature`` ones like mode.patch may not apply to 2.1. Ports are always welcome.

filter.patch

This patch provides the basic functionality for Cleanfeed by making some extra headers available to the Perl filter, as well as message bodies. This patch was changed in version 0.95.3. It is against <FONT SIZE="-1">INN</FONT> 1.7.2 and should be applied in the innd directory. This patch is included in the insync ``megapatch`` for <FONT SIZE="-1">INN</FONT> as of version 1.1c, so if you are running this version of <FONT SIZE="-1">INN</FONT> you need not apply this patch. Not necessary for <FONT SIZE="-1">INN</FONT> 2.x.

dynamic-load.patch

This patch enables <FONT SIZE="-1">INN</FONT>`s Perl interpreter to load dynamic modules. It is necessary for <FONT SIZE="-1">MD5</FONT> support. The patch is against <FONT SIZE="-1">INN</FONT> 1.7+insync and should be applied in the lib directory (<FONT SIZE="-1">NOT</FONT> the innd directory). It applies cleanly to other versions of <FONT SIZE="-1">INN</FONT> including 1.5.1 and 1.7.2. This patch is included in the insync ``megapatch`` for <FONT SIZE="-1">INN</FONT> as of version 1.1d, so if you are running this version of <FONT SIZE="-1">INN</FONT> you need not apply this patch. Not necessary for <FONT SIZE="-1">INN</FONT> 2.x.

If you are still using <FONT SIZE="-1">INN</FONT> 1.5.1, you can use dynamic-1.5.1.patch instead.

In order to compile <FONT SIZE="-1">INN</FONT> with the new patch, you need to edit the <FONT SIZE="-1">PERL_LIB</FONT> entry in config.data. Type this command at the shell, and paste its output into config.data as <FONT SIZE="-1">PERL_LIB</FONT>:

perl -MExtUtils::Embed -e ldopts

Most systems also allow you to simply enter that line in backquotes as <FONT SIZE="-1">PERL_LIB</FONT>.

This patch requires Perl 5.004 or later! <FONT SIZE="-1">INN</FONT> will not compile linked with Perl 5.003 after following these instructions!

<FONT SIZE="-1">AIX</FONT>: There is a problem with Perl dynamic loading from <FONT SIZE="-1">INN</FONT> under the <FONT SIZE="-1">AIX</FONT> operating system. In simple terms, it doesn`t work. This seems to be a problem with the gcc compiler. Success has been reported by rebuilding both Perl and <FONT SIZE="-1">INN</FONT> with <FONT SIZE="-1">IBM</FONT>`s commercial compiler CSet (a.k.a. xlC).

Solaris: There have been multiple reports of Cleanfeed not working under Solaris if any part of the system -- <FONT SIZE="-1">INN</FONT>, Perl, or the <FONT SIZE="-1">MD5</FONT> module -- are compiled using egcs. Success has been reported by recompiling everything with gcc, and by upgrading to the very newest egcs.

upgrade.patch

For current users of Cleanfeed, this is a patch for an already-patched <FONT SIZE="-1">INN</FONT>, or for 1.7.2+insync1.1d, to bring you up to the new version of the Cleanfeed patch. Not applying this patch right now will only lose you a couple of filters, and nothing will break if you don`t apply it (no changes to the filter source or configuration will be required).

messageid.patch

This is a patch which adds a new Perl hook to innd, filter_messageid. This allows you to run a Perl subroutine against each message-id as it is offered to your server, and decide whether to refuse the article before it is even sent to your server. Cleanfeed includes a small filter_messageid. This patch is entirely optional.

mode.patch

This patch adds a line to <FONT SIZE="-1">INN</FONT>`s ctlinnd mode output for Perl filter status. The output line is generated by the filter_stats subroutine. The default output contains the number of articles accepted, rejected and refused since the filter started, and the sizes of the <FONT SIZE="-1">EMP</FONT>, Message-<FONT SIZE="-1">ID</FONT>, and Excessive Supersedes hashes. If timer_info is enabled, this will also include the rate in articles per second (rounded to the nearest tenth) at which articles were examined (total sent through the filter) and accepted by the filter, averaged over the timer_interval number of seconds.

After applying the patches, rebuild all of <FONT SIZE="-1">INN</FONT> and do a ``make update``. The first patch (filter.patch) only requires innd to be rebuilt, but the dynamic-load.patch requires you to rebuild the whole distribution. Current users upgrading with upgrade.patch need only rebuild innd and reinstall that executable.

Thus:

cd inn [to the top-level source directory] make clean cd innd cp wherever/filter.patch . [from the Cleanfeed distribution] patch <filter.patch cd ../lib cp wherever/dynamic-load.patch [from the Cleanfeed distribution] patch <dynamic-load.patch cd ../config emacs config.data [edit the PERL_LIB entry as above] make all make update

Finally, you need to install the <FONT SIZE="-1">MD5</FONT> Perl module, no matter what version of <FONT SIZE="-1">INN</FONT> you are running.  

<FONT SIZE="-1">INSTALLING</FONT> <FONT SIZE="-1">CLEANFEED</FONT> - <FONT SIZE="-1">INN</FONT>

In <FONT SIZE="-1">INN</FONT> 1.7.2 and earlier, the location where <FONT SIZE="-1">INN</FONT> looks for the Perl filter is set in config.data, as _PATH_PERL_FILTER_INND. By default, the filename is filter_innd.pl. The Cleanfeed filter program file should be installed in this location. <FONT SIZE="-1">INN</FONT> comes with an example filter_innd.pl file; move this file (or whatever other filter is in place) out of the way first.

Before putting the filter in place, edit the file, changing $config_dir to the location of your cleanfeed.conf file.

After editing the file, always check for errors with the command:

perl -cw filter_innd.pl

Once the file is in place, tell innd to reload it:

ctlinnd reload filter.perl meow

And, if Perl filtering is currently disabled, enable it:

ctlinnd perl y

Now, you can watch it working by looking at your news.notice log:

tail -f /var/log/news/news.notice

If your server is running a full feed, you should start seeing a constant stream of rejections almost immediately.  

INSTALLATION - HIGHWIND SERVERS

The various Highwind server packages (Cyclone, Typhoon, and Breeze) all have the same external filter interface. The filter runs as its own process, reading from standard input and writing to standard output.  

<FONT SIZE="-1">SYSTEM</FONT> <FONT SIZE="-1">REQUIREMENTS</FONT>

In order to run Cleanfeed with a Highwind server, you will need:

*

Cyclone, Typhoon or Breeze

*

Perl 5.003 or later

*

The <FONT SIZE="-1">MD5</FONT> Perl module

The Highwind servers are commercial products. For more information:
    http://www.highwind.com/

The <FONT SIZE="-1">MD5</FONT> Perl module is available from:
    http://www.perl.com/<FONT SIZE="-1">CPAN</FONT>-local/modules/by-module/<FONT SIZE="-1">MD5</FONT>/

Perl itself is available from the Perl home page:
    http://www.perl.com/  

<FONT SIZE="-1">INSTALLING</FONT> <FONT SIZE="-1">CLEANFEED</FONT> - <FONT SIZE="-1">HIGHWIND</FONT>

The Cleanfeed program file should be installed as ``cleanfeed`` in your news server`s bin directory (cyclone/bin, etc). Make it owned by news:news and make it executable.

Before putting the filter in place, edit the file, changing $config_dir to the location of your cleanfeed.conf file. Also ensure that the shebang line (the first line of the file, starting with #!) points to the correct location of your perl executable.

After editing the file, always check for errors with the command:

perl -cw cleanfeed

There should be no warnings.

Now, edit your bin/start script. You need to add two options to the command line that starts up the server process, the -program option to tell it what program to use as a filter, and the -body option to tell it to send the bodies as well as the headers.

typhoond -program /typhoon/bin/cleanfeed -body

...along with whatever else you have cluttering up the command line.

(Highwind has indicated that this may/will be a config file option in a future release.)

Now you can restart the server with the bin/restart script. Check to make sure Cleanfeed is running, with ``ps -ef`` or ``top``. If Cyclone/Typhoon is unable to start the filter for some reason, it will log an error via syslog. The error will not be terribly helpful.

You can make Cleanfeed reload its configuration from cleanfeed.conf and local code from cleanfeed.local by sending it a <FONT SIZE="-1">SIGHUP</FONT>.  

INSTALLATION - NNTPRELAY

Please note that I do not have an NNTPRelay server, nor access to one, nor much interest in mucking around with Windows NT, and thus I have not tested the NNTPRelay filtering support myself. The necessary changes and notes were contributed by someone else. Additions and improvements to this documentation would be most welcome.

The filter interface in NNTPRelay is pretty much the same as in the Highwind servers.  

<FONT SIZE="-1">SYSTEM</FONT> <FONT SIZE="-1">REQUIREMENTS</FONT>

In order to run Cleanfeed with NNTPRelay, you will need:

*

NNTPRelay version 1.1b4 or later

*

Perl 5.003 or later

*

The <FONT SIZE="-1">MD5</FONT> Perl module

NNTPRelay is available from:
    http://nntprelay.maxwell.syr.edu/

An <FONT SIZE="-1">NT</FONT> binary release of Perl 5.004, which apparently includes the <FONT SIZE="-1">MD5</FONT> module, can be found at:
    http://www.perl.com/<FONT SIZE="-1">CPAN/</FONT>ports/win32/Standard/x86

The <FONT SIZE="-1">MD5</FONT> module (in source code) can be found at:
    http://www.perl.com/<FONT SIZE="-1">CPAN</FONT>-local/modules/by-module/<FONT SIZE="-1">MD5</FONT>/  

<FONT SIZE="-1">INSTALLING</FONT> <FONT SIZE="-1">CLEANFEED</FONT> - <FONT SIZE="-1">NNTPRELAY</FONT>

Before putting the filter in place, edit the file, changing $config_dir to the location of your cleanfeed.conf file.

Install the Cleanfeed program file wherever is appropriate on your system, as ``cleanfeed.pl``. Edit NNTPRelay`s config.txt file, adding an entry like this:

ExternalFilter=c:/perl/bin/perl.exe c:/news/cleanfeed.pl

Of course, use the correct path to your Perl executable and to the Cleanfeed program file. Now restart NNTPRelay. If you defined a logfile in Cleanfeed, it should appear.  

THE HACKER`S GUIDE

Cleanfeed will look for a file called cleanfeed.local, in the same directory as cleanfeed.conf. If this file exists, it will be loaded and evaluated as Perl code right after the config file. This enables you to provide your own local filter code which will survive an upgrade of the main Cleanfeed source.

It will be reloaded when the filter is reloaded with ctlinnd reload filter.perl meow (for INN), or when configuration is reloaded with a SIGHUP (in standalone mode). This means that you can modify the running code without restarting Cleanfeed.

cleanfeed.local can define a number of different subroutines, which, if defined, will be called at various points in the filter process. Other subroutines can, of course, be defined as required by your code.

The file is simply re-evaluated each time. So, if you remove a subroutine from the file completely, that subroutine will remain defined after the reload, because nothing replaced it. You will need instead to define it as an empty subroutine, or explicitely undef it, to make it go away.  

<FONT SIZE="-1">STUFF</FONT> <FONT SIZE="-1">YOU</FONT> <FONT SIZE="-1">CAN</FONT> <FONT SIZE="-1">DEFINE</FONT>

Cleanfeed will call the following subroutines, if they are defined. See the section on return values for instructions on what your code should return.

local_config

This is called after configuration is loaded, each time. It will be called when the filter is reloaded (with <FONT SIZE="-1">INN</FONT>) or when configuration is reloaded with <FONT SIZE="-1">SIGHUP</FONT> (running standalone), as well as when the filter is first run. No return value is expected.

local_filter_before_emp

Called for each (non-control) article, before any other filters. General-purpose spam filters shouldn`t go here, because you really want to populate the <FONT SIZE="-1">EMP</FONT> hashes first.

local_filter_after_emp

Called for each (non-control) article, after the <FONT SIZE="-1">EMP</FONT> filters but before any other filters.

local_filter_middle

Called for each (non-control) article, after the ``simple`` filters but before the ``expensive`` body checks.

local_filter_scoring

Called during the scoring filter. Return the value, positive or negative, by which to adjust the article`s score.

Warning: Here there be dragons! If you`re going to play with this please examine the existing source, and use the debugging routines to watch what you`re doing.

local_filter_last

Called for each (non-control) article, after all other filters are done.

local_filter_cancel

Called for all cancel control messages.

local_filter_newrmgroup

Called for all newgroup and rmgroup control messages.

 

<FONT SIZE="-1">RETURN</FONT> <FONT SIZE="-1">VALUES</FONT>

The general filtering subroutines you can define (local_filter_before_emp, local_filter_after_emp, local_filter_middle, local_filter_last, local_filter_cancel, and local_filter_newrmgroup) are expected to return a value indicating whether you want to accept the article being examined. If the article is okay, you should return "" (empty string), in which case filtering will proceed as usual. If you want to reject the article, you return any other string, which will be used as the reason.

The rejection code actually expects two return values -- the first string is the ``verbose`` rejection message, and the second is the ``non-verbose`` message (see the verbose configuration option). If only one is supplied, it will be used for both purposes.

The scoring filter calls local_filter_scoring, which is expected to return the value, postive or negative, by which the article`s score should be adjusted.  

<FONT SIZE="-1">WHAT</FONT> <FONT SIZE="-1">YOU</FONT> <FONT SIZE="-1">GET</FONT>

Your subroutines get information about the article in several variables.

%hdr

A hash containing the article headers. The key is the header name, in ``canonical`` case as <FONT SIZE="-1">INN</FONT> likes them; the value is the content of the header. When running under <FONT SIZE="-1">INN</FONT>, only headers known to <FONT SIZE="-1">INN</FONT> will be included in the hash (which includes any header used anywhere in Cleanfeed). In standalone mode, all headers will be present, but only the known headers will be sent in canonical case; others will have the header name (and thus hash key) in whatever case they are in the article itself, making them difficult to find and use consistently.

The message body is in this hash under the key __BODY__. If running <FONT SIZE="-1">INN</FONT> 2.x with storageapi, it will be provided in wireformat, with lines terminated in rather than just . With the traditional spool format (and in all cases with <FONT SIZE="-1">INN</FONT> prior to 2.x) lines will be terminated only with .

Examples:

To get the Subject header as a scalar: $hdr{`Subject`}

To get the entire message body as a scalar: $hdr{`__BODY__`}

%lch

A hash containing lowercased versions of some of the article headers. The hash keys are the header names in all lowercase; the values are the contents of the headers, with all letters forced to lowercase.

Currently, the only headers added to this hash are From, Organization, Subject, Content-Type, X-Newsreader, X-Newsposter, Message-<FONT SIZE="-1">ID</FONT>, and Sender.

This hash is not availabe to local_filter_before_emp.

@groups

An array containing the newsgroups the article is posted to (from the Newsgroups header). You can find out how many groups the article is crossposted to with ``scalar @groups``.

@followups

An array containing the newsgroups to which followups are set (from the Followup-To header). If the article has no Followup-To header, this array will be identical to @groups. You can find out how many groups followups are set to with ``scalar @followups``. This is the preferred way to limit crossposting, because limiting only by the Newsgroups header will catch FAQs and such.

$lines

The number of lines in the message body. This is not taken from the Lines header as that can be client-supplied to fool filtering; this is determined by counting the lines in the message body.

%gr

A hash containing information about the groups the article is posted to. This isn`t very straightforward and may not be useful to you, but I`m including it in this documentation for completeness. The following entries may be present in this hash:

$gr{`net`} - the number of net.* (Usenet <FONT SIZE="-1">II</FONT>) newsgroups the article is posted to, if any.

$gr{`other`} - the number of non-net.* groups the article is posted to.

$gr{`md5skip`} - true if the article should be exempted from the <FONT SIZE="-1">MD5</FONT> body checks (if all newsgroups match the regexp in md5exclude).

$gr{`binary`} - true if the article is posted only to groups where binaries are allowed (if all newsgroups match bin_allowed).

$gr{`html`} - true if the article is posted only to groups where html is allowed (if all newsgroups match html_allowed).

$gr{`poison`} - number of `poison` newsgroups this article is posted to (matching poison_groups). If this is present, you`ll only see this entry in local_filter_before_emp and local_filter_after_emp because it will be rejected after that.

$gr{`abuse`} - number of `net abuse` newsgroups this article is posted to (matching net_abuse_groups).

$gr{`reports`} - number of `spam reports` newsgroups this article is posted to (matching spam_report_groups).

$gr{`low_xpost`} - number of `low crosspost limit` groups this article is posted to (matching low_xpost_groups).

$gr{`mod`} - number of moderated groups this article is posted to (requires that Cleanfeed have an active file).

$gr{`allmod`} - true if this article is posted only to moderated groups.

$gr{`faq`} - true if this article is crossposted to news.answers.

%config

A hash containing all configuration options.

 

<FONT SIZE="-1">DEBUGGING</FONT>

When you make filtering changes, you should always check the results for false positives. I`ve provided two subroutines to help you do this: writeheaders() and writefull().

First, make sure debug_batch_directory is set in your configuration. Set this to a directory that is writable by the news user.

Call either of these subroutines with one argument, the basename of the batch file you want to write the current article to. writeheaders will dump the article`s headers out to the file (with <FONT SIZE="-1">INN</FONT> this will only give you the known headers). writefull will dump the full article, headers (again, known headers with <FONT SIZE="-1">INN</FONT>) and body. The file will be rotated if it becomes larger than debug_batch_size, set in your configuration. The rotation is simple, a number is appended to the end of the file, and incremented until the filename does not exist. You`ll have to delete the old files yourself.

When testing a new filter, simply call writeheaders ("batchfile") or writefull ("batchfile") when you`re going to reject an article. Then you can look at the file to make sure you`re doing what you think you`re doing.  

SIGNALS

When running under Cyclone, Typhoon, Breeze, or NNTPRelay (standalone mode), Cleanfeed will catch SIGHUP, and reload its configuration from cleanfeed.conf. It will also reload and reevaluate cleanfeed.local if you`re using it. Note that, unlike INN, there is no way to reload the filter code itself without restarting the server.

Cleanfeed in standalone mode will also catch SIGUSR1 and write its crude current-status file (see statfile in the config section) on the next cycle through the filter.

(I honestly don`t know if SIGUSR1 and SIGHUP are things which exist on NT for NNTPRelay.)  

CREDITS

Written by Jeremy Nixon <jeremy@exit109.com>.

Originally based on Jeff Garzik`s EMP filter.

I can`t possibly mention everyone who has submitted ideas or fixes for the filter, but I`d like to acknowledge the substantial contributions of several people: Danhiel Baker, Frank Copeland, Brian Moore, John Payne, Russ Allbery, David Riley, and SeokChan LEE. Thanks, guys.

dynamic-load.patch is from Piers Cawley. The body-filtering portion of the INN filter.patch is from Jeff Garzik. messageid.patch is from Ed Mooring. mode.patch is from John Payne.  

COPYRIGHT

Copyright 1997-1998 by Jeremy Nixon, All Rights Reserved.  

LICENSE

This software may be distributed freely, provided it is intact (including all the files from the original archive). You may modify it, and you may distribute your modified version, provided the original work is credited to the appropriate authors, and your work is credited to you (don`t make changes and pass them off as my work), and that you aren`t charging for it.  

AVAILABILITY

This filter is available at:

http://www.exit109.com/~jeremy/news/antispam.html ftp://ftp.exit109.com/users/jeremy/

cnfsheadconf

NAME

cnfsheadconf - set CNFS header  

SYNOPSIS

cnfsheadconf [ -c CLASS ] [ -h ] [ -w ]  

DESCRIPTION

Cnfsheadconf reads <pathetc in inn.conf>/cycbuff.conf and <pathetc in inn.conf>/storage.conf to determine which cycbuff is available, reads the specified cycbuff and modifies the header.  

OPTIONS

-c CLASS

Cnfsheadconf prints status for the specified class.

-h

Cnfsheadconf prints usage information.

-w

Cnfsheadconf modifies cycbuff header.

 

HISTORY

Written by Katsuhiro Kondou <kondou@nec.co.jp> for InterNetNews. This is revision 1.1.2.2, dated 2002/09/01.  

SEE ALSO

cycbuff.conf(5), inn.conf(5), storage.conf(5).