awg-quick

title: awg-quick(8)

text:
# awg-quick(8)

## NAME
wg-quick - set up a WireGuard interface simply

## SYNOPSIS
wg-quick [ up | down | save | strip ] [ CONFIG_FILE | INTERFACE ]

## DESCRIPTION
This is an extremely simple script for easily bringing up a WireGuard interface, suitable for a few common use cases.

Use up to add and set up an interface, and use down to tear down and remove an interface. Running up adds a WireGuard interface, brings up the interface with the supplied IP addresses, sets up mtu and routes, and optionally runs pre/post up scripts. Running down optionally saves the current configuration, removes the WireGuard interface, and optionally runs pre/post down scripts. Running save saves the configuration of an existing interface without bringing the interface down. Use strip to output a configuration file with all wg-quick(8)-specific options removed, suitable for use with wg(8).

CONFIG_FILE is a configuration file, whose filename is the interface name followed by `.conf'. Otherwise, INTERFACE is an interface name, with configuration found at `/etc/wireguard/INTERFACE.conf', searched first, followed by distro-specific search paths.

Generally speaking, this utility is just a simple script that wraps invocations to wg(8) and ip(8) in order to set up a WireGuard interface. It is designed for users with simple needs, and users with more advanced needs are highly encouraged to use a more specific tool, a more complete network manager, or otherwise just use wg(8) and ip(8), as usual.

## CONFIGURATION
The configuration file adds a few extra configuration values to the format understood by wg(8) in order to configure additional attributes of an interface. It handles the values that it understands, and then it passes the remaining ones directly to wg(8) for further processing.

It infers all routes from the list of peers' allowed IPs, and automatically adds them to the system routing table. If one of those routes is the default route (0.0.0.0/0 or ::/0), then it uses ip-rule(8) to handle overriding of the default gateway.

The configuration file will be passed directly to wg(8)'s `setconf' sub-command, with the exception of the following additions to the Interface section, which are handled by this tool:

- Address — a comma-separated list of IP (v4 or v6) addresses (optionally with CIDR masks) to be assigned to the interface. May be specified multiple times.

- DNS — a comma-separated list of IP (v4 or v6) addresses to be set as the interface's DNS servers, or non-IP hostnames to be set as the interface's DNS search domains. May be specified multiple times. Upon bringing the interface up, this runs `resolvconf -a tun.INTERFACE -m 0 -x` and upon bringing it down, this runs `resolvconf -d tun.INTERFACE`. If these particular invocations of resolvconf(8) are undesirable, the PostUp and PostDown keys below may be used instead.

- MTU — if not specified, the MTU is automatically determined from the endpoint addresses or the system default route, which is usually a sane choice. However, to manually specify an MTU to override this automatic discovery, this value may be specified explicitly.

- Table — Controls the routing table to which routes are added. There are two special values: `off' disables the creation of routes altogether, and `auto' (the default) adds routes to the default table and enables special handling of default routes.

- PreUp, PostUp, PreDown, PostDown — script snippets which will be executed by bash(1) before/after setting up/tearing down the interface, most commonly used to configure custom DNS options or firewall rules. The special string `%i' is expanded to INTERFACE. Each one may be specified multiple times, in which case the commands are executed in order.

- SaveConfig — if set to `true', the configuration is saved from the current state of the interface upon shutdown. Any changes made to the configuration file before the interface is removed will therefore be overwritten.

Recommended INTERFACE names include `wg0' or `wgvpn0' or even `wgmgmtlan0'. However, the number at the end is in fact optional, and really any free-form string [a-zA-Z0-9_=+.-]{1,15} will work. So even interface names corresponding to geographic locations would suffice, such as `cincinnati', `nyc', or `paris', if that's somehow desirable.

## EXAMPLES
These examples draw on the same syntax found for wg(8), and a more complete description may be found there. Bold lines below are for options that extend wg(8).

The following might be used for connecting as a client to a VPN gateway for tunneling all traffic:

[Interface]

Address = 10.200.100.8/24

DNS = 10.200.100.1

PrivateKey = oK56DE9Ue9zK76rAc8pBl6opph+1v36lm7cXXsQKrQM=

[Peer]

PublicKey = GtL7fZc/bLnqZldpVofMCD6hDjrK28SsdLxevJ+qtKU=

PresharedKey = /UwcSPg38hW/D9Y3tcS1FOV0K1wuURMbS0sesJEP5ak=

AllowedIPs = 0.0.0.0/0

Endpoint = demo.wireguard.com:51820

The `Address` field is added here in order to set up the address for the interface. The `DNS` field indicates that a DNS server for the interface should be configured via resolvconf(8). The peer's allowed IPs entry implies that this interface should be configured as the default gateway, which this script does.

Building on the last example, one might attempt the so-called ``kill-switch'', in order to prevent the flow of unencrypted packets through the non-WireGuard interfaces, by adding the following two lines `PostUp` and `PreDown` lines to the `[Interface]` section:

PostUp = iptables -I OUTPUT ! -o %i -m mark ! --mark $(wg show %i fwmark) -m addrtype ! --dst-type LOCAL -j REJECT

PreDown = iptables -D OUTPUT ! -o %i -m mark ! --mark $(wg show %i fwmark) -m addrtype ! --dst-type LOCAL -j REJECT

The `PostUp' and `PreDown' fields have been added to specify an iptables(8) command which, when used with interfaces that have a peer that specifies 0.0.0.0/0 as part of the `AllowedIPs', works together with wg-quick's fwmark usage in order to drop all packets that are either not coming out of the tunnel encrypted or not going through the tunnel itself. (Note that this continues to allow most DHCP traffic through, since most DHCP clients make use of PF_PACKET sockets, which bypass Netfilter.) When IPv6 is in use, additional similar lines could be added using ip6tables(8).

Or, perhaps it is desirable to store private keys in encrypted form, such as through use of pass(1):

PreUp = wg set %i private-key <(pass WireGuard/private-keys/%i)

For use on a server, the following is a more complicated example involving multiple peers:

[Interface]

Address = 10.192.122.1/24

Address = 10.10.0.1/16

SaveConfig = true

PrivateKey = yAnz5TF+lXXJte14tji3zlMNq+hd2rYUIgJBgB3fBmk=

ListenPort = 51820

[Peer]

PublicKey = xTIBA5rboUvnH4htodjb6e697QjLERt1NAB4mZqp8Dg=

AllowedIPs = 10.192.122.3/32, 10.192.124.1/24

[Peer]

PublicKey = TrMvSoP4jYQlY6RIzBgbssQqY3vxI2Pi+y71lOWWXX0=

AllowedIPs = 10.192.122.4/32, 192.168.0.0/16

[Peer]

PublicKey = gN65BkIKy1eCE9pP1wdc8ROUtkHLF2PfAqYdyYBz6EA=

AllowedIPs = 10.10.10.230/32

Notice the two `Address' lines at the top, and that `SaveConfig' is set to `true', indicating that the configuration file should be saved on shutdown using the current status of the interface.

A combination of the `Table', `PostUp', and `PreDown' fields may be used for policy routing as well. For example, the following may be used to send SSH traffic (TCP port 22) traffic through the tunnel:

[Interface]

Address = 10.192.122.1/24

PrivateKey = yAnz5TF+lXXJte14tji3zlMNq+hd2rYUIgJBgB3fBmk=

ListenPort = 51820

Table = 1234

PostUp = ip rule add ipproto tcp dport 22 table 1234

PreDown = ip rule delete ipproto tcp dport 22 table 1234

[Peer]

PublicKey = xTIBA5rboUvnH4htodjb6e697QjLERt1NAB4mZqp8Dg=

AllowedIPs = 0.0.0.0/0

These configuration files may be placed in any directory, putting the desired interface name in the filename:

\# wg-quick up /path/to/wgnet0.conf

For convenience, if only an interface name is supplied, it automatically chooses a path in `/etc/wireguard/':

\# wg-quick up wgnet0

This will load the configuration file `/etc/wireguard/wgnet0.conf'.

The strip command is useful for reloading configuration files without disrupting active sessions:

\# wg syncconf wgnet0 <(wg-quick strip wgnet0)

## SEE ALSO
wg(8), ip(8), ip-link(8), ip-address(8), ip-route(8), ip-rule(8), resolvconf(8).

## AUTHOR
wg-quick was written by Jason A. Donenfeld. For updates and more information, a project page is available on the World Wide Web.


amorad

package: amora

title: amorad(8)

text:
# amorad(8)

## NAME
amorad - Amora (A Remote Mobile Assistant) daemon

## SYNOPSIS
amorad [options]

## DESCRIPTION
Amora is an application that enables you to control your PC desktop using a cellphone. It uses bluetooth to send mouse and keyboard events to the graphical session. With it you can control your slides in OpenOffice.org, movies or any other application. Amora also has a screenshot feature, where you can see a thumbnail in the cellphone screen of the currently focused window in your desktop.

The server (amorad) is written in C using Xlib and XTest to send events for X session and the POSIX socket API for I/O. It must be started by the user, inside a valid X session.

## OPTIONS
-h

Help (usage) message

-l

Set a specific path for the log file

-v

Show program version and exit

## AMORA CLIENT
In order to use amora, you need a mobile phone with amora-client installed and running. The current client is implemented in Python for S60 (Nokia cellphones).

## BUGS
See the current bugs and open new ones in the project website.

## CREDITS
Author: Adenilson Cavalcanti da Silva

Contributions from: Ademar de Souza Reis Jr., Alexis Younes, Thiago Marcos Santos, Wilson Prata and others;

## SEE ALSO
http://code.google.com/p/amora/


anacron

package: anacron

title: anacron(8)

summary: runs commands periodically

text:
# anacron(8)

## 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)>.


and

package: and

title: and(8)

summary: auto nice daemon

text:
# and(8)

## NAME
and - auto nice daemon

## SYNOPSIS
and [-htvsx] [-i interval] [-c /path/to/and.conf] [-d /path/to/and.priorities]

## VERSION
This manual page documents and version 1.2.2.

## DESCRIPTION
The auto nice daemon activates itself in certain intervals and renices and even kills jobs according to their priority and CPU usage.

Renice levels and kill signals can be defined in terms of users, groups, and commands. Wildcards can be specified for any of these. In addition, commands can be specified using POSIX regular expressions. To allow for network-wide configuration and priority files, a mechanism for hostname-based evaluation is provided, again supporting regular expressions for specifying host names.

Jobs owned by root are left alone. Jobs are never increased in their priority.

Here are some real-world examples:

A certain user is notorious for wasting CPU with next-to-irrelevant jobs. One line is sufficient to renice all of his jobs to about 19. This is a typical situation for a LART (Luser's Attitude Readjustment Tool) like and.

A CPU server is dedicated to a certain group, but others may also use it when it's idle. Just define default nice levels of e.g. 18 and a lower nice level for the privilegued group, say nice level 12.

A certain web browser who shall remain unnamed tends to go berserk once in a while. You can configure and to kill -9 it after e.g. 20 CPU minutes.

## COMMAND-LINE OPTIONS
-c /path/to/and.conf

Specifies the configuration file. If this flag is omitted, /etc/and/and.conf is used instead.

-d /path/to/and.priorities

Specifies the priority database file. If this flag is omitted, /etc/and/and.priorities is used instead.

-h

Produces a short help text.

-i interval

Sets the interval between nice level checks. This flag overrides the interval specified in the configuration file, if any. The default interval of 60 seconds is used if neither -i nor an interval directive in the configuration file is given.

-s

Log to stdout. Without this switch, logging goes to syslog (normal operations) or ./debug.and (test mode). Useful for debugging config files.

-t

Run in test mode only, i.e. don't really renice or kill anything. In this mode, logging goes into ./debug.and instead of syslog.

-v

Increase verbosity. For maximum verbosity, this flag can be specified multiple times. Be warned that this will blow up your log files, so you should use it in test mode only.

-x

Run in full operational mode, i.e. really renice or kill things. This is the default.

## SIGNALS
On kill -HUP the auto nice daemon will reload its configuration file and priority database.

## FILES
/etc/and/and.conf

General configuration file. Stores default nice level, default interval, the "time zones" and the database lookup affinity.

/etc/and/and.priorities

The priority database (in plain text). Contains the (user, group, command, nicelevels) tuples.

Both files have their own manual pages.

./debug.and

Contains logging and status information for debugging purposes. Used in test mode only.

## SEE ALSO
and.conf(5), and.priorities(5), kill(1), regex(7), renice(8)

## INTERNET
http://and.sourceforge.net/

## AUTHOR
The auto nice daemon and this manual page were written by Patrick Schemitz <schemitz@users.sourceforge.net>


angie

package: angie

title: angie(8)

text:
# angie(8)

## NAME
Angie — HTTP and reverse proxy server, mail proxy server

## SYNOPSIS
angie

[-?hqTtVvmM] [-c file] [-e file] [-g directives] [-p prefix] [-s signal] [--help] [--build-env] [--log-level=level]

## DESCRIPTION
Angie is an HTTP and reverse proxy server, a mail proxy server, and a generic TCP/UDP proxy server. It is known for its high performance, stability, rich feature set, simple configuration, and low resource consumption.

The options are as follows:

-?, -h, --help

Print help.

-c file

Use an alternative configuration file.

-e file

Use an alternative error log file. Special value stderr indicates that the standard error output should be used.

-g directives

Set global configuration directives. See EXAMPLES for details.

-p prefix

Set the prefix path. The default value is %%PREFIX%%.

-q

Suppress non-error messages during configuration testing.

-s signal

Send a signal to the master process. The argument signal can be one of: stop, quit, reopen, reload. The following table shows the corresponding system signals:

stop

SIGTERM

quit

SIGQUIT

reopen

SIGUSR1

reload

SIGHUP

-m

Show built-in modules and exit.

-M

Show built-in and loaded modules, then exit.

-T

Same as -t, but additionally dump configuration files to standard output.

-t

Do not run, just test the configuration file. Angie checks the configuration file syntax and then tries to open files referenced in the configuration file.

-V

Print the Angie version, compiler version, and configure script parameters.

-v

Print the Angie version.

--build-env

Show build environment and exit.

--log-level=level

Set initial error log level.

## SIGNALS
The master process of Angie can handle the following signals:

SIGINT, SIGTERM

Shut down quickly.

SIGHUP

Reload configuration, start the new worker process with a new configuration, and gracefully shut down old worker processes.

SIGQUIT

Shut down gracefully.

SIGUSR1

Reopen log files.

SIGUSR2

Upgrade the Angie executable on the fly.

SIGWINCH

Shut down worker processes gracefully.

While there is no need to explicitly control worker processes normally, they support some signals too:

SIGTERM

Shut down quickly.

SIGQUIT

Shut down gracefully.

SIGUSR1

Reopen log files.

## DEBUGGING LOG
To enable a debugging log, reconfigure Angie to build with debugging:

./configure --with-debug ...

and then set the debug level of the error_log:

error_log /path/to/log debug;

It is also possible to enable the debugging for a particular IP address:

```
events {
	debug_connection 127.0.0.1;
}
```

## ENVIRONMENT
The ANGIE environment variable is used internally by Angie and should not be set directly by the user.

## FILES
%%PID_PATH%%

Contains the process ID of Angie. The contents of this file are not sensitive, so it can be world-readable.

%%CONF_PATH%%

The main configuration file.

%%ERROR_LOG_PATH%%

Error log file.

## EXIT STATUS
Exit status is 0 on success, or 1 if the command fails.

## EXAMPLES
Test configuration file ~/myangie.conf with global directives for PID and quantity of worker processes:

```
angie -t -c ~/myangie.conf \
	-g "pid /var/run/myangie.pid; worker_processes 2;"
```

## SEE ALSO
For online documentation, technical support, and bug reports, please refer to https://en.angie.software.

## HISTORY
On 27 of July 2022 a group of former nginx developers registered LLC "Web Server" in order to create and maintain new fork of nginx called Angie.

## AUTHORS
This manual page was originally written by Sergey A. Osokin <osa@FreeBSD.org.ru>


aoe-discover

package: aoetools

title: aoe-discover(8)

summary: tell aoe driver to discover AoE devices

text:
# aoe-discover(8)

## NAME
aoe-discover - tell aoe driver to discover AoE devices

## SYNOPSIS

```
aoe-discover
```

## DESCRIPTION
The aoe-discover command tells the aoe driver to discover ATA over Ethernet (AoE) devices on the network. All network interfaces will be probed with a AoE config query broadcast.

If the aoe-interfaces command has limited the allowable network interfaces, only devices discovered via allowable interfaces will become available. The default is to make available all AoE devices found on all accessible ethernet networks.

It's good to run the aoe-discover command after running aoe-interfaces.

## EXAMPLE
In this example, the root user on a host named nai loads the aoe module with only eth0 allowable for AoE traffic. After remembering that shelf 7 is on eth3, this sysadmin uses aoe-interfaces to add eth3 to the list of allowable network interfaces and then calls aoe-discover to ask the aoe driver to look for new AoE devices.

```
nai:~# modprobe aoe aoe_iflist="eth0"
nai:~# aoe-stat

   e10.9            eth0              up
nai:~# aoe-interfaces eth0 eth3
nai:~# aoe-discover
nai:~# aoe-stat

    e7.0            eth3              up

    e7.1            eth3              up

    e7.2            eth3              up

    e7.3            eth3              up

    e7.4            eth3              up

    e7.5            eth3              up

    e7.6            eth3              up

    e7.7            eth3              up

    e7.8            eth3              up

    e7.9            eth3              up

   e10.9            eth0              up
```

## SEE ALSO
aoe-interfaces(8), aoe-stat(8), aoetools(8).

## AUTHOR
Ed L. Cashin (ecashin@coraid.com)


aoe-flush

title: aoe-flush(8)

text:
# aoe-flush(8)

## NAME
aoe-flush - flush the down devices out of the aoe driver

## SYNOPSIS

```
aoe-flush [-a]
aoe-flush dev1 [dev2 ...]
```

## DESCRIPTION
The aoe-flush command tells the aoe driver to remove devices from the system and forget about them. Normally the aoe driver will remember all devices it has seen until the module is unloaded. By default, aoe-flush will only flush downed devices. With the -a flag all devices are candidates for removal.

aoe-flush will not remove devices that are in use. This includes devices in the closewait state or those in the process of being installed.

By specifying a series of specific aoe devices, e.g., e7.0 e3.2, it is possible to ask the aoe driver to forget these devices. This feature may be convenient after a temporary AoE target is no longer being used.

## OPTIONS
-a

The -a option tells the aoe driver to forget all unused devices.

## EXAMPLE

```
nai# aoe-stat | grep e12.0

     e12.0         0.000GB   eth1 down
nai# aoe-flush
nai# aoe-stat | grep e12.0
```

## BUGS
Flushed devices may reappear when they are discovered by the periodic discovery beacon. aoe-discover may be used to force this behaviour.

## SEE ALSO
aoe-stat(8), aoe-discover(8), aoetools(8).

## AUTHOR
Sam Hopkins (sah@coraid.com)


aoe-interfaces

title: aoe-interfaces(8)

text:
# aoe-interfaces(8)

## NAME
aoe-interfaces - restrict aoe driver to specified network interfaces

## SYNOPSIS

```
aoe-interfaces [dev1] [dev2 ...]
aoe-interfaces -c
```

## DESCRIPTION
The aoe-interfaces command tells the aoe driver to ignore ATA over Ethernet (AoE) traffic on all but the specified network interfaces. It is analogous to the aoe_iflist module load option.

If neither the aoe_iflist module load option nor the aoe-interfaces command are used, the aoe driver will use any network interface for AoE traffic. Using aoe-interfaces to limit AoE to only trusted networks prevents the case where a rogue AoE target appears on a public network, diverting data from the legitimate AoE target. Such an imposter target effectively corrupts the data on the legitimate target.

If the aoe driver is a module, then calling aoe-interfaces without arguments will display the current interfaces list. If it hasn't been set then the output will be blank.

It's good to run the aoe-discover command after setting the AoE interfaces list.

## OPTIONS
-c

The -c flag will clear the interface access list, permitting any interface to be used.

## EXAMPLE
In this example, the root user on a host named nai loads the aoe module with only eth0 allowable for AoE traffic. After remembering that shelf 7 is on eth3, this sysadmin uses aoe-interfaces to add eth3 to the list of allowable network interfaces and then calls aoe-discover to ask the aoe driver to look for new AoE devices.

```
nai:~# modprobe aoe aoe_iflist="eth0"
nai:~# aoe-stat

   e10.9            eth0              up
nai:~# aoe-interfaces eth0 eth3
nai:~# aoe-discover
nai:~# aoe-stat

    e7.0            eth3              up

    e7.1            eth3              up

    e7.2            eth3              up

    e7.3            eth3              up

    e7.4            eth3              up

    e7.5            eth3              up

    e7.6            eth3              up

    e7.7            eth3              up

    e7.8            eth3              up

    e7.9            eth3              up

   e10.9            eth0              up
nai:~# aoe-interfaces
eth0 eth3
```

## SEE ALSO
aoe-discover(8), aoe-stat(8), aoetools(8).

## AUTHOR
Ed L. Cashin (ecashin@coraid.com)


aoe-mkdevs

title: aoe-mkdevs(8)

text:
# aoe-mkdevs(8)

## NAME
aoe-mkdevs - create special device files for aoe driver

## SYNOPSIS

```
aoe-mkdevs {device-dir}
env n_partitions=1 aoe-mkdevs {device-dir}
```

## DESCRIPTION
The aoe-mkdevs command is deprecated in favor of udev. Systems with udev do not need to use the aoe-mkdevs or aoe-mkself commands, because udev will create device nodes as needed.

Systems without udev use aoe-mkdevs to create the character special files necessary to control the aoe driver. The aoe-mkdevs command uses aoe-mkshelf to also create block special files.

The aoe drivers after version 49 support dynamic minor device numbers so that a greater number of devices can be supported. The aoe-mkdevs command is incompatible with dynamic device numbers. If your system lacks udev, and you are using an aoe driver version 50 or above, use the aoe_dyndevs=0 module option to force the aoe driver to use static device numbers.

If you are not using dynamic device numbers, and you built your aoe driver to support only one partition per device (whole-disk partitions), then the device files must match, and you should use the n_partitions environment variable described below.

### Arguments
device-dir

This should be the name of the directory where the special device files will be created.

## ENVIRONMENT VARIABLES
If the n_partitions variable is set in the environment, it will override the default number of partitions per aoe disk, namely 16.

## EXAMPLE
In this example, the root user on a host named nai creates special files for using the aoe disks in shelf 7. After remembering that the driver doesn't have partition support, this sysadmin gets rid of the mismatching device nodes and calls aoe-mkdevs again with n_partitions set to 1.

```
nai:~# rm -rf /dev/etherd
nai:~# aoe-mkdevs /dev/etherd
nai:~# ls /dev/etherd | wc -l
1603
nai:~# rm -rf /dev/etherd
nai:~# n_partitions=1 aoe-mkdevs /dev/etherd
nai:~# ls /dev/etherd | wc -l
103
```

## SEE ALSO
aoe-discover(8), aoe-interfaces(8), aoe-mkshelf(8), aoe-stat(8), aoetools(8), udev(7).

## AUTHOR
Ed L. Cashin (ecashin@coraid.com)


aoe-mkshelf

title: aoe-mkshelf(8)

text:
# aoe-mkshelf(8)

## NAME
aoe-mkshelf - create special device files for one shelf address

## SYNOPSIS

```
aoe-mkshelf {device-dir} {shelf-address}
env n_partitions=1 aoe-mkshelf {device-dir} {shelf-address}
```

## DESCRIPTION
The aoe-mkshelf command is not needed on systems that have udev installed and is incompatible with aoe drivers that have the aoe_dyndevs module parameter set to 1.

Systems lacking udev and having an aoe driver that uses static minor device numbers can use aoe-mkshelf to create the block special files necessary to access the AoE devices with the given shelf address.

All aoe drivers prior to aoe6-50 use static minor device numbers. Versions 50 and up use dynamic minor device numbers when the module parameter aoe_dyndevs=1 is set.

If you are using static minor device numbers and your aoe driver supports only one partition per device (whole-disk partitions), then the device files must match, and you should use the n_partitions environment variable described below.

### Arguments
device-dir

This should be the name of the directory where the block device files will be created.

shelf-address

This is the AoE major address, or shelf address, for which to create device nodes. For example, specifying a shelf address of 1 means that the e1.* device nodes will be created in device-dir.

## ENVIRONMENT VARIABLES
If the n_partitions variable is set in the environment, it will override the default number of partitions per aoe disk, namely 16.

## EXAMPLE
In this example, the root user on a host named nai creates special files for using the aoe disks in shelf 7. Then he remembers that the driver doesn't have partition support, so the command is called again with n_partitions set to 1.

```
nai:~# aoe-mkshelf /dev/etherd 7
nai:~# ls /dev/etherd/e7.* | wc -l
160
nai:~# rm /dev/etherd/e7.*
nai:~# n_partitions=1 aoe-mkshelf /dev/etherd 7
nai:~# ls /dev/etherd/e7.* | wc -l
10
nai:~#
```

## SEE ALSO
aoe-discover(8), aoe-interfaces(8), aoe-mkdevs(8), aoe-stat(8), aoetools(8), udev(7).

## AUTHOR
Ed L. Cashin (ecashin@coraid.com)


aoe-revalidate

title: aoe-revalidate(8)

text:
# aoe-revalidate(8)

## NAME
aoe-revalidate - revalidate the disk size of an aoe device

## SYNOPSIS

```
aoe-revalidate e{major}.{minor}
```

## DESCRIPTION
The aoe-revalidate command tells the aoe driver to revalidate the disk size of an open aoe device. Normally the aoe driver will only acknowledge changes in an aoe device's disk size when the aoe device is not open.

It should be noted that if an aoe device's disk size shrinks in revalidation any users may become hopelessly confused when their resumed I/O starts to fail.

## EXAMPLE

```
nai# aoe-stat | grep e1.9

     e1.9        82.348GB   eth0 up
nai# < /dev/etherd/e1.9 sleep 600 &
[1] 13006
nai# aoe-revalidate e1.9
nai# aoe-stat | grep e1.9

     e1.9       164.696GB   eth0 up
```

## SEE ALSO
aoe-stat(8), aoetools(8).

## AUTHOR
Sam Hopkins (sah@coraid.com)


aoe-sancheck

title: aoe-sancheck(8)

summary: verify storage network capabilities

text:
# aoe-sancheck(8)

## NAME
aoe-sancheck - verify storage network capabilities

## SYNOPSIS

```
aoe-sancheck [-v]
```

## DESCRIPTION
The aoe-sancheck command collects information about the local interfaces and probes the network for ATA over Ethernet devices, validating the paths for each device. It does not use the aoe kernel module but rather the bpf interface to evaluate the network. As such, the aoe module does not need to be loaded to perform the test.

The output of the command is divided into two sections: information about the local interfaces followed by a list of detected AoE devices. The first section displays the local interfaces, if the interface is up or down, its configured MTU, and the PCI ID for the interface.

The second section lists detected AoE devices, one per line, with the following information:

Device

The device name of the form eX.Y where X is the AoE device shelf address, and Y is the AoE device slot address.

Macs

The number of mac addresses detected for this device.

Payload

The number of bytes of data the device can handle in a single AoE request. This number does not represent the total frame size as it does not include bytes from ethernet or AoE headers.

Local Interfaces

The list of local interfaces from which the device is visible.

### Options
-v

Prints out additional raw information.

## DIAGNOSIS
For each device, aoe-sancheck may print out additional lines of suggestions or warnings. The following checks are made:

The MTU of the local interfaces is set high enough to handle the AoE device's reported payload.

Depending on the host NIC's capabilities and storage network switch's capabilities, best performance may or may not be with local interface MTU set higher than a device's payload size.

The number of local interfaces matches the number of interfaces on the device.

Best performance comes from having a host and device with comparable bandwidth. Aoe-sancheck simply counts the number of interfaces involved and does not figure link bandwidth in its comparison.

All local interfaces for an AoE device have the same MTU.

If one interface for a device has a smaller MTU than the others, the AoE driver must use the smaller payload size for all interfaces.

Each path to the device is capable of the configured payload size.

This check detects the situation where a local interface is configured for jumbo frames and the AoE device is capable of jumbo frames, but some aspect of the network is incapable of passing frames that size, for example, a misconfigured switch. Aoe-sancheck reports the maximum payload size the path is capable of if less than the configured payload size.

## BUGS
The program may sometimes display inconsistent results between runs showing that a path is capable of a smaller frame size than it actually is. If you see this behavior, please email one of the authors with your verbose output.

## SEE ALSO
aoeping(8), aoetools(8)

## AUTHORS
Justin Sanders (justin@coraid.com), Sam Hopkins (sah@coraid.com)


aoe-stat

title: aoe-stat(8)

summary: print aoe device status report

text:
# aoe-stat(8)

## NAME
aoe-stat - print aoe device status report

## SYNOPSIS

```
modprobe aoe
aoe-stat
env sysfs_dir=/sys aoe-stat
```

## DESCRIPTION
The aoe-stat script collects information on ATA over Ethernet devices from sysfs.

For each AoE device the kernel has discovered, there is one row in the script's output. Each row has the following columns.

devicename

The device name is of the form eX.Y,

with X being the AoE device shelf address, and Y being the AoE slot address.

size

The size of the AoE device is in gigabytes (billions of bytes).

ifname

The network interface name is printed in the third column.

payload

The number of bytes read from or written to the storage target in each AoE packet appears in the fourth column, unless the aoe driver does not export this information.

status

The device status is in the last column. Possible values are up, down, and down,closewait. The "up" status means the aoe driver considers this device ready for I/O. The "down" status means the opposite. The "down,closewait" status means that some software still has the device open, and when this straggler closes the device, it will enter the "down" state.

## UNAVAILABLE TARGETS
If a discovered AoE target will not respond to I/O commands, some of the information needed to allow Linux to use the device is not available. The aoe-stat command shows the missing information as "(NA)" fields.

It is normal for "(NA)" fields to appear during the brief time between the time that an AoE target is detected and the time the Linux kernel finishes reading its partition table.

## ENVIRONMENT VARIABLES
If the sysfs_dir variable is set in the environment, it will override the default location where aoe-stat will look for sysfs, namely /sys.

## WARNINGS
If the minor device number of a device node does not match that of its namesake, aoe-stat will print a warning as shown below.

```
nai:~# aoe-stat

      e0.3         0.104GB   eth0 up

      e0.4      4398.046GB   eth0 up

     e20.0      1000.215GB   eth0 up

     e42.0      2000.431GB   eth0 up
aoe-stat Warning: device node /dev/etherd/e45.1 has wrong minor device number

     e45.1      1152.874GB   eth0 up
```

Using such a device node is dangerous, because its name doesn't match the actual device that you would be reading from and writing to. Such a broken device node should be removed. Device nodes are created by udev or (on systems without udev) by aoe-mkdevs.

## EXAMPLE
In this example, the root user on a host named nai loads the aoe driver module and then prints a list of all the available aoe devices. Then he remembers to bring up the storage network interfaces, does an AoE discovery, and prints the list again. This time the list shows all the devices in shelf seven.

```
nai:~# modprobe aoe
nai:~# aoe-stat
nai:~# ifconfig eth3 up
nai:~# aoe-discover
nai:~# aoe-stat

      e0.0     10995.116GB   eth3 up

      e0.1     10995.116GB   eth3 up

      e0.2     10995.116GB   eth3 up

      e1.0      1152.874GB   eth3 up

      e7.0       370.566GB   eth3 up
nai:~#
```

## SEE ALSO
aoe-discover(8), aoe-interfaces(8), aoe-mkdevs(8), aoe-mkshelf(8), aoetools(8), udev(7).

## AUTHOR
Ed L. Cashin (ecashin@coraid.com)


aoe-version

title: aoe-version(8)

text:
# aoe-version(8)

## NAME
aoe-version - print AoE-related software version information

## SYNOPSIS

```
aoe-version
```

## DESCRIPTION
The aoe-version script collects information on running and installed ATA over Ethernet software, displaying a summary.

## EXAMPLE

```
ellijay:~# aoe-version

              aoetools: 17

  installed aoe driver: 50

    running aoe driver: 50
```

## SEE ALSO
aoe-discover(8), aoe-interfaces(8), aoetools(8), aoe-stat(8).

## AUTHOR
Ed L. Cashin (ecashin@coraid.com)


aoecfg

title: aoecfg(8)

summary: manipulate AoE configuration strings

text:
# aoecfg(8)

## NAME
aoecfg - manipulate AoE configuration strings

## SYNOPSIS
aoecfg [-c cmd] [-s cfgstr] [-t timeout] [shelf slot] [netif]

## DESCRIPTION
Aoecfg(8) sends AoE configuration commands that control the retrivial, conditional or unconditional setting of AoE configuration strings. Since configuration happens before the MAC address of the target is known, the packet is broadcast. AoE targets with a matching shelf and slot respond. Since the default shelf and slot are the wildcard values 0xffff and 0xff, with no arguments aoecfg(8) will return configuration strings from all targets visible on the default interface, eth0.

## OPTIONS
-c cmd

specify the AoE configuration command. The default is read. The available commands are

read Read the server config string without performing any test and respond.

test Respond only if the specified string exactly matches the server configuration string.

prefix Respond only if the specified string is a prefix of the server configuration string.

set If the current server config string is empty, set the server config string to the argument string and respond. If the current server config string is not empty, return a response with Flags bit E set and Error set to 4.

fset Force set the server config string to the argument string and respond.

-s cfgstr

specify the config string.

-t timeout

specify the timeout in seconds. The default is no timeout. If neither the shelf nor the slot are specified, aoecfg(8) will exit after the first result. Otherwise, aoecfg(8) will exit only after the timeout has expired since it does not know how many responses to expect.

shelf slot

specify the shelf and slot used in the query. If unspecified, they default to broadcast.

netif

specifiy the network interface. The default is eth0.

## SEE ALSO
aoe-discover(8), aoe-interfaces(8), aoe-mkdevs(8), aoe-mkshelf(8), aoe-stat(8), aoeping(8), AoE (ATA over Ethernet): http://support.coraid.com/documents/AoEr10.txt, ATA specification

## AUTHOR
Erik Quanstrom (quanstro@coraid.com)


aoeping

title: aoeping(8)

summary: simple communication with AoE device

text:
# aoeping(8)

## NAME
aoeping - simple communication with AoE device

## SYNOPSIS
aoeping [options] {shelf} {slot} {netif}

## DESCRIPTION
The aoeping(8) program performs simple one or two-round-trip communication with an ATA over Ethernet (AoE) device. It creates and receives AoE packets directly, using raw network sockets.

Running aoeping(8) without command line arguments will result in a short usage summary being displayed.

The aoeping(8) program will wait forever if it doesn't receive an expected response. The caller should use a time out to catch this situation.

### Arguments
shelf

This should be the shelf address (major AoE address) of the AoE device to communicate with.

slot

This should be the slot address (minor AoE address) of the AoE device to communicate with.

netif

The name of the ethernet network interface to use for AoE communications, e.g., eth1.

### Options
-i

Issue an ATA "identify device" command after receiving the AoE device's Config Query response. The "ident" response will be printed on standard output as a hexidecimal dump.

-I

Issue an ATA "identify device" command after receiving the AoE device's Config Query response. The "ident" response will be pretty-printed on standard output as selected human-readable fields.

-v

Turn on more copious output, including a hexidecimal dump of the Config Query response from the AoE device (see AoE spec at URL below).

-s

This option takes an argument. The argument is a decimal integer that specifies the number of seconds that aoeping(8) will wait for a response before timing out and exiting with a non-zero status.

-S

This option takes an argument. The argument is the name of a SMART command to send to the disk. The SMART commands in the list below are supported. If the command requires data transfer, one sector (512 bytes) of data is always the amount transfered. If the command takes a parameter (for the Low LBA register), then the name of the SMART command is immediately followed by a colon and then a number, the value of the parameter, e.g., "-S read_log:1".

read_data

offline_immediate

read_log

write_log

enable

disable

return_status For write_log, aoeping(8) reads from standard input the one sector of data to be written to the specified log.

If the AoE device does not support SMART commands or if the command is aborted, an error message is printed to standard error and aoeping(8) exits with a non-zero status. A command may be aborted if SMART is disabled on the device.

The aoeping(8) command just sends and receives SMART commands, without interpreting them. See the ATA specification for more information on using SMART.

-t

(This is an advanced feature.) This option has an argument. The argument is a decimal integer that is used as the initial tag, with the highest bit set, as the first tag in ATA commands. Tags for subsequent ATA commands will be incremented by one.

-h

Show a usage summary.

## EXAMPLE
In this example, the root user uses aoeping(8) to check for the presence of aoe device e10.9 on network interface eth0.

```
bash# aoeping -v 10 9 eth0 | head
tag: 80000000
eth: eth0
shelf: 10
slot: 9
config query response:
00 0d 87 aa c9 00 00 10 04 00 11 1f 88 a2 18 00
00 0a 09 01 00 00 00 00 00 03 30 08 00 10 00 04
66 6f 6f 0a 00 ff ff ff ff ff ff ff ff ff ff ff
ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff
ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff
```

The next example shows root making sure the disk on the e10.9 is still responsive by issuing an ATA device identify command with a 20-second timeout.

```
bash# aoeping -i -s 20 \

  10 9 eth0 > /dev/null \

  && echo ok
ok
```

The next example uses SMART to determine whether the disk on e10.9 thinks it has exceeded its error threshold. The ATA spec says that the LBA Mid register will be 0x4f when the disk has not exceeded its error threshold.

```
bash# aoeping -S return_status \

  10 9 eth0 | grep 'LBA Mid: 0x4f' \

  > /dev/null \

  && echo ok
ok
```

Note that in a script, it would be prudent to specify and handle a timeout. Also, a good script would make sure the Status register does not have the error bit (bit zero) or the device fault bit (bit 5) set.

## SEE ALSO
aoe-discover(8), aoe-interfaces(8), aoe-mkdevs(8), aoe-mkshelf(8), aoe-stat(8),

AoE (ATA over Ethernet): http://support.coraid.com/documents/AoEr10.txt,

ATA specification

## AUTHOR
Ed L. Cashin (ecashin@coraid.com)


coraid-update

title: coraid-update(8)

text:
# coraid-update(8)

## NAME
coraid-update - upload an update file to a CORAID appliance

## SYNOPSIS

```
coraid-update {update file} {AoE device}
```

## DESCRIPTION
The coraid-update script performs a few sanity checks before copying the local update file to the remote update AoE target on the CORAID appliance.

Two arguments are provided: 1) the name of the update file to be uploaded, and 2) the special block device file corresponding to the update target, e.g., /dev/etherd/e100.40.

It generates no output and exits with a zero status when the update file has been successfully uploaded to the update target on the appliance. Otherwise, an error message is printed to standard error and coraid-update exits with a non-zero status.

## SEE ALSO
aoe-discover(8), aoe-interfaces(8), aoe-stat(8), aoetools(8), udev(7).

## AUTHOR
Ed L. Cashin (ecashin@coraid.com)


title: a2chkconfig(8)

text:
# a2chkconfig(8)

## NAME
a2chkconfig is an utility for apache2 autostart modification.

## SYNOPSIS
a2chkconfig

## SUMMARY
a2chkconfig reads configuration files from conf/*-start.d/* and creates or removes symbolic links in corresponding /etc/httpd2/conf/*-enabled.

Syntax of configuration files in directories conf/*-start.d:

NAME={yes,no}

where NAME is a filename in corresponding conf/*-available.

## EXAMPLE
If you want to disable mod_alias you have to edit file /etc/httpd2/conf/mods-start.d/000-default.conf and change parameter alias to "no". You can see that symbolic link "alias.load" removed from directory /etc/httpd2/conf/mods-enabled.d

## BUGS
Configuration files in conf/*-start.d/* must have new line at the end of file.

## AUTHOR
Written by Andrew Avramenko with help of Aleksey Avdeev.

## COPYRIGHT
Copyright © 2007. ALT Linux TEAM.

This is free software. You may redistribute copies of it under the terms of the GNU General Public License <http://www.gnu.org/licenses/gpl.html>. There is NO WARRANTY, to the extent permitted by law.

## SEE ALSO
a2enmod(8) a2dismod(8) a2enextra(8) a2disextra(8) a2ensite(8) a2dissite(8) apachectl(8)


title: a2enmod(8)

summary: enable or disable an apache2 module

text:
# a2enmod(8)

## NAME
a2enmod, a2dismod - enable or disable an apache2 module

## SYNOPSIS
a2enmod [module]

a2dismod [module]

## DESCRIPTION
This manual page documents briefly the a2enmod and a2dismod commands.

a2enmod is a script that enables the specified module within the apache2 configuration. It does this by creating symlinks within /etc/apache2/mods-enabled. Likewise, a2dismod disables a module by removing those symlinks. It is not an error to enable a module which is already enabled, or to disable one which is already disabled.

## NOTE
a2enmod also enables the module in the conf/mods-start.d/* files to prevent the module explicitly enabled from being disabled after update. a2dismod disables module in conf/mods-start.d/* for the same reason.

## EXAMPLES
a2enmod imagemap

a2dismod mime_magic

Enables the mod_imagemap module, and disables the mod_mime_magic module.

## FILES
/etc/apache2/mods-available

Directory with files giving information on available modules.

/etc/apache2/mods-enabled

Directory with links to the files in mods-available for enabled modules.

## SEE ALSO
apache2ctl(8).

## AUTHOR
This manual page was written by Daniel Stone <daniel@sfarc.net> for the Debian GNU/Linux distribution, as it is a Debian-specific script with the package.


apachectl

title: apachectl(8)

summary: Apache HTTP Server Control Interface

text:
# apachectl(8)

## NAME
apachectl - Apache HTTP Server Control Interface

## SYNOPSIS
When acting in pass-through mode, apachectl can take all the arguments available for the httpd binary.

apachectl [ httpd-argument ]

When acting in SysV init mode, apachectl takes simple, one-word commands, defined below.

apachectl command

## SUMMARY
apachectl is a front end to the Apache HyperText Transfer Protocol (HTTP) server. It is designed to help the administrator control the functioning of the Apache httpd daemon.

The apachectl script can operate in two modes. First, it can act as a simple front-end to the httpd command that simply sets any necessary environment variables and then invokes httpd, passing through any command line arguments. Second, apachectl can act as a SysV init script, taking simple one-word arguments like start, restart, and stop, and translating them into appropriate signals to httpd.

If your Apache installation uses non-standard paths, you will need to edit the apachectl script to set the appropriate paths to the httpd binary. You can also specify any necessary httpd command line arguments. See the comments in the script for details.

The apachectl script returns a 0 exit value on success, and >0 if an error occurs. For more details, view the comments in the script.

## OPTIONS
Only the SysV init-style options are defined here. Other arguments are defined on the httpd manual page.

start

Start the Apache httpd daemon. Gives an error if it is already running. This is equivalent to apachectl -k start.

stop

Stops the Apache httpd daemon. This is equivalent to apachectl -k stop.

restart

Restarts the Apache httpd daemon. If the daemon is not running, it is started. This command automatically checks the configuration files as in configtest before initiating the restart to make sure the daemon doesn't die. This is equivalent to apachectl -k restart.

fullstatus

Displays a full status report from mod_status. For this to work, you need to have mod_status enabled on your server and a text-based browser such as lynx available on your system. The URL used to access the status report can be set by editing the STATUSURL variable in the script.

status

Displays a brief status report. Similar to the fullstatus option, except that the list of requests currently being served is omitted.

graceful

Gracefully restarts the Apache httpd daemon. If the daemon is not running, it is started. This differs from a normal restart in that currently open connections are not aborted. A side effect is that old log files will not be closed immediately. This means that if used in a log rotation script, a substantial delay may be necessary to ensure that the old log files are closed before processing them. This command automatically checks the configuration files as in configtest before initiating the restart to make sure Apache doesn't die. This is equivalent to apachectl -k graceful.

graceful-stop

Gracefully stops the Apache httpd daemon. This differs from a normal stop in that currently open connections are not aborted. A side effect is that old log files will not be closed immediately. This is equivalent to apachectl -k graceful-stop.

configtest

Run a configuration file syntax test. It parses the configuration files and either reports Syntax Ok or detailed information about the particular syntax error. This is equivalent to apachectl -t.

The following option was available in earlier versions but has been removed.

startssl

To start httpd with SSL support, you should edit your configuration file to include the relevant directives and then use the normal apachectl start.

## FILES
The default paths listed below may be changed at compile time. Consult your local installation for the actual locations.

/usr/local/apache2/bin/envvars

Environment variable settings sourced at startup.

/usr/local/apache2/bin/httpd

The httpd binary invoked by apachectl.


title: check_forensic(8)

text:
# check_forensic(8)

## NAME
check_forensic - tool to extract mod_log_forensic output from apache log files

## SYNOPSIS
check_forensic <log_file>

## DESCRIPTION
chech_forensic is a simple shell script designed to help apache administrators to extract mod_log_forensic output from apache, apache-ssl and apache-perl log files.

## AUTHOR
This manual page was written by Fabio M. Di Nitto <fabbione@fabbione.net>, for the Debian GNU/Linux system (but may be used by others).


checkgid

title: checkgid(8)

summary: checks the gid

text:
# checkgid(8)

## NAME
checkgid - checks the gid

## SYNOPSIS
checkgid group

## DESCRIPTION
This manual page documents briefly the checkgid command.

checkgid is a program that checks whether it can setgid to the group specified. This is to see if it is a valid group for apache2 to use at runtime. If the user (should be run as superuser) is in that group, or can setgid to it, it will return 0.

## AUTHOR
This manual page was written by Daniel Stone <daniel@sfarc.net> for the Debian GNU/Linux distribution, as the original did not have a manpage.


fcgistarter

title: fcgistarter(8)

summary: Start a FastCGI program

text:
# fcgistarter(8)

## NAME
fcgistarter - Start a FastCGI program

## SYNOPSIS
fcgistarter -c command -p port [ -i interface ] -N num

## NOTE
Currently only works on Unix systems.

## OPTIONS
-c command

Absolute path of the FastCGI program

-p port

Port which the program will listen on

-i interface

Interface which the program will listen on

-N num

Number of instances of the program


httpd

title: httpd(8)

text:
# httpd(8)

## NAME
httpd - Apache Hypertext Transfer Protocol Server

## SYNOPSIS
httpd [ -d serverroot ] [ -f config ] [ -C directive ] [ -c directive ] [ -D parameter ] [ -e level ] [ -E file ] [ -k start|restart|graceful|stop|graceful-stop ] [ -h ] [ -l ] [ -L ] [ -S ] [ -t ] [ -v ] [ -V ] [ -X ] [ -M ] [ -T ]

On Windows systems, the following additional arguments are available:

httpd [ -k install|config|uninstall ] [ -n name ] [ -w ]

## SUMMARY
httpd is the Apache HyperText Transfer Protocol (HTTP) server program. It is designed to be run as a standalone daemon process. When used like this it will create a pool of child processes or threads to handle requests.

In general, httpd should not be invoked directly, but rather should be invoked via apachectl on Unix-based systems or as a service on Windows NT, 2000 and XP and as a console application on Windows 9x and ME.

## OPTIONS
-d serverroot

Set the initial value for the ServerRoot directive to serverroot. This can be overridden by the ServerRoot directive in the configuration file. The default is /usr/local/apache2.

-f config

Uses the directives in the file config on startup. If config does not begin with a /, then it is taken to be a path relative to the ServerRoot. The default is conf/httpd.conf.

-k start|restart|graceful|stop|graceful-stop

Signals httpd to start, restart, or stop. See Stopping Apache httpd for more information.

-C directive

Process the configuration directive before reading config files.

-c directive

Process the configuration directive after reading config files.

-D parameter

Sets a configuration parameter which can be used with <IfDefine> sections in the configuration files to conditionally skip or process commands at server startup and restart. Also can be used to set certain less-common startup parameters including -DNO_DETACH (prevent the parent from forking) and -DFOREGROUND (prevent the parent from calling setsid() et al).

-e level

Sets the LogLevel to level during server startup. This is useful for temporarily increasing the verbosity of the error messages to find problems during startup.

-E file

Send error messages during server startup to file.

-h

Output a short summary of available command line options.

-l

Output a list of modules compiled into the server. This will not list dynamically loaded modules included using the LoadModule directive.

-L

Output a list of directives provided by static modules, together with expected arguments and places where the directive is valid. Directives provided by shared modules are not listed.

-M

Dump a list of loaded Static and Shared Modules.

-S

Show the settings as parsed from the config file (currently only shows the virtualhost settings).

-T (Available in 2.3.8 and later)

Skip document root check at startup/restart.

-t

Run syntax tests for configuration files only. The program immediately exits after these syntax parsing tests with either a return code of 0 (Syntax OK) or return code not equal to 0 (Syntax Error). If -D DUMP_VHOSTS is also set, details of the virtual host configuration will be printed. If -D DUMP_MODULES is set, all loaded modules will be printed.

-v

Print the version of httpd, and then exit.

-V

Print the version and build parameters of httpd, and then exit.

-X

Run httpd in debug mode. Only one worker will be started and the server will not detach from the console.

## FILES
The default paths listed below may be changed at compile time or with various command-line and configuration directives. Consult your local installation for the actual locations.

/usr/local/apache2/conf/httpd.conf

Main server configuration file.

/usr/local/apache2/conf/mime.types

Default MIME type mappings.

/usr/local/apache2/logs/error_log

Error log file.

/usr/local/apache2/logs/access_log

Access log file.

/usr/local/apache2/logs/httpd.pid

File containing the process ID of the running daemon.

The following arguments are available only on the Windows platform:

-k install|config|uninstall

Install Apache httpd as a Windows NT service; change startup options for the Apache httpd service; and uninstall the Apache httpd service.

-n name

The name of the Apache httpd service to signal.

-w

Keep the console window open on error so that the error message can be read.


rotatelogs

title: rotatelogs(8)

text:
# rotatelogs(8)

## NAME
rotatelogs - Piped logging program to rotate Apache logs

## SYNOPSIS
rotatelogs [ -l ] [ -L linkname ] [ -p program ] [ -f ] [ -D ] [ -t ] [ -v ] [ -e ] [ -c ] [ -n number-of-files ] logfile rotationtime|filesize(B|K|M|G) [ offset ]

## SUMMARY
rotatelogs is a simple program for use in conjunction with Apache's piped logfile feature. It supports rotation based on a time interval or maximum size of the log.

## OPTIONS
-l

Causes the use of local time rather than GMT as the base for the interval or for strftime(3) formatting with size-based rotation.

-L linkname

-p program

If given, rotatelogs will execute the specified program every time a new log file is opened. The filename of the newly opened file is passed as the first argument to the program. If executing after a rotation, the old log file is passed as the second argument. rotatelogs does not wait for the specified program to terminate before continuing to operate, and will not log any error code returned on termination. The spawned program uses the same stdin, stdout, and stderr as rotatelogs itself, and also inherits the environment.

-f

Causes the logfile to be opened immediately, as soon as rotatelogs starts, instead of waiting for the first logfile entry to be read (for non-busy sites, there may be a substantial delay between when the server is started and when the first request is handled, meaning that the associated logfile does not "exist" until then, which causes problems from some automated logging tools)

-D

Creates the parent directories of the path that the log file will be placed in if they do not already exist. This allows strftime(3) formatting to be used in the path and not just the filename.

-t

Causes the logfile to be truncated instead of rotated. This is useful when a log is processed in real time by a command like tail, and there is no need for archived data. No suffix will be added to the filename, however format strings containing '%' characters will be respected.

-T

Causes all but the initial logfile to be truncated when opened. This is useful when the format string contains something that will loop around, such as the day of the month. Available in 2.4.56 and later.

-v

Produce verbose output on STDERR. The output contains the result of the configuration parsing, and all file open and close actions.

-e

Echo logs through to stdout. Useful when logs need to be further processed in real time by a further tool in the chain.

-c

Create log file for each interval, even if empty.

-n number-of-files

Use a circular list of filenames without timestamps. This option overwrites log files at startup and during rotation. With -n 3, the series of log files opened would be "logfile", "logfile.1", "logfile.2", then overwriting "logfile". When this program first opens "logfile", the file will only be truncated if -t is also provided. Every subsequent rotation will always begin with truncation of the target file. For size based rotation without -t and existing log files in place, this option may result in unintuitive behavior such as initial log entries being sent to "logfile.1", and entries in "logfile.1" not being preserved even if later "logfile.n" have not yet been used. Available in 2.4.5 and later.

logfile

rotationtime

The time between log file rotations in seconds. The rotation occurs at the beginning of this interval. For example, if the rotation time is 3600, the log file will be rotated at the beginning of every hour; if the rotation time is 86400, the log file will be rotated every night at midnight. (If no data is logged during an interval, no file will be created.)

filesize(B|K|M|G)

The maximum file size in followed by exactly one of the letters B (Bytes), K (KBytes), M (MBytes) or G (GBytes). .PP When time and size are specified, the size must be given after the time. Rotation will occur whenever either time or size limits are reached.

offset

The number of minutes offset from UTC. If omitted, zero is assumed and UTC is used. For example, to use local time in the zone UTC -5 hours, specify a value of -300 for this argument. In most cases, -l should be used instead of specifying an offset.

## EXAMPLES

```

     CustomLog "|bin/rotatelogs /var/log/logfile 86400" common

```

This creates the files /var/log/logfile.nnnn where nnnn is the system time at which the log nominally starts (this time will always be a multiple of the rotation time, so you can synchronize cron scripts with it). At the end of each rotation time (here after 24 hours) a new log is started.

```

     CustomLog "|bin/rotatelogs -l /var/log/logfile.%Y.%m.%d 86400" common

```

This creates the files /var/log/logfile.yyyy.mm.dd where yyyy is the year, mm is the month, and dd is the day of the month. Logging will switch to a new file every day at midnight, local time.

```

     CustomLog "|bin/rotatelogs /var/log/logfile 5M" common

```

This configuration will rotate the logfile whenever it reaches a size of 5 megabytes.

```

     ErrorLog "|bin/rotatelogs /var/log/errorlog.%Y-%m-%d-%H_%M_%S 5M"

```

This configuration will rotate the error logfile whenever it reaches a size of 5 megabytes, and the suffix to the logfile name will be created of the form errorlog.YYYY-mm-dd-HH_MM_SS.

```

     CustomLog "|bin/rotatelogs -t /var/log/logfile 86400" common

```

This creates the file /var/log/logfile, truncating the file at startup and then truncating the file once per day. It is expected in this scenario that a separate process (such as tail) would process the file in real time.

```

     CustomLog "|bin/rotatelogs -T /var/log/logfile.%d 86400" common

```

If the server is started (or restarted) on the first of the month, this appends to /var/log/logfile.01. When a log entry is written on the second of the month, /var/log/logfile.02 is truncated and new entries will be added to the top. This example keeps approximately 1 months worth of logs without external maintenance.

## PORTABILITY
The following logfile format string substitutions should be supported by all strftime(3) implementations, see the strftime(3) man page for library-specific extensions.

• %A - full weekday name (localized)

• %a - 3-character weekday name (localized)

• %B - full month name (localized)

• %b - 3-character month name (localized)

• %c - date and time (localized)

• %d - 2-digit day of month

• %H - 2-digit hour (24 hour clock)

• %I - 2-digit hour (12 hour clock)

• %j - 3-digit day of year

• %M - 2-digit minute

• %m - 2-digit month

• %p - am/pm of 12 hour clock (localized)

• %S - 2-digit second

• %U - 2-digit week of year (Sunday first day of week)

• %W - 2-digit week of year (Monday first day of week)

• %w - 1-digit weekday (Sunday first day of week)

• %X - time (localized)

• %x - date (localized)

• %Y - 4-digit year

• %y - 2-digit year

• %Z - time zone name

• %% - literal `%'


htcacheclean

title: htcacheclean(8)

summary: Clean up the disk cache

text:
# htcacheclean(8)

## NAME
htcacheclean - Clean up the disk cache

## SYNOPSIS
htcacheclean [ -D ] [ -v ] [ -t ] [ -r ] [ -n ] [ -Rround ] -ppath [ -llimit ] [ -Llimit ]

htcacheclean [ -n ] [ -t ] [ -i ] [ -Ppidfile ] [ -Rround ] -dinterval -ppath [ -llimit ] [ -Llimit ]

htcacheclean [ -v ] [ -Rround ] -ppath [ -a ] [ -A ]

htcacheclean [ -D ] [ -v ] [ -t ] [ -Rround ] -ppath url

## SUMMARY
htcacheclean is used to keep the size of mod_cache_disk's storage within a given size limit, or limit on inodes in use. This tool can run either manually or in daemon mode. When running in daemon mode, it sleeps in the background and checks the cache directory at regular intervals for cached content to be removed. You can stop the daemon cleanly by sending it a TERM or INT signal. When run manually, a once off check of the cache directory is made for cached content to be removed. If one or more URLs are specified, each URL will be deleted from the cache, if present.

## OPTIONS
-dinterval

Daemonize and repeat cache cleaning every interval minutes. This option is mutually exclusive with the -D, -v and -r options. To shutdown the daemon cleanly, just send it a SIGTERM or SIGINT.

-D

Do a dry run and don't delete anything. This option is mutually exclusive with the -d option. When doing a dry run and deleting directories with -t, the inodes reported deleted in the stats cannot take into account the directories deleted, and will be marked as an estimate.

-v

Be verbose and print statistics. This option is mutually exclusive with the -d option.

-r

Clean thoroughly. This assumes that the Apache web server is not running (otherwise you may get garbage in the cache). This option is mutually exclusive with the -d option and implies the -t option.

-n

Be nice. This causes slower processing in favor of other processes. htcacheclean will sleep from time to time so that (a) the disk IO will be delayed and (b) the kernel can schedule other processes in the meantime.

-t

Delete all empty directories. By default only cache files are removed, however with some configurations the large number of directories created may require attention. If your configuration requires a very large number of directories, to the point that inode or file allocation table exhaustion may become an issue, use of this option is advised.

-ppath

Specify path as the root directory of the disk cache. This should be the same value as specified with the CacheRoot directive.

-Ppidfile

Specify pidfile as the name of the file to write the process ID to when daemonized.

-Rround

Specify round as the amount to round sizes up to, to compensate for disk block sizes. Set to the block size of the cache partition.

-llimit

Specify limit as the total disk cache size limit. The value is expressed in bytes by default (or attaching B to the number). Attach K for Kbytes, M for MBytes or G for Gbytes.

-Llimit

Specify limit as the total disk cache inode limit. K, M or G suffix can also be used.

-i

Be intelligent and run only when there was a modification of the disk cache. This option is only possible together with the -d option.

-a

List the URLs currently stored in the cache. Variants of the same URL will be listed once for each variant.

-A

List the URLs currently stored in the cache, along with their attributes in the following order: url, header size, body size, status, entity version, date, expiry, request time, response time, body present, head request.

## DELETING A SPECIFIC URL
If htcacheclean is passed one or more URLs, each URL will be deleted from the cache. If multiple variants of an URL exists, all variants would be deleted.

When a reverse proxied URL is to be deleted, the effective URL is constructed from the Host header, the port, the path and the query. Note the '?' in the URL must always be specified explicitly, whether a query string is present or not. For example, an attempt to delete the path / from the server localhost, the URL to delete would be http://localhost:80/?.

## LISTING URLS IN THE CACHE
By passing the -a or -A options to htcacheclean, the URLs within the cache will be listed as they are found, one URL per line. The -A option dumps the full cache entry after the URL, with fields in the following order:

url

The URL of the entry.

header size

The size of the header in bytes.

body size

The size of the body in bytes.

status

Status of the cached response.

entity version

The number of times this entry has been revalidated without being deleted.

date

Date of the response.

expiry

Expiry date of the response.

request time

Time of the start of the request.

response time

Time of the end of the request.

body present

If 0, no body is stored with this request, 1 otherwise.

head request

If 1, the entry contains a cached HEAD request with no body, 0 otherwise.

## EXIT STATUS
htcacheclean returns a zero status ("true") if all operations were successful, 1 otherwise. If an URL is specified, and the URL was cached and successfully removed, 0 is returned, 2 otherwise. If an error occurred during URL removal, 1 is returned.

## FILES
The cache root directory is specified as an argument on the command line and should match the CacheRoot directive in the server configuration.

path

The root directory of the disk cache to be cleaned.


suexec

title: suexec(8)

text:
# suexec(8)

## NAME
suexec - Switch user before executing external programs

## SYNOPSIS
suexec -V

## SUMMARY
suexec is used by the Apache HTTP Server to switch to another user before executing CGI programs. In order to achieve this, it must run as root. Since the HTTP daemon normally doesn't run as root, the suexec executable needs the setuid bit set and must be owned by root. It should never be writable for any other person than root.

For further information about the concepts and the security model of suexec please refer to the suexec documentation (http://httpd.apache.org/docs/2.4/suexec.html).

## OPTIONS
-V

If you are root, this option displays the compile options of suexec. For security reasons all configuration options are changeable only at compile time.


apachkconfig

package: apachkconfig

title: apachkconfig(8)

text:
# apachkconfig(8)

## NAME
apachkconfig - updates and queries addons config information for different Apache favours

## SYNOPSIS
apachkconfig --list [name]

apachkconfig --add name

apachkconfig --del name

apachkconfig [--favour|--level favours] name <on|off|reset>

apachkconfig [--favour|--level favours] name

## DESCRIPTION
apachkconfig provides a simple command-line tool for maintaining the apache addon configuration (e.g /etc/httpd*/addon.d) directories by relieving system administrators of the task of directly manipulating the numerous symbolic links in those directories.

This implementation (as well as this man page) of apachkconfig was inspired by the chkconfig command used for manipulating SYSV services.

apachkconfig has five distinct functions: adding new addon for management, removing addons from management, listing the current startup information for addons, changing the startup information for addons, and checking the startup state of a particular addon.

When apachkconfig is run without any options, it displays usage information. If only an addon name is given, it checks to see if the service is configured to be loaded by the default apache favour. If it is, apachkconfig returns true; otherwise it returns false. The --favour option may be used to have apachkconfig query an alternative favour rather than the default one.

If one of on, off, or reset is specified after the addon name, apachkconfig changes the startup information for the specified addon. The on and off flags cause the addon to be loaded or ignored, respectively, by the apache favour being changed. The reset flag resets the startup information for the addon to whatever is specified in the config file in question.

By default, the on, off and reset options affect all of the apache favours installed. The --favour option may be used to specify which favours are affected.

## OPTIONS
--favour favours

Specifies the apache favours an operation should pertain to. It is given as an alpha-numeric string. For example, --favour 1p2 specifies favours 1 (Apache-13), p (Apache13-mod_perl) and 2 (Apache2).

--add name

This option adds a new addon for management by apachkconfig. When a new addon is added, apachkconfig ensures that the service has an activate entry in every favour. If any apache favour is missing such an entry, chkconfig creates the appropriate entry as specified by the default values in the addon config file.

--del name

The addon is removed from apachkconfig management, and any symbolic links in apache addon config directories (e.g /etc/httpd*/addon.d) which pertain to it are removed.

--list name

This option lists all of the addons which apachkconfig knows about, and whether they are loaded or ignored by each apache favour. If name is specified, information is only displayed about addon name.

## FAVOUR FILES
Each addon which should be manageable by apachkconfig needs two or more commented lines added to its config file. The first line tells apachkconfig for what favours the addon should be loaded by default, as well as the load priority level and optionally favour restriction list. If the addon should not, by default, be loaded in any favours, a - should be used in place of the favours list. If the addon should never be loaded by any other apache favour, exept some exactly named, add the list of restricted favours after the priority level. The second line contains a description for the service, and may be extended across multiple lines with backslash continuation.

For example, awstats.conf has these three lines:

```
# apachkconfig: 1p2 50
# description: Real-time logfile analyzer to get advanced web statistics \

               AWStats is a short for Advanced Web Statistics. It's a free \
	       tool that generates advanced web (but also ftp, syslog or \
	       mail) server access statistics graphically.
```

This says that the awstats CGI script config should be loaded by apache favours 1, p, and 2, that its start priority should be 50, 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. Second example, webauth.conf make sense only for Apache2:

```
# apachkconfig: - 12 2
# description: A WebAuth (GSS-API) authentication module for Apache2
```

This says that the webauth module config could be loaded only by apache favour 2, that its start priority should be 12 and that it should be disabled by default.

## SEE ALSO
chkconfig(8) httpd(8)

## AUTHOR

```
Yury Konovalov <yurix@altlinux.org>
```


apcaccess

package: apcupsd

title: apcaccess(8)

text:
# apcaccess(8)

## NAME
apcaccess — retrieve status information from apcupsd(8)

## SYNOPSIS
apcaccess

[-f <config-file>] [-h <host>[:<port>]] [-p <parameter-name>] [-u] [<command>] [<host>[:<port>]]

## DESCRIPTION
apcaccess is a program which prints out the complete status of most American Power Conversion Corp. (APC) UPSes provided you have the apcupsd(8) daemon installed, properly configured and running. It can access status information from any APC UPS attached to the localhost or attached to any computer on the network which is running apcuspd in NIS mode.

The command line options are:

-f

configuration file of apcupsd (default is usually /etc/apcupsd/apcupsd.conf)

-h

hostname and port of apcupsd to communicate with. The default hostname and port are obtained from the configuration file.

-p

Report only the value of the named parameter instead of all parameters and values.

-u

Remove units field for easier parsing by scripts.

<command>

An optional command, unless a hostname is also being specified. The only implemented command is status Shorthand for status localhost:3551. This produces a full printout of the available status information for the associated UPS.

<host>

An optional hostname which may be a bare machine name, fully qualified domain name or IP address.

:<port>

An optional port number where a hostname argument has been specified. The default is 3551, the official port number assigned by IANA for the apcupsd NIS server. The default hostname and port are obtained from the configuration file.

apcaccess uses apcupsd's inbuilt Network Information Server (NIS) -- no relation to Sun's NIS/YP service -- to obtain the current status information from the UPS on the local or remote computer. It is therefore necessary to have the following configuration directives:

-

NETSERVER on

-

NISPORT 3551

in the /etc/apcupsd/apcupsd.conf configuration file so that the Network Information Server will be accessible. Firewall rules for appropriate network access may also be needed.

## STATUS REPORT FORMAT
The status report output format is simple ASCII. Generally there is a single piece of information on each line of output. The content varies based on the model of UPS being used and, in some cases, the firmware version.

## EXAMPLES
Set out below is a sample of the status output which may be generated for the specified UPS models.

### All models
APC

: version, number of records and number of bytes following

DATE

: Date and time of last update from UPS

HOSTNAME

: hostname of computer running apcupsd

VERSION

: apcupsd version number, date and operating system

UPSNAME

: UPS name from configuration file (dumb) or EEPROM (smart)

CABLE

: Cable type specified in the configuration file

MODEL

: UPS model derived from UPS information

UPSMODE

: Mode in which UPS is operating

STARTTIME

: Date and time apcupsd was started

STATUS

: UPS status. One or more of the following (space-separated): CAL TRIM BOOST ONLINE ONBATT OVERLOAD LOWBATT REPLACEBATT NOBATT SLAVE SLAVEDOWN

or

COMMLOST

or

SHUTTING DOWN

MASTERUPD

: Last time the master sent an update to the slave

ENDAPC

: Date and time of status information was written

### Smart-UPS and Matrix-UPS (Smart Signalling)
LINEV

: Current input line voltage

LOADPCT

: Percentage of UPS load capacity used as estimated by UPS

BCHARGE

: Current battery capacity charge percentage

TIMELEFT

: Remaining runtime left on battery as estimated by the UPS

MBATTCHG

: Min battery charge % (BCHARGE) required for system shutdown

MINTIMEL

: Min battery runtime (MINUTES) required for system shutdown

MAXTIME

: Max battery runtime (TIMEOUT) after which system is shutdown

MAXLINEV

: Maximum input line voltage since apcupsd started

MINLINEV

: Min (observed) input line voltage since apcupsd started

OUTPUTV

: Current UPS output voltage

SENSE

: Current UPS sensitivity setting for voltage fluctuations

DWAKE

: Time UPS waits after power off when the power is restored

DSHUTD

: Delay before UPS powers down after command received

DLOWBATT

: Low battery signal sent when this much runtime remains

LOTRANS

: Input line voltage below which UPS will switch to battery

HITRANS

: Input line voltage above which UPS will switch to battery

RETPCT

: Battery charge % required after power off to restore power

ITEMP

: UPS internal temperature in degrees Celcius

ALARMDEL

: Delay period before UPS starts sounding alarm

BATTV

: Current battery voltage

LINEFREQ

: Current line frequency in Hertz

LASTXFER

: Reason for last transfer to battery since apcupsd startup

NUMXFERS

: Number of transfers to battery since apcupsd startup

XONBATT

: Date, time of last transfer to battery since apcupsd startup

TONBATT

: Seconds currently on battery

CUMONBATT

: Cumulative seconds on battery since apcupsd startup

XOFFBAT

: Date, time of last transfer off battery since apcupsd startup

SELFTEST

: Date and time of last self test since apcupsd startup

STESTI

: Self-test interval

STATFLAG

: UPS status flag in hex

DIPSW

: Current UPS DIP switch settings

REG1

: Fault register 1 in hex

REG2

: Fault register 2 in hex

REG3

: Fault register 3 in hex

MANDATE

: UPS date of manufacture

SERIALNO

: UPS serial number

BATTDATE

: Date battery last replaced (if set)

NOMOUTV

: Nominal output voltage to supply when on battery power

NOMBATTV

: Nominal battery voltage

EXTBATTS

: Number of external batteries (for XL models)

BADBATTS

: Number of bad external battery packs (for XL models)

FIRMWARE

: UPS firmware version

APCMODEL

: APC model information

### Newer Back-UPS Pro (Smart Signalling)
LINEV

: Current input line voltage

LOADPCT

: Percentage of UPS load capacity used

MBATTCHG

: Min battery charge % (BCHARGE) required for system shutdown

MINTIMEL

: Min battery runtime (MINUTES) required for system shutdown

MAXTIME

: Max battery runtime (TIMEOUT) after which system is shutdown

MAXLINEV

: Maximum input line voltage since apcupsd startup

MINLINEV

: Minimum input line voltage since apcupsd startup

OUTPUTV

: Current UPS output voltage

BATTV

: Current battery charge voltage

STATFLAG

: UPS status flag in hex

### Back-UPS RS 1500 (USB)
LINEV

: Current input line voltage

LOADPCT

: Percentage of UPS load capacity used

BCHARGE

: Current battery capacity charge percentage

TIMELEFT

: Remaining runtime left on battery as estimated by UPS

MBATTCHG

: Min battery charge % (BCHARGE) required for system shutdown

MINTIMEL

: Min battery runtime (MINUTES) required for system shutdown

MAXTIME

: Max battery runtime (TIMEOUT) after which system is shutdown

*OUTPUTV

: Current UPS output voltage

*DWAKE

: Time UPS waits after power off when the power is restored

*DSHUTD

: Delay before UPS powers down after command received

LOTRANS

: Input line voltage below which UPS will switch to battery

HITRANS

: Input line voltage above which UPS will switch to battery

*RETPCT

: Battery charge % required after power off to restore power

*ITEMP

: UPS internal temperature in degrees Celcius

ALARMDEL

: Delay period before UPS starts sounding alarm

BATTV

: Current battery voltage

*LINEFREQ

: Current line frequency in Hertz

*LASTXFER

: Reason for last transfer to battery since apcupsd startup

NUMXFERS

: Number of transfers to battery since apcupsd startup

XONBATT

: Date, time of last transfer to battery since apcupsd startup

TONBATT

: Seconds currently on battery

CUMONBATT

: Cumulative seconds on battery since apcupsd startup

XOFFBAT

: Date, time of last transfer off battery since apcupsd startup

SELFTEST

: Date and time of last self test since apcupsd startup

STATFLAG

: UPS status flag in hex

MANDATE

: UPS date of manufacture

SERIALNO

: UPS serial number

BATTDATE

: Date battery last replaced (if set)

NOMBATTV

: Nominal battery voltage

FIRMWARE

: UPS firmware version

APCMODEL

: APC model information

* presence dependant on USB firmware version.

### Web/SNMP (AP9716) or PowerNet SNMP (AP9605) SmartSlot Card
LINEV

: Current input line voltage

LOADPCT

: Percentage of UPS load capacity used as estimated by UPS

BCHARGE

: Current battery capacity charge percentage

TIMELEFT

: Remaining runtime left on battery as estimated by UPS

MBATTCHG

: Min battery charge % (BCHARGE) required for system shutdown

MINTIMEL

: Min battery runtime (MINUTES) required for system shutdown

MAXTIME

: Max battery runtime (TIMEOUT) after which system is shutdown

MAXLINEV

: Maximum input line voltage since apcupsd startup

MINLINEV

: Minimum input line voltage since apcupsd startup

OUTPUTV

: UPS output voltage

SENSE

: Current UPS sensitivity setting for voltage fluctuations

DWAKE

: Time UPS waits after power off when the power is restored

DSHUTD

: Delay before UPS powers down after command received

DLOWBATT

: Low battery signal sent when this much runtime remains

LOTRANS

: Input line voltage below which UPS will switch to battery

HITRANS

: Input line voltage above which UPS will switch to battery

RETPCT

: Battery charge % required after power off to restore power

ITEMP

: UPS internal temperature in degrees Celcius

ALARMDEL

: Delay period before UPS starts sounding alarm

LINEFREQ

: Current line frequency in Hertz

NUMXFERS

: Number of transfers to battery since apcupsd startup

TONBATT

: Seconds currently on battery

CUMONBATT

: Cumulative seconds on battery since apcupsd startup

XOFFBATT

: Date, time of last transfer off battery since apcupsd startup

STESTI

: Self-test interval

STATFLAG

: UPS status flag in hex

DIPSW

: Current UPS DIP switch settings

MANDATE

: UPS date of manufacture

SERIALNO

: UPS serial number

BATTDATE

: Date battery last replaced (if set)

NOMOUTV

: Nominal output voltage to supply when on battery power

NOMPOWER

: Nominal power output in watts

EXTBATTS

: Number of external batteries (for XL models)

BADBATTS

: Number of bad external battery packs (for XL models)

FIRMWARE

: UPS firmware version

APCMODEL

: APC model information

### Share-UPS (AP9270) (Basic port)
MBATTCHG

: Min battery charge % (BCHARGE) required for system shutdown

MINTIMEL

: Min battery runtime (MINUTES) required for system shutdown

MAXTIME

: Max battery runtime (TIMEOUT) after which system is shutdown

NUMXFERS

: Number of transfers to battery since apcupsd startup

TONBATT

: Seconds currently on battery

CUMONBATT

: Cumulative seconds on battery since apcupsd startup

XOFFBATT

: Date, time of last transfer off battery since apcupsd startup

STATFLAG

: UPS status flag in hex

### UPS Environmental Monitoring SmartSlot Card (AP9612TH)
HUMIDITY

: Ambient humidity

AMBTEMP

: Ambient temperature

### Back-UPS Pro and Smart-UPS v/s (Smart Signalling)
LINEFAIL

: Input line voltage status.

BATTSTAT

: Battery status.

LASTXFER

: Last (observed) transfer to battery.

### Back-UPS and Net-UPS (Simple Signalling)
LINEFAIL

: Input line voltage status.

BATTSTAT

: Battery status.

STATFLAG

: UPS status flag in hex.

## FILES
/etc/apcupsd/apcupsd.conf

## SEE ALSO
apcupsd.conf(5), apcupsd(8).

The HTML apcupsd manual installed on your system or available online at http://www.apcupsd.org/

## AUTHORS

### This page
Trevor Roydhouse

### Software

Adam Kropelin (current Project Manager and Code Maintainer)

Kern Sibbald (former Project Manager and Code Maintainer)

Riccardo Facchetti (former Project Manager and Code Maintainer)

Andre M. Hedrick (Project Founder and former Code Maintainer)

### Contributors
An enormous number of users who have devoted their time and energy to this project -- thanks.


apccontrol

title: apccontrol(8)

summary: apcupsd(8) event handler script

text:
# apccontrol(8)

## NAME
apccontrol — apcupsd(8) event handler script

## SYNOPSIS
apccontrol

{ <event> <ups-name> <connected> <powered> }

## DESCRIPTION
When apcupsd(8) detects anomalies from the UPS being monitored, it triggers an event which usually results in one or more calls to the apccontrol shell script. Each event causes apccontrol to take a particular action. These actions default to sane behaviour for all the events that apcupsd is likely to encounter. However, you can change the behaviour of every single action.

When apcupsd detects an event, it calls the apccontrol script with the following four arguments:

event

This is the event that occurred. Refer to the list of possible events below.

ups-name

This is the name of the UPS as specified in the /etc/apcupsd/apcupsd.conf configuration file - not the name in the EEPROM of a smart UPS.

connected

This is 1 if apcupsd is connected to the UPS via a serial or USB port. In the case of a slave machine where apcupsd is not directly connected to the UPS, this value will be 0.

powered

This is 1 if the computer on which apcupsd is running is powered by the UPS and 0 if not. This is not currently implemented and always defaults to 0.

Events are sent to the system log and, optionally, to the temporary events file (/etc/apcupsd/apcupsd.events), and they also generate a call to apccontrol which in turn will call any scripts you have placed in the /etc/apcupsd directory.

### LIST OF EVENTS AND DEFAULT ACTIONS
annoyme

apcupsd generates this event when a shutdown is scheduled, and the time specified by the ANNOYME configuration directive in the /etc/apcupsd/apcupsd.conf file has expired. Default action -- sends "Power problems please logoff." to wall(1) and then exits.

battattach

apcupsd generates this event when it detects that the UPS battery has been reconnected after a battdetach event. Default action: does nothing.

battdetach

apcupsd generates this event when it detects that the UPS battery has been disconnected. Default action: does nothing.

changeme

apcupsd generates this event when it detects that the utility power is on, but the battery is not functioning correctly. This is repeated every 9 hours. Default action -- sends "Emergency! UPS batteries have failed Change them NOW" to wall and then exits.

commfailure

apcupsd generates this event each time it loses communication with the monitored UPS. This event is not detected on simple signalling UPSes like the Back-UPS 650. Default action -- sends "Communications with UPS lost." to wall and then exits.

commok

apcupsd generates this event after a commfailure event when communication with the UPS is re-established. Default action -- sends "Communications with UPS restored." to wall and then exits.

doreboot

This event is deprecated and should not be used. Default action -- sends "Beginning Reboot Sequence" to wall and then calls shutdown(8) with the "-r now" command line arguments to reboot the computer.

doshutdown

apcupsd generates this event to shutdown the computer when the UPS is running on battery power and one of the limits (time, run, load) is reached. Default action -- sends "Beginning Shutdown Sequence" to wall and then calls shutdown(8) with the command line arguments "-h now" to shutdown the computer.

emergency

apcupsd generates this event when the UPS is on battery power, the battery is low and the utility power is on: a sure sign of battery failure! Default action -- sends "Emergency Shutdown. Possible UPS battery failure." to wall. Immediately after this, apcupsd generates a doshutdown event to shutdown the system.

failing

apcupsd generates this event when the UPS is running on batteries and the UPS sets the low battery signal indicating that battery power is nearly exhausted. After this event, apcupsd will immediately generate a doshutdown event. Default action -- sends "UPS battery power exhausted. Doing shutdown." to wall and then exits.

killpower

apcupsd does not normally generate this event. Instead, it is invoked directly from the system halt script as 'apccontrol killpower' because the killpower event needs to be performed as late in system shutdown as possible. Default action -- sends "UPS now committed to shut down" to wall, waits for 10 seconds and then issues the command "apcupsd --killpower" to put the UPS into hibernate mode and shut off power to the connected equipment. In the case of a smart UPS, the UPS will then wait for the expiry of any configured shutdown time delay specified by the SLEEP configuration directive. In hibernate mode, the UPS will restore utility power to the connected equipment subject to the values specified for the RETURNCHARGE and WAKEUP configuration directives.

loadlimit

apcupsd generates this event when the battery discharge limit specified by the BATTERYLEVEL configuration directive has been reached. Default action -- sends "UPS battery discharge limit reached. Doing shutdown" to wall and then exits. After this event, apcupsd will immediately generate a doshutdown event.

mainsback

apcupsd generates this event when the utility power returns after a powerout event. The doshutdown event may or may not have been generated depending on the parameters you have defined and the length of the power outage. Attempting cancellation of a doshutdown event should never be tried as it is very unlikely to succeed and will almost certainly leave your computer in an indeterminate state. Default action -- if the file /var/run/powerfail exists, sends "Continuing with shutdown." to wall and then exits. Otherwise, does nothing.

onbattery

apcupsd generates this event if a power failure has been detected and the UPS is still on battery power at the expiry of the delay specified by the ONBATTERYDELAY configuration directive. Default action -- sends "Power failure. Running on UPS batteries." to wall and then exits.

offbattery

apcupsd generates this event when the utility power returns if, and only if, the onbattery event has been generated. Default -- sends ""Power has returned..." to wall and then exits.

powerout

apcupsd generates this event as soon as apcupsd detects that the UPS has switched to battery power and it is not a self-test. Default action -- does nothing.

remotedown

apcupsd generates this event on a slave machine when it detects either (1) that the master has shutdown, or (2) that an onbattery event has occurred and communication with the master has been lost. Default action: sends "Remote Shutdown. Beginning Shutdown Sequence." to wall and exits. Immediately after this, apcupsd generates a doshutdown event to shutdown the system.

runlimit

apcupsd generates this event when the remaining runtime limit specified by the MINUTES configuration directive expires while the UPS is on battery power as the result of a utility power outage. The remaining runtime is internally calculated by the UPS and monitored by apcuspd. Default action -- sends "UPS battery runtime percent reached. Doing shutdown." to wall and then exits. After this event, apcupsd will immediately generate a doshutdown event.

timeout

apcupsd generates this event when the time specified by the TIMEOUT configuration directive expires while the UPS is on battery power as the result of a utility power outage. This configuration directive is not normally used with smart UPSes which would instead rely on the more reliable remaining runtime (MINUTES) or the battery level (BATTERYLEVEL) configuration directives. Default action -- send "UPS battery runtime limit exceeded. Doing shutdown." to wall and then exits. After this event, apcupsd will immediately generate a doshutdown event.

startselftest

apcupsd generates this event when it detects the start of a UPS self test. Default action: does nothing.

endselftest

apcupsd generates this event when it detects the end of a UPS self test. Default action: does nothing.

### CUSTOMISING EVENT ACTIONS
Do not modify apccontrol directly as it will be overwritten the next time you upgrade to a new release of apcupsd.

The recommended way to customise an event action is simply to create an executable program or script file with the same name as the event and put that file in the /etc/apcupsd directory. Now, when the selected event occurs, apccontrol will execute your program or script.

If you want apccontrol to also execute its default action for the selected event, your program or script should exit with an exit status of 0 (zero).

If you do not want apccontrol to also execute its default action for the selected event, your program or script must exit with an exit status of 99. Be aware that if you completely override the default action, you must ensure the proper shutdown of your computer if this is necessary.

Some sample scripts (changeme, commfailure, commok, offbattery and onbattery) that email messages to root instead of broadcasting messages to all logged-in users may be found in /etc/apcupsd after an installation and also in the platforms/etc directory of the apcupsd source code.

## FILES
/etc/apcupsd/apccontrol

## SEE ALSO
wall(1), apcupsd.conf(5), apcupsd(8), shutdown(8).

The HTML apcupsd manual installed on your system or available online at http://www.apcupsd.org/

## AUTHORS

### This page
Trevor Roydhouse

### Software

Adam Kropelin (current Project Manager and Code Maintainer)

Kern Sibbald (former Project Manager and Code Maintainer)

Riccardo Facchetti (former Project Manager and Code Maintainer)

Andre M. Hedrick (Project Founder and former Code Maintainer)

### Contributors
An enormous number of users who have devoted their time and energy to this project -- thanks.