archiveopteryx

title: archiveopteryx(8)

text:
# archiveopteryx(8)

## NAME
Overview of Archiveopteryx.

## SYNOPSIS
/etc/init.d/archiveopteryx {start,stop}

/etc/archiveopteryx/*.conf

## DESCRIPTION
Archiveopteryx is a mail server system optimised for long-term storage and heavy access. It comprises a set of server programs that provide access to mail stored in a relational database (PostgreSQL).

## GETTING STARTED
The following five steps should suffice to install Archiveopteryx. If they don't, or if anything is unclear, more detailed instructions are available at http://archiveopteryx.org/installation

### 1. Install Archiveopteryx
Usually, this is as simple as:

apt-get install archiveopteryx (on Debian)

portinstall archiveopteryx (on FreeBSD)

http://archiveopteryx.org/installation explains what to do in other cases.

Use

/usr/lib64/archiveopteryx/archiveopteryx start

to start Archiveopteryx using the default configuration from archiveopteryx.conf, which tries hard to be sensible.

### 2. Add a user
Run

aox add user name password address@domain

to create a username and password.

### 3. Inject some test mail
You can use deliver(8) to inject some mail you already have.

This command injects all the messages from a berkeley mbox file:

formail -s deliver yourname@domain < mbox

### 4. Check that you can read mail
The mail you just delivered is in your inbox, and you can read it with any IMAP or POP3 client.

### 5. Configure your MTA
The normal way to deliver mail from your MTA into Archiveopteryx is via LMTP. By default, Archiveopteryx listens on 127.0.0.1 port 2026.

On aox.org we describe how to configure some common MTAs to work with Archiveopteryx. See e.g. http://archiveopteryx.org/postfix for postfix(1).

## ARCHITECTURE
Archiveopteryx consists of a number of frontend servers, each of which uses backend servers:

RDBMS

The RDBMS is where all the mail is stored. At present only PostgreSQL is supported.

logd

The log server is an internal server which filters log entries so useful messages are logged while noise is suppressed.

Each server is described more fully in its own man page: logd(8), postgres(1) and archiveopteryx(8) for the frontend server, which serves IMAP, POP3, LMTP and/or SMTP and perhaps webmail.

Normally, there is one logd(8) process running. In addition there will be at least one postgres(1) and one archiveopteryx(8) process.

The servers use TCP to communicate internally, so they can be distributed across a server cluster. Generally, one host will run the database backend, one host (perhaps the same) will run logd(8) and as many as required will run frontends.

The man pages for each server explain the use and configuration of each. See archiveopteryx.conf(5) for more about configuring Archiveopteryx in general.

## SECURITY
All Archiveopteryx servers run in chroot directories.

The user-facing servers run in a special jail directory. They have neither read nor write access to this directory.

logd(8) runs chrooted to another directories. All of the servers close all open files at startup and drop root privileges. By default they run as user aox, group aox, although these names can be changed using archiveopteryx.conf(5).

The servers check that they lose prvileges as expected, and refuse to start if they're too privileged.

Note that logd(8) must have permission to create the logfile.

## MAIL STORAGE
Archiveopteryx does not store mail in the RFC-822 format. It parses each message upon delivery, and stores a normalized representation, optimized for fast and reliable search and categorization.

This offers the following advantages, among others:

Performance

One example: Each address is stored exactly once, as Unicode and with RFC-2047 encoding undone. Finding all messages sent from/to a given name is extremely fast, because only a single SQL SELECT is necessary, and it accesses just two small tables.

Long-term Stability

Archiveopteryx handles today's common syntax problems and stores the correct form in the database. Because of that, the mail reader which looks at old mail in the year 2020 will not need to be bug compatible with today's version of Microsoft Outlook.

Scalability and Flexibility

Only the database size limits Archiveopteryx's capacity. Many other servers limit individual folders to 2GB (or less), or cannot support more than a few thousand subfolders/messages in a folder. With Archiveopteryx, you don't need to invent workarounds for such artificial limitations.

Robustness

Because mail is stored normalized and parsed, large attachments are generally stored only once, and mail parsing exploits are rendered harmless before reaching the MUA. A movie clip sent to a hundred recipients is not a problem, because it's stored just once.

## LICENSING
Archiveopteryx is available under two licences, namely the OSL 3.0 license and a commercial software license.

The OSL 3.0 (see http://archiveopteryx.org/opensource) is a fairly restrictive open source license similar to the more well-known GNU licenses. It includes a disclaimer of responsibility.

Our commercial license offers more flexibility than the OSL and a full warranty. There are also extra services. Contact info@aox.org for more details, or see http://archiveopteryx.org/commercial

## DEFAULTS
The configurable file and directory names in this build are as follows:

SBINDIR

(where servers live) is /usr/sbin.

BINDIR

(where other executables live) is /usr/bin.

INITDIR

(where the startup script lives) is /usr/lib64/archiveopteryx.

MANDIR

(where manpages live) is /usr/share/man.

PIDFILEDIR

(where pidfiles live) is /var/run.

LIBDIR

(where supporting files live) is /usr/lib64/archiveopteryx.

JAILDIR

(the working directory of the user-facing servers) is /var/lib/archiveopteryx, and can be overridden using the jail-directory variable in archiveopteryx.conf(5).

CONFIGDIR

(where the configuration files live) is /etc/archiveopteryx.

LOGFILE

(the full name of the logfile) is syslog/mail, and can be overridden using the logfile variable in archiveopteryx.conf(5).

These variables can be changed only by editing the file Jamsettings and recompiling Archiveopteryx. Jamsettings also contains some variables used only during compilation and/or installation, and some which provide defaults for archiveopteryx.conf(5) settings.

## FILES
/etc/archiveopteryx/archiveopteryx.conf

contains the Archiveopteryx configuration.

/usr/lib64/archiveopteryx/automatic-key.pem

contains a private key and self-signed certificate used by openssl(3).

## AUTHOR
The Archiveopteryx Developers, info@aox.org.

## VERSION
This man page covers Archiveopteryx version 3.1.3, released 2010-03-10, http://archiveopteryx.org/3.1.3

## SEE ALSO
archiveopteryx(8), archiveopteryx.conf(5), deliver(8), logd(8), http://archiveopteryx.org


deliver

package: archiveopteryx

title: deliver(8)

text:
# deliver(8)

## NAME
deliver - deliver mail into Archiveopteryx.

## SYNOPSIS
/usr/bin/deliver [-f sender] [-t mailbox] [-v] destination [filename]

## DESCRIPTION
The deliver program injects a single mail message in RFC-822 format into Archiveopteryx. It connects to Archiveopteryx's backend ddatabase injects the message into the correct mailbox.

deliver is meant as a compatibility shim for use with e.g. formail(1) and with MTAs that want to deliver to a program. Note that you will generally get better performance by using LMTP.

deliver bypasses Sieve and always stores mail directly into the target mailbox.

## OPTIONS
-f sender

specifies the fully qualified address of the message sender. This is the same as the SMTP envelope sender.

Starting with version 2.01, the -f argument is ignored. It is still accepted to keep old scripts working.

-t mailbox

directs deliver to store the message into the named mailbox. The "p" right on the mailbox must be granted to "anyone". ("p" controls who is permitted to send mail to the mailbox, see RFC 4314 for more details.)

-v

requests more verbosity during delivery. May be specified twice.

## EXAMPLES
To deliver an entire berkeley mbox into the inbox of user nirmala@example.com:

formail -s deliver nirmala@example.com < mbox

To deliver each message in the MH folder +blah into the inbox of user raj@example.net:

folder +blah

seq all | xargs -n1 deliver raj@example.net

To deliver each message in the MH folder +ramble into folder stumble of user raj@example.net:

folder +blah

seq all | xargs -n1 deliver -t stumble raj@example.net

If raj has not granted "anyone" the "p" right ("p"ost mail to mailbox), this example fails.

## DIAGNOSTICS
The normal exit status of deliver is 0. In case of errors, deliver returns an error code from sysexits.h, such as EX_TEMPFAIL, EX_NOUSER, etc.

## BUGS
Delivering multiple messages would also be good, for those big mailbox migrations. In that case, deliver should report which messages could be delivered and which could not.

There is no command-line option to set the configuration file.

## AUTHOR
The Archiveopteryx Developers, info@aox.org.

## VERSION
This man page covers Archiveopteryx version 3.1.3, released 2010-03-10, http://archiveopteryx.org/3.1.3

## SEE ALSO
archiveopteryx(8), archiveopteryx.conf(5), logd(8), http://archiveopteryx.org


installer

title: installer(8)

text:
# installer(8)

## NAME
installer - Archiveopteryx installer.

## SYNOPSIS
/usr/lib64/archiveopteryx/installer [ -n ] [ -q ] [ -v ] ...

## DESCRIPTION
This program does the following:

1. Creates a Unix group named aox.

2. Creates a Unix user named aox.

3. Creates a Postgres user named aox.

4. Creates a Postgres user named aoxsuper.

5. Creates a Postgres database named archiveopteryx owned by aoxsuper.

6. Loads the database schema and grants limited privileges to user aox.

7. Generates an initial configuration file.

8. Adjusts ownership and permissions if necessary.

installer should be run after jam install when installing from source.

By default, the address of the PostgreSQL server is derived from the compile-time DBADDRESS setting in the Jamsettings file (which is 127.0.0.1 by default). If the db-address variable is set in an existing configuration file, that value takes precedence. If the -a command-line flag is used, then the address specified has precedence over either of the former values.

If the server address (as determined above) is 127.0.0.1, the installer will try to use a Unix domain socket to connect to the server. The location of this socket is determined by the -s socket command-line argument. If no socket is specified, the default named socket location ( /tmp/.s.PGSQL.5432) is used instead. For any other server address, the installer will try to use a Unix domain socket only if one is explicitly specified with -s. In any case, if password authentication is to be used when talking to the server, the -P option will cause the installer to prompt for the password.

## OPTIONS
-q

Suppresses all normal output.

-v

Makes the output more verbose (may be repeated).

-n

Causes the program to report what it would do, but not actually do anything.

-g group

Allows you to specify a Unix group other than the default of aox.

-u user

Allows you to specify a Unix username other than the default of aox.

-p postgres

Allows you to specify the name of the PostgreSQL superuser. The default is to try $PGUSER (if set), postgres and pgsql in turn.

-P

Instructs the installer to prompt for and read the PostgreSQL superuser's password, and be prepared to use that for authentication (if necessary).

-a address

Allows you to specify a different address for the Postgres server. The default is 127.0.0.1.

-s /path/to/socket

Allows you to specify a location for the PostgreSQL server's Unix-domain listening socket. The specified value is used as described above.

-t port

Allows you to specify a different port for the Postgres server. The default is 5432. (This value is used only if the server address does not refer to a Unix socket.)

-d dbname

Allows you to specify a database to use. The default is archiveopteryx.

-S schema

Allows you to specify a schema where the Archiveopteryx database objects will be installed. If this is not specified, objects are installed into the public schema.

Please do not use -S unless you are sure you understand all its implications. It is safe to ignore it entirely if you don't.

The defaults come from Jamsettings.

## DIAGNOSTICS
The return code is zero if all goes well, and a non-zero in case of errors. Disasters are logged via stderr.

## AUTHOR
The Archiveopteryx Developers, info@aox.org.

## VERSION
This man page covers Archiveopteryx version 3.1.3, released 2010-03-10, http://archiveopteryx.org/3.1.3

## SEE ALSO
archiveopteryx(8), archiveopteryx.conf(5), logd(8), http://archiveopteryx.org


logd

title: logd(8)

text:
# logd(8)

## NAME
logd - logging server for Archiveopteryx.

## SYNOPSIS
/usr/sbin/logd [-f] [-c configfile]

## DESCRIPTION
The Archiveopteryx logd is an internal server which receives, buffers and filters log entries from other parts of Archiveopteryx, so that useful messages are logged, while noise is suppressed.

Archiveopteryx's log system uses four log levels: Disaster, Error, Info and Debug. Each program in Archiveopteryx sends its log messages to logd, which writes them to a logfile.

If a message is logged with severity log-level (set to Info by default) or greater, it is immediately written to the log file. All messages of lower severity are discarded.

If logd receives the SIGHUP signal, it closes and reopens its logfile.

After startup, logd changes root to the directory where logfile is located, and changes uid and gid to jail-user and jail-group. Therefore, jail-user must have the right to open logfile.

## OPTIONS
-c filename

Read configuration variables from filename instead of from /etc/archiveopteryx/archiveopteryx.conf.

-f

Fork into background during startup.

## CONFIGURATION
logd is configured using archiveopteryx.conf(5).

logd uses the following configuration variables: log-address, log-port, logfile (default syslog/mail), log-level (default info), jail-user (default aox), jail-group (default aox).

## DIAGNOSTICS
In case of error, smtpd exits with exit code 1, an error message on stderr and (usually more detailed) information in the log file.

## FILES
/etc/archiveopteryx/archiveopteryx.conf

/usr/sbin/logd

## AUTHOR
The Archiveopteryx Developers, info@aox.org.

## VERSION
This man page covers Archiveopteryx version 3.1.3, released 2010-03-10, http://archiveopteryx.org/3.1.3

## SEE ALSO
archiveopteryx(8), archiveopteryx.conf(5), deliver(8), aox(8), http://archiveopteryx.org


recorder

title: recorder(8)

text:
# recorder(8)

## NAME
recorder - IMAP connection recorder

## SYNOPSIS
/usr/sbin/recorder srcport address destport file

## DESCRIPTION
The recorder program relays data between an IMAP client and server, and records the session in a format which allows the Archiveopteryx developers to replay and analyse it later.

If you have problems getting archiveopteryx(8) to work with a particular IMAP client, you can make the client connect to the recorder, instead of directly to imapd, and recorder will produce a transcript of the IMAP session. If the client opens more than one connection, recorder stores more than one file.

The file format is pure ASCII and can be edited. We suggest that you edit out your password, then send the rest to info@aox.org and we may be able to find out what's happening.

We have debug tools that can replay the connection, so we can fix any bugs on the server's side. In some cases, we can also add the file to our regression tests, so we can be sure that new versions of archiveopteryx(8) do not have the same error.

## EXAMPLE
To intercept and record traffic to the IMAP server on 192.0.2.17 and place a record of the connections in files called /tmp/bugreport* you can do the following:

### Disable TLS
recorder does not work when TLS is being used. (To TLS, a tool like recorder looks like a man-in-the-middle attack.)

To disable TLS, set the variable use-tls to disabled in /etc/archiveopteryx/archiveopteryx.conf (see the archiveopteryx.conf(5) man page for more information.)

### Restart Archiveopteryx
The change to use-tls only takes effect when you restart Archiveopteryx, e.g. by issuing the following command:

/usr/lib64/archiveopteryx/archiveopteryx restart

### Start recorder
To make recorder listen on port 1430 and forward connections to the real server on port 143:

/usr/sbin/recorder 1430 192.0.2.17 143 /tmp/bugreport

### Connect to recorder
With the IMAP client, you connect to port 1430 on this host instead of the real server, and work as usual. Please don't do much more than is necessary to reproduce the problem, because it makes the bugreport files grow very large.

Stop

Just hit Control-C to stop recorder when you're done. The files called /tmp/bugreport* contain the IMAP session transcripts.

Remove passwords

Please edit the files to remove any passwords or other confidential data. If you can, don't change the number of words or bytes. It's best to change all the letters in passwords and confidential words to 'x'.

That's it. Now you can send an excellent bug report to info@aox.org.

## AUTHOR
The Archiveopteryx Developers, info@aox.org.

## VERSION
This man page covers Archiveopteryx version 3.1.3, released 2010-03-10, http://archiveopteryx.org/3.1.3

## SEE ALSO
archiveopteryx(8), archiveopteryx.conf(5), deliver(8), logd(8), http://archiveopteryx.org


title: arping2(8)

text:
# arping2(8)

## NAME
arping - sends arp and/or ip pings to a given host

## SYNOPSIS
arping [-0aAbBdDeFhpqrRuUv] [-S host/ip] [-T host/ip] [-s MAC] [-t MAC] [-c count] [-i interface] [ -w seconds ] [ -W seconds ] [ -V vlan ] [ -Q priority ] [ -g group ] <host | -B>

arping --help

## DESCRIPTION
The arping utility sends ARP and/or ICMP requests to the specified host and displays the replies. The host may be specified by its hostname, its IP address, or its MAC address.

One request is sent each second.

When pinging an IP an ARP who-has query is sent. When pinging a MAC address a directed broadcast ICMP Echo request is sent. For more technical explanation and an FAQ, see the README file.

Note on timing

ARP packets are usually replied to (on a LAN) so fast that the OS task scheduler can’t keep up to get exact enough timing. On an idle system the roundtrip times will be pretty much accurate, but with more load the timing gets less exact.

To get more exact timing on a non-idle system, re-nice arping to -15 or so.

\# nice -n -15 arping foobar

This is not just an issue with arping, it is with normal ping also (at least it is on my system). But it doesn’t show up as much with ping since arping packets (when pinging IP) doesn’t traverse the IP stack when received and are therefore replied to faster.

## OPTIONS
--help

Show extended help. Not quite as extensive as this manpage, but more than -h.

-0

Use this option to ping with source IP address 0.0.0.0. Use this when you haven’t configured your interface yet. Note that this may get the MAC-ping unanswered. This is an alias for -S 0.0.0.0.

-a

Audible ping.

-A

Only count addresses matching requested address (This *WILL* break most things you do. Only useful if you are arpinging many hosts at once. See arping-scan-net.sh for an example).

-b

Like -0 but source broadcast source address (255.255.255.255). Note that this may get the arping unanswered since it’s not normal behavior for a host.

-B

Use instead of host if you want to address 255.255.255.255.

-c count

Only send count requests.

-C count

Only wait for count replies, regardless of -c and -w.

-d

Find duplicate replies. Exit with 1 if there are answers from two different MAC addresses.

-D

Display answers as exclamation points and missing packets as dots. Like flood ping on a Cisco.

-e

Like -a but beep when there is no reply.

-F

Don’t try to be smart about the interface name. Even if this switch is not given, -i disables this smartness.

-g group

setgid() to this group instead of the nobody group.

-h

Displays a help message and exits.

-i interface

Don’t guess, use the specified interface.

-m type

Type of timestamp to use for incoming packets. Use -vv when pinging to list available ones.

-p

Turn on promiscious mode on interface, use this if you don’t "own" the MAC address you are using.

-P

Send ARP replies instead of requests. Useful with -U.

-q

Does not display messages, except error messages.

-Q priority

802.1p priority to set. Should be used with 802.1Q tag (-V). Defaults to 0.

-r

Raw output: only the MAC/IP address is displayed for each reply.

-R

Raw output: Like -r but shows "the other one", can be combined with -r.

-s MAC

Set source MAC address. You may need to use -p with this.

-S IP

Like -b and -0 but with set source address. Note that this may get the arping unanswered if the target does not have routing to the IP. If you don’t own the IP you are using, you may need to turn on promiscious mode on the interface (with -p). With this switch you can find out what IP-address a host has without taking an IP-address yourself.

-t MAC

Set target MAC address to use when pinging IP address.

-T IP

Use -T as target address when pinging MACs that won’t respond to a broadcast ping but perhaps to a directed broadcast.

Example:

```
To check the address of MAC-A, use knowledge of MAC-B and IP-B.
```

```
$ arping -S <IP-B> -s <MAC-B> -p <MAC-A>
```

-u

```
Show index=received/sent instead of just index=received when
pinging MACs.
```

-U

```
Send unsolicited ARP. This sets the destination MAC address in
the ARP frame to the broadcast address. Unsolicited ARP is used
to update the neighbours’ ARP caches.
```

```
Example:

$ arping -i <interface> -U <interface IP>
```

-v

```
Verbose output. Use twice for more messages.
```

-V vlan

```
VLAN tag to set. Defaults to no VLAN tag.
```

-w sec

```
Specify a timeout before ping exits regardless of how many packets have been sent or received.
```

-W sec

```
Time to wait between pings.
```

-z

```
Enable seccomp (default seccomp state depends on compile options)
```

-Z

```
Disable seccomp (default seccomp state depends on compile options)
```

## EXAMPLES

```
# arping -c 3 88.1.180.225
ARPING 88.1.180.225
60 bytes from 00:11:85:4c:01:01 (88.1.180.225): index=0 time=13.910 msec
60 bytes from 00:11:85:4c:01:01 (88.1.180.225): index=1 time=13.935 msec
60 bytes from 00:11:85:4c:01:01 (88.1.180.225): index=2 time=13.944 msec
```

```
--- 88.1.180.225 statistics ---
3 packets transmitted, 3 packets received,   0% unanswered
```

```
# arping -c 3 00:11:85:4c:01:01
ARPING 00:11:85:4c:01:01
60 bytes from 88.1.180.225 (00:11:85:4c:01:01): icmp_seq=0 time=13.367 msec
60 bytes from 88.1.180.225 (00:11:85:4c:01:01): icmp_seq=1 time=13.929 msec
60 bytes from 88.1.180.225 (00:11:85:4c:01:01): icmp_seq=2 time=13.929 msec
```

```
--- 00:11:85:4c:01:01 statistics ---
3 packets transmitted, 3 packets received,   0% unanswered
```

```
# arping -C 2 -c 10 -r 88.1.180.225
00:11:85:4c:01:01
00:11:85:4c:01:01
```

```

```

## BUGS
You have to use -B instead of arpinging 255.255.255.255, and -b instead of -S 255.255.255.255. This is libnets fault.

## SEE ALSO
ping(8), arp(8), rarp(8)

## AUTHOR
Arping was written by Thomas Habets <thomas@habets.se>.

http://www.habets.pp.se/synscan/

git clone http://github.com/ThomasHabets/arping.git


arpsend

package: arpsend

title: arpsend(8)

text:
# arpsend(8)

## NAME
arpsend - send an Ethernet frame containing an IP ARP request or reply packet with user-specified fields

## SYNOPSIS
arpsend [ -c count ] [ -d debuglevel ] [ -h ] [ -p pause_time ] [ -q ] [ -v ] [ -w ]

[ -i interface_name ]

[ -E ether_source_address ] [ -e ether_dest_address ]

[ -Q vlan_id ]

[ -o arp_opcode ]

[ -S sender_hardware_address ] [ -s sender_protocol_address ]

[ -T target_hardware_address ] -t target_protocol_address

## DESCRIPTION
arpsend sends an Ethernet frame containing an IP ARP request or reply packet containing fields you specify. This is a diagnostic tool intended for use by network administrators.

The program does not listen for any ARP replies; if you want to see any ARP replies prompted by a request, you should use another program to do so, such as tcpdump(1).

## AVAILABILITY
arpsend is a product of the Network Switching and Routing at Princeton University's Office of Information Technology, and is available from https://www.net.princeton.edu/software/arpsend/

Presently the product builds and runs on Solaris 9 and 10 on SPARC with gcc.

The program relies on the libnet(3) library.

## OPTIONS
-c count

Specifies the number of packets to send. If not specified, this defaults to 1.

-d debug_level

Sets the debug_level variable that controls the amount of debugging messages generated. If not specified, this defaults to 0 (no debugging). Presently no debugging messages are defined.

-E ether_source_address

Specifies the source address of the Ethernet frame. If not specified, this defaults to the Ethernet address of the outgoing interface. (Some environments may not allow you to override this value.)

-e ether_dest_address

Specifies the destination address of the Ethernet frame. If not specified, this defaults to the Ethernet broadcast address.

-h

Display a brief usage summary, then exit.

-i interface_name

Specifes the name of the Ethernet interface through which the packet should be sent. If not specified, this defaults to the first interface that is up (other than loopback).

-o arp_opcode

Specifies the ARP opcode; valid values are 1 (ARP Request) and 2 (ARP Reply). If not specified, this defaults to 1 (ARP Request).

-p pause_time

Specifies the number of seconds to pause between sending each packet, when the packet count is great than 1. If not specified, this defaults to 1 second.

-q

Specifies 'quiet' operation; only errors and warnings are displayed.

-Q vlan_id

Tag the frame with an 802.1Q VLAN ID.

-S sender_hardware_address

Specifies the ARP sender hardware address. If not specified, this defaults to the Ethernet address of the outgoing interface.

-s sender_protocol_address

Specifies the ARP sender protocol address. If not specified, this defaults to the primary IP address of the outgoing interface.

-T target_hardware_address

Specifies the ARP target hardware address. If not specified, this default to 0:0:0:0:0:0.

-t target_protocol_address

Specifies the ARP target protocol address. This option must be specified; no default value is supplied.

-v

Display the program's version number, then exit.

-w

Specifies that arpsend should not warn you about values that might cause network problems.

## OPERATION
arpsend is a diagnostic tool intended to be used by an network administrator. It is possible to specify values that will interfere with the normal operation of devices attached to the network, or the network as a whole.

arpsend checks for the most-common values that could cause network problems, but by no means can catch all such combinations of values. When it believes the values you specify could cause a problem, it will display a warning, and ask you if you still wish to send the packet. You can skip these checks (and the associated prompt) with the -w option; your packet will be sent without comment.

## EXAMPLES
To broadcast an ARP Request out the first interface that is up, requesting that 192.168.1.1 respond with an ARP Reply:

```
arpsend -t 192.168.1.1
```

In the example above, if my own IP address (on this interface) were 192.168.1.1, the packet would be a Gratuitous ARP request. Although the value of the target hardware address is not significant in a Gratuitous ARP request, typical ARP implementations set it to ff:ff:ff:ff:ff:ff when they send a Gratuitous ARP request; you can duplicate this behavior with:

```
arpsend -T ff:ff:ff:ff:fff:ff -t 192.168.1.1
```

To unicast an ARP Request via interface le1 to 0:0:1:1:2:3, requesting that 192.168.1.1 respond with an ARP Reply:

```
arpsend -i le1 -e 0:0:1:1:2:3 -t 192.168.1.1
```

To send an ARP Reply that appears to come from a device with IP address 192.168.1.3 and Ethernet address 0:0:1:1:1:1, unicasting the packet to 0:0:1:9:9:9 (we'll pretend that the target device's IP address is 192.168.1.4):

```
arpsend -o 2 -E 0:0:1:1:1:1 -e 0:0:1:9:9:9 -S 0:0:1:1:1:1 -s 192.168.1.3 -T 0:0:1:9:9:9 -t 192.168.1.4
```

## AUTHOR
The program was written by Irwin Tillman of Princeton University OIT Network Switching and Routing. It was written to run on Solaris 9 and 10, relying on the generally-available libnet(3) library.

## SEE ALSO
RFC 826

Address Resolution Protocol

RFC 1122

Host Network Requirements (Link Layer: Specific Issues, section 2.3)

libnet(3)

available from https://codedocs.xyz/libnet/libnet/md_README.html or https://github.com/libnet/libnet/releases


package: asterisk

title: astdb2bdb(8)

summary: convert astdb back to Berkeley DB 1.86

text:
# astdb2bdb(8)

## NAME
astdb2bdb - convert astdb back to Berkeley DB 1.86

## SYNOPSIS
cd astvarlibdir && astdb2bdb path/to/astdb.sqlite3

## DESCRIPTION
Up until version version 11, Asterisk used an old version of the Berkeley DB 1.86 (bdb) to store its internal persistent database. In version 11 it switched to using a SQLIte 3 database. This program is used to convert the newly-formatted SQLite 3 astdb back to bdb.

You may need it in case of reverting an upgrade or other similar scenarios.

## OPTIONS
There is a single (and required) parameter: the path the the sqlite file. The output file will be a file called astdb in the current working directory.

## EXAMPLES
In case you want to revert an upgrade to Asterisk 11, you can do the following (while Asterisk is not running):

cd /var/lib/asterisk && astdb2bdb astdb.sqlite3 && rm astdb.sqlite3

This will convert the newly-formatted astdb back to the old format, and delete it (to avoid obsolete data copies).

## NOTES
Berkeley DB 1.86 is obsolete. It is incompatible with newer versions (4.x and newer) that you may see around. Chances are you don't have the tools to use it independently of Asterisk.

## SEE ALSO
astdb2sqlite3(8), asterisk(8)

## AUTHOR
astdb2bdb was written by Terry Wilson <twilson@digium.com>.

This manual page was written by Tzafrir Cohen <tzafrir.cohen@xorcom.com>.


title: astdb2sqlite3(8)

summary: convert astdb to SQLite 3

text:
# astdb2sqlite3(8)

## NAME
astdb2sqlite3 - convert astdb to SQLite 3

## SYNOPSIS
astdb2sqlite3 path/to/astdb

## DESCRIPTION
Up until version version 11, Asterisk used an old version of the Berkeley DB 1.86 (bdb) to store its internal persistent database. In version 11 it switched to using a SQLite 3 database. This program is used to convert an existing bdb astdb file to astdb.sqlite3.

Normally the conversion is done by Asterisk itself which will run this program. But you may need to run it on your own.

## OPTIONS
There is a single (and required) parameter: the path the the bdb file. The output file name will be the same as the input, with .sqlite3 appended.

## EXAMPLES
Asterisk will typically run the following to upgrade the database:

astdb2sqlite3 /var/lib/asterisk/astdb

which will create /var/lib/asterisk/astdb.sqlite3.

## SEE ALSO
astdb2bdb(8), asterisk(8)

## AUTHOR
astdb2sqlite3 was written by Terry Wilson <twilson@digium.com>.

This manual page was written by Tzafrir Cohen <tzafrir.cohen@xorcom.com>.


asterisk

title: asterisk(8)

summary: All-purpose telephony server.

text:
# asterisk(8)

## NAME
asterisk - All-purpose telephony server.

## SYNOPSIS

asterisk

[-BcdfFghiImnpqRtTvVW] [-C file] [-e memory] [-G group] [-L loadaverage] [-M value] [-U user] [-s socket-file]

asterisk -r

[-v] [-d] [-x command]

asterisk -R

[-v] [-d] [-x command]

## DESCRIPTION
asterisk is a full-featured telephony server which provides Private Branch eXchange (PBX), Interactive Voice Response (IVR), Automated Call Distribution (ACD), Voice over IP (VoIP) gatewaying, Conferencing, and a plethora of other telephony applications to a broad range of telephony devices including packet voice (SIP, IAX2, MGCP, Skinny, H.323, Unistim) devices (both endpoints and proxies), as well as traditional TDM hardware including T1, E1, ISDN PRI, GR-303, RBS, Loopstart, Groundstart, ISDN BRI and many more.

At start, Asterisk reads the /etc/asterisk/asterisk.conf main configuration file and locates the rest of the configuration files from the configuration in that file. The -C option specifies an alternate main configuration file. Virtually all aspects of the operation of asterisk's configuration files can be found in the sample configuration files. The format for those files is generally beyond the scope of this man page.

When running with -c, -r or -R options, Asterisk supplies a powerful command line, including command completion, which may be used to monitors its status, perform a variety of administrative actions and even explore the applications that are currently loaded into the system.

Asterisk is a trademark of Digium, Inc.

## OPTIONS
Running Asterisk starts the asterisk daemon (optionally running it in the foreground). However running it with -r or -R connects to an existing Asterisk instance through a remote console.

-B

Force the background of the terminal to be black, in order for terminal colors to show up properly. Equivalent to forceblackbackground = yes in asterisk.conf. See also -n and -W.

-C file

Use file as master configuration file instead of the default, /etc/asterisk/asterisk.conf

-c

Provide a control console on the calling terminal. The console is similar to the remote console provided by -r. Specifying this option implies -f and will cause asterisk to no longer fork or detach from the controlling terminal. Equivalent to console = yes in asterisk.conf.

-d

Enable extra debugging statements. This parameter may be used several times, and each increases the debug level. Equivalent to debug = num in asterisk.conf to explicitly set the initian debug level to num. When given at startup, this option also implies -f (no forking). However when connecting to an existing Asterisk instance (-r or -R), it may only increase the debug level.

-e memory

Limit the generation of new channels when the amount of free memory has decreased to under memory megabytes. Equivalent to minmemfree = memory in asterisk.conf.

-f

Do not fork or detach from controlling terminal. Overrides any preceding specification of -F on the command line. Equivalent to nofork = yes in asterisk.conf. See also -c.

-F

Always fork and detach from controlling terminal. Overrides any preceding specification of -f on the command line. May also be used to prevent -d and -v to imply no forking. Equivalent to alwaysfork = yes in asterisk.conf.

-g

Remove resource limit on core size, thus forcing Asterisk to dump core in the unlikely event of a segmentation fault or abort signal. NOTE: in some cases this may be incompatible with the -U or -G flags.

-G group

Run as group group instead of the calling group. NOTE: this requires substantial work to be sure that Asterisk's environment has permission to write the files required for its operation, including logs, its comm socket, the asterisk database, etc.

-h

Provide brief summary of command line arguments and terminate.

-i

Prompt user to intialize any encrypted private keys for IAX2 secure authentication during startup.

-I

Enable internal timing if DAHDI timing is available. The default behaviour is that outbound packets are phase locked to inbound packets. Enabling this switch causes them to be locked to the internal DAHDI timer instead.

-L loadaverage

Limits the maximum load average before rejecting new calls. This can be useful to prevent a system from being brought down by terminating too many simultaneous calls.

-m

Temporarily mutes output to the console and logs. To return to normal, use logger mute.

-M value

Limits the maximum number of calls to the specified value. This can be useful to prevent a system from being brought down by terminating too many simultaneous calls.

-n

Disable ANSI colors even on terminals capable of displaying them. This option can be used only at startup (e.g. not with remote console).

-p

If supported by the operating system (and executing as root), attempt to run with realtime priority for increased performance and responsiveness within the Asterisk process, at the expense of other programs running on the same machine. Note: astcanary will run concurrently with asterisk. If astcanary stops running or is killed, asterisk will slow down to normal process priority, to avoid locking up the machine.

-q

Reduce default console output when running in conjunction with console mode (-c).

-r

Instead of running a new Asterisk process, attempt to connect to a running Asterisk process and provide a console interface for controlling it.

-R

Much like -r. Instead of running a new Asterisk process, attempt to connect to a running Asterisk process and provide a console interface for controlling it. Additionally, if connection to the Asterisk process is lost, attempt to reconnect for as long as 30 seconds.

-s socket file name

In combination with -r, connect directly to a specified Asterisk server socket.

-t

When recording files, write them first into a temporary holding directory, then move them into the final location when done.

-T

Add timestamp to all non-command related output going to the console when running with verbose and/or logging to the console.

-U user

Run as user user instead of the calling user. NOTE: this requires substantial work to be sure that Asterisk's environment has permission to write the files required for its operation, including logs, its comm socket, the asterisk database, etc.

-v

Increase the level of verboseness on the console. The more times -v is specified, the more verbose the output is. Specifying this option implies -f and will cause asterisk to no longer fork or detach from the controlling terminal. This option may also be used in conjunction with -r and -R. Note: This always sets the verbose level in the asterisk process, even if it is running in the background. This will affect the size of your log files.

-V

Display version information and exit immediately.

-W

Display colored terminal text as if the background were white or otherwise light in color. Normally, terminal text is displayed as if the background were black or otherwise dark in color.

-x command

Connect to a running Asterisk process and execute a command on a command line, passing any output through to standard out and then terminating when the command execution completes. Implies -r when -R is not explicitly supplied.

-X

Enables executing of includes via #exec directive inside asterisk.conf.

## EXAMPLES
asterisk - Begin Asterisk as a daemon

asterisk -vvvgc - Run on controlling terminal

asterisk -rx "core show channels" - Display channels on running server

## BUGS
Bug reports and feature requests may be filed at https://github.com/asterisk/asterisk/issues/

## SEE ALSO
https://www.asterisk.org - The Asterisk Home Page

http://www.asteriskdocs.org - The Asterisk Documentation Project

https://docs.asterisk.org - The Asterisk documentation

https://www.digium.com/ - Asterisk is sponsored by Digium

## AUTHOR
Mark Spencer <markster@digium.com>

Countless other contributors, see CREDITS with distribution for more information.


astgenkey

title: astgenkey(8)

text:
# astgenkey(8)

## NAME
astgenkey - generates keys for for Asterisk IAX2 RSA authentication

## SYNOPSIS
astgenkey [ -q ] [ -n ] [ keyname ]

## DESCRIPTION
astgenkey This script generates an RSA private and public key pair in PEM format for use by Asterisk. The private key should be kept a secret, as it can be used to fake your system's identity. Thus by default (without the option -n ) the script will create a passphrase-encrypted copy of your secret key: without entering the passphrase you won't be able to use it.

However if you want to use such a key with Asterisk, you'll have to start it interactively, because the scripts that start asterisk can't use that encrypted key.

The key is identified by a name. If you don't write the name on the command-line you'll be prompted for one. The outputs of the script are:

name.pub

The public key: not secret. Send this to the other side.

name.key

The private key: secret.

Those files should be copied to /var/lib/asterisk/keys

(The private key: on your system. The public key: on other systems)

To see the currently-installed keys from the asterisk CLI, use the command

keys show

## OPTIONS
-q

Run quietly.

-n

Don't encrypt the private key.

## SECURITY
The keys are created, using the umask of the user running the command. To create the keys in a secure manner, you should check to ensure that your umask is first set to disallow the private key from being world- readable, such as with the following commands:

umask 0066

astgenkey yourkey

And then make the key accessible to Asterisk (assuming you run it as user "asterisk").

chown asterisk /var/lib/asterisk/keys/yourname.*

## FILES
/var/lib/asterisk/keys

## SEE ALSO
asterisk(8), genrsa(1), rsa(1),

http://www.voip-info.org/wiki-Asterisk+iax+rsa+auth

## AUTHOR
This manual page was written by Tzafrir Cohen <tzafrir.cohen@xorcom.com> Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, Version 2 any later version published by the Free Software Foundation.

On Debian systems, the complete text of the GNU General Public License can be found in /usr/share/common-licenses/GPL-2.


autosupport

title: autosupport(8)

text:
# autosupport(8)

## NAME
autosupport — interactive script to provide Digium[tm]'s support with information

## SYNOPSIS
autosupport [OPTION] [prefix]

## DESCRIPTION
autosupport is a script that is normally run by a user contacting Digium's Technical Support to automate gathering support information. It will probe the system for some run-time and system information, and generate a backup of Asterisk related configuration. An optional parameter for a prefix may be specified which is typically used to specify a Digium Technical Support Ticket ID.

The script requires root privileges to run, and writes all output in the home directory of the user running the script. For the purposes of this document, this will be referred to as /root/ henceforth.

The system information is written to /root/digiuminfo.txt and the backup of configuration (and the system information file) are written to a tarball in /root/ with a base name of digium-info. A Date Stamp will be appended, and if specified the optional parameter will be a prefix. The tarball at least is expected to be attached to a support ticket with Digium.

## OPTIONS

### Arguments:
prefix

Used to prefix the file names. Typically a Digium Technical Support Ticket ID

### Options:
-n, --non-interactive

Run without requiring user input

-h, --help

Show help about options

## FILES
/root/digiuminfo.txt

/root/digium-info_YYYYMMDD.tar.gz

## SEE ALSO
asterisk(8)

## AUTHOR
autosupport was written by John Bigelow <support@digium.com> in conjunction with Charles Moye and Trey Blancher. This manual page was written by Tzafrir Cohen <tzafrir.cohen@xorcom.com> and updated by Charles Moye. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, Version 2 any later version published by the Free Software Foundation.

On Debian systems, the complete text of the GNU General Public License can be found in /usr/share/common-licenses/GPL-2.


title: safe_asterisk(8)

text:
# safe_asterisk(8)

## NAME
safe_asterisk — A wrapper to run the asterisk executable in a loop

## SYNOPSIS
safe_asterisk [ asterisk_params ]

## DESCRIPTION
safe_asterisk is a script that runs asterisk in a loop, which can be useful if you fear asterisk may crash.

The script does not run in the background like a standard service. Rather, it runs in its own linux virtual console (9, by default). It also uses the option '-c' of asterisk(8) to avoid detaching asterisk from that terminal.

safe_asterisk also runs asterisk with unlimited core file size, and thus asterisk will dump core in case of a crash.

To get a "picture" of console 9, from another terminal (e.g: from a remote shell session) you can use:

screendump 9

The init script of the Debian package should be able to run safe_asterisk as the asterisk service, if so configured. See comments in /etc/default/asterisk

## FILES
/tmp

safe_asterisk runs in that directory, rather than in / as usual.

/tmp/core

If core files were generated there, they may be

/etc/asterisk/startup.d

Files in this directory will be 'source'd by the safe_asterisk script before it starts Asterisk proper, allowing them to set additional environment variables or run any other steps that are needed for your system.

## BUGS
While showing the output on a console is useful, using screen(1) as the terminal may be better.

The script does not read configuration from standard location under /etc

It uses fixed locations under /tmp , and thus may be exposed to a symlink attacks.

## SEE ALSO
asterisk(8), screendump(9)

## AUTHOR
This manual page was written by Tzafrir Cohen <tzafrir.cohen@xorcom.com> Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, Version 2 any later version published by the Free Software Foundation.

On Debian systems, the complete text of the GNU General Public License can be found in /usr/share/common-licenses/GPL-2.


ataidle

package: ataidle

title: ataidle(8)

summary: a utility to spin down ATA drives

text:
# ataidle(8)

## NAME
ataidle - a utility to spin down ATA drives

## SYNOPSIS
ataidle [-h] [-i] [-s] [-o] [-I standby_mins ] [-S standby_mins ] [-A aam_level ] [-P apm_level ] device

## DESCRIPTION
ATAidle sets various power management features on hard drives, including timeouts to switch to idle and standby power saving modes, and setting the APM (power) and AAM (acoustic) levels. If only a device is specified, without options, information about the selected device will be shown.

## OPTIONS
-h

Show usage information

-i

Puts the drive into Idle mode

-s

Puts the drive into Standby mode

-o

Puts the drive into Sleep mode

-I

Puts the drive into Idle mode and configures the standby timer to put the drive into Standby mode after standby_mins minutes of inactivity.

-S

Puts the drive into Standby mode and configures the standby timer to put the drive into Standby mode after standby_mins minutes of inactivity.

-A

Set the acoustic level of the hard drive. This allows you to reduce the acoustic output of the drive at the expense of performance.

-P

Set the Advanced Power Management level of the drive. This allows you to reduce the power consumption of the drive at the expense of performance. A low apm_level will cause the drive to go into Standby mode to save power.

## NOTES
Notes on Auto Acoustic Management (AAM) and APM support

AAM and APM settings are vendor-specific and not all intermediate values may be valid. If you set an invalid APM value you will be notified that it failed - when setting an AAM value you should check the output of 'ataidle <device>' to see if it has been updated. If it hasn't, the value isn't supported and you should try a higher or lower setting.

Meaning of AAM values:

0

Acoustic management disabled.

1

Minimum noise.

2-126

Intermediate noise levels.

127

Maximum performance, maximum noise. Meaning of APM values:

0

APM disabled

1

Minimum power usage with Standby (spindown).

2-127

Intermediate power usage with Standby.

128

Minimum power usage without Standby (no spindown).

129-253

Intermediate power usage without Standby.

254

Maximum performance, maximum power usage.

## AUTHOR
Bruce Cran <bruce@cran.org.uk>

## SEE ALSO
atacontrol(8), hdparm(8), smartctl(8)


atftpd

package: atftp

title: atftpd(8)

summary: Trivial File Transfer Protocol Server.

text:
# atftpd(8)

## NAME
atftpd - Trivial File Transfer Protocol Server.

## SYNOPSIS
atftpd [options] directory

## DESCRIPTION
atftpd is a TFTP (RFC1350) server. By default it is started by inetd on most systems, but may run as a stand alone daemon. This server is multi-threaded and supports all options described in RFC2347 (option extension), RFC2348 (blksize), RFC2349 (tsize and timeout) and RFC2090 (multicast option). It also supports mtftp as defined in the PXE specification.

## OPTIONS
This program supports both the usual GNU command line syntax, with long options starting with two dashes ('-') as well as short options. A description of the options is included below.

-t, --tftpd-timeout <value>

Number of seconds of inactivity before the server exits. This value has meaning only when the server is started by inetd. In daemon mode, the server never exits. Default is 300 seconds.

-r, --retry-timeout <value>

How many seconds to wait for a reply before retransmitting a packet. Default is 5 seconds. This can be overridden by the TFTP client with the 'timeout' option.

-m, --maxthread <value>

Maximum number of concurrent threads allowed. Default is 100.

-v, --verbose[=value]

Increase or set the logging level. No arguments will increase by one the current value. Default is LOG_NOTICE, see syslog(3) for log level. Valid value range from 0 (LOG_EMERG) to 7 (LOG_DEBUG).

--trace

When verbose level is set to 7, this will output debug information for each packet sent or received from the network.

--no-timeout

disable 'timeout' from RFC2349. This will prevent the server from acknowledging the 'timeout' option requested by the client.

--no-tsize

disable 'tsize' from RFC2349. This will prevent the server from acknowledging the 'tsize' option requested by the client.

--no-blksize

disable 'blksize' from RFC2348. This will prevent the server from acknowledging the 'blksize' request by the client.

--no-windowsize

disable 'windowsize' from RFC7440. This will prevent the server from acknowledging the 'windowsize' request by the client.

--no-multicast

disable 'multicast' from RFC2090. This will prevent the server from acknowledging the 'multicast' request by the client.

--logfile <logfile>

Log to a specific file instead of only syslog. 'nobody' (or any user used to run the server) must have permissions on the given file. Assuming the file is /var/log/atftpd.log, simply run: "touch /var/log/atftpd.log" and then "chown nobody.nogroup /var/log/atftpd.log". When the server is run in daemon mode, /dev/stdout or /dev/stderr can be used. Specifying a single dash as the filename will send logs to stdout (file descriptor 1).

--pidfile

Write the PID of the server to the specified file. This may be useful when automatically starting and stopping one or more instance of the server.

--daemon

Run as a daemon. Do not use this option if atftpd is started by inetd.

--no-fork

When --daemon is specified, this option will prevent the server from forking to background. It is useful for debugging purpose or specialized usage.

--user <user[.group]>

By default, the server change identity to the user nobody and group nogroup. Specify an alternate user.group with this option.

--group <group>

Alternate way of specifying the group. If group is specified with --user and --group, the last option will be used.

--port <number>

Specify the port on which atftpd listens. Useful when --daemon is specified. Default is standard tftp port as determined by getservbyname(3).

--bind-address <IP address>

Specify the IP address which atftpd binds to. Useful when --daemon is specified. Default is to bind to all interfaces. Only one address can be specified, the server can only listen to one or all interfaces.

--mcast-ttl

Specify the TTL to be used for multicast datagram. By default a value of 1 is used. Note that TTL has a special meaning in multicast as it is used to determine the scope of the packets. The value of 1 means the packets don't leave the local network, see ip(4). Scope may also be determine by the address as described RFC2365.

--mcast-addr

Specify the IP address range to be used for multicast transfer. Format string may comprise range and list of values: "239.255.0.0-31,128-132,200". Default value is "239.255.0.0-255". This address range is proposed in RFC2365 for local scope.

--mcast-port

Specify the UDP port to use for multicast transfer. Format string may contain range and list of port number: "1758-2000,8000-9000". default value is "1758".

--pcre <file>

Specify a pattern/replacement file to use. This allows one to replace requested file name based on Perl Compatible Regular Expression. See README.PCRE.

--pcre-test <file>

Test a pattern/replacement file. When using this option, the server will not start as usual but just read file name from stdin and printout the substitution.

--mtftp <file>

This will start a mtftp server thread for each valid entry in the supplied file. See PXE specification for detail about mtftp. An example file is provided in the source distribution.

--mtftp-port <port>

Port the mtftp server shall listen to for incoming request.

--no-source-port-checking

In some specific cases of networks using load balancer or other equipment performing NAT (network address translation), some needs to disable source port checking because port number as been translated. If you want to use this feature, you must know why you need it and the implication. Be aware that this option violate the RFC1350. This option has effect only for non-multicast transfer.

--prevent-sas

Address the Sorcerer's Apprentice Syndrome situation as requested by RFC 1350. This RFC requires repeated responses to a single packet to be rejected. Thus a block will only get retransmitted on a timeout. For backward compatibility, the default stays to ignore this RFC. So blocks get transmitted on every request.

--mcast-switch-client

This option allows the server to proceed with the next multicast client as soon as the current client timeout. When the current master client fails to send an acknowledge (ACK) to the server, the server will send an option acknowledge (OACK) to the master client with the field MC (master client) set to false and send an OACK to the next multicast client with MC set to true. Without this option, the server will retry the current master client up to 5 times and then mark it done, proceeding with the next one.

-V, --version

Show version of program.

-h, --help

Show summary of options.

path

This is the root directory used by the TFTP server. All requested files from a TFTP client must reside in this directory. If not specified, the directory defaults to /tftpboot. Since atftpd run as the nobody user, the permission of the directory must be set properly to allow file reading and writing.

## STATS
Starting with release 0.2, the server collects some statistics. Currently the server compute system load, time between connections and some thread statistics like number of file sent, received, number of abort... To see those stats in the logs, you need to set --verbose=6 (LOG_NOTICE) or higher.

## SECURITY
TFTP by itself has no provision for security. There is no user authentication and TFTP clients get access to all files within the specified root directory for which the server has permission.

Some level of security can be gained using atftp libwrap support. Adding proper entry to /etc/hosts.allow and /etc/hosts.deny will restrict access to trusted hosts. Daemon name to use in these files is in.tftpd.

## PCRE
The atftpd server provides a way to dynamically replace requested file name by a new one based on Perl compatible regular expression. Pairs of pattern/replacement are read from the specified files. Upon reception of a read request, the server will first try to open the file name requested. If it fails, then it will search for a replacement based on the content of the pattern file. If this still fails, then an error will be sent to the client. This feature is available only for read request. It makes no sense doing this substitution for client writing files to the server.

## MTFTP
The mtftp name refer to multicasrt tftp as define by the PXE specification. See pxespec.txt for the source of the specification. Note that this is not the same as RFC2090. PXE compliant boot implements mtftp, not RFC2090.

## SEE ALSO
inetd(8),hosts_access(5),libpcre(7), RFC1350, RFC2090, RFC2347, RFC2348, RFC2349 and pxespec.pdf.

## AUTHOR
This manual page was written by Remi Lefebvre <remi@debian.org> and Jean-Pierre Lefebvre <helix@step.polymtl.ca>.


title: ath_info(8)

text:
# ath_info(8)

## NAME
ath_info - print module version info, write some eeprom fields

## SYNOPSIS
ath_info [-w [-g N:M]] [-v] [-f] <pci_address> [<field1> <val1> [<field2> <val2> ...]]

## DESCRIPTION
ath_info prints some version information of Atheros WLAN modules. It furthermore allows to change regulatory domain and PCI ID fields in the EEPROM.

You must first retrieve the PCI memory address of the module by lspci -v and maybe activate the module by setpci (see example below).

DISCLAIMER: Use the write function only if you know what you are doing! There is the chance to brick your module. The authors aren't responsible for any damage caused by using this program.

Transmitting on illegal frequencies may violate state laws. Obey the local regulations!

## OPTIONS
-w

Write to the EEPROM. You need to specify at least one field value pair (see below).

-g N:M

Set the GPIO pin N to level M (N=0..5, M=0,1). Only useful with -w. ath_info sets GPIO 4 to 0 (low) for chipsets newer or equal to 5213 to enable writing to the EEPROM. If your module has a different layout, you may need to overwrite this.

-v

verbose printouts

-f

force, don't ask before writing to EEPROM (with -w).

<pci_address>

The PCI address of the module. You must retrieve it with lspci.

<field> <value>

Field and value names for EEPROM writing. Possible fields are: pci_dev_id, pci_vendor_id, pci_class, pci_rev_id, pci_subsys_dev_id, pci_subsys_vendor_id, regdomain

## EXAMPLE
Execute the commands below from a root account.

Retrieve the module's PCI memory address with lspci:

```
# lspci -v
0b:00.0 Ethernet controller: Atheros Communications, Inc. AR5211 802.11ab NIC
(rev 01)

        Subsystem: Standard Microsystems Corp [SMC] Unknown device 2335

        Flags: medium devsel, IRQ 20

        Memory at 6c000000 (32-bit, non-prefetchable) [size=64K]

        Capabilities: [44] Power Management version 2
```

The above card has its memory mapped at 0x6c000000. If no madwifi driver is running or the module isn't recognized by the driver anymore, e.g. due to wrong PCI id values (check your syslog), you must manually enable the PCI device with setpci. The argument to "-s" comes from the output above:

```
setpci -s 0b:00.0 command=0x41f cache_line_size=0x10
```

Retrieve some information of the module:

```
# ./ath_info 0x6c000000

 -==Device Information==-
MAC Version:  5211  (0x40)
MAC Revision: 5211  (0x42)
5GHz PHY Revision: 5111  (0x17)
2GHz PHY Revision: 2111  (0x23)

 -==EEPROM Information==-
EEPROM Version:     3.2
EEPROM Size:        16K
Regulatory Domain:  0x20

 -==== Capabilities ====-
|  802.11a Support: yes  |
|  802.11b Support: yes  |
|  802.11g Support: no   |
|  RFKill  Support: no   |

 ========================
```

Set the regulatory domain to 0. You need to confirm to write with 'y' (-f turns this off). Check http://madwifi-project.org/wiki/UserDocs/CountryCode for more information on regdomains and country codes:

```
# ./ath_info -w 0x6c000000 regdomain 0

 -==Device Information==-
MAC Version:  5211  (0x40)
MAC Revision: 5211  (0x42)
5GHz PHY Revision: 5111  (0x17)
2GHz PHY Revision: 2111  (0x23)

 -==EEPROM Information==-
EEPROM Version:     3.2
EEPROM Size:        16K
Regulatory Domain:  0x20

 -==== Capabilities ====-
|  802.11a Support: yes  |
|  802.11b Support: yes  |
|  802.11g Support: no   |
|  RFKill  Support: no   |

 ========================
GPIO registers: CR 00000000 DO 00000000 DI 00000000

           regdomain (0x00bf) := 0x0000
WARNING: The write function may easy brick your device or
violate state regulation on frequency usage.
Proceed on your own risk!
Shall I write the above value(s)? (y/n)
y
```

## BUGS
The write function is currently not tested with 5210 devices.

Use at your own risk, entering a false device address will have really nasty results!

An invalid magic in the EEPROM will cause ath_info to fail.


athcool

package: athcool

title: athcool(8)

text:
# athcool(8)

## NAME
athcool - control power-saving mode on AMD Athlon/Duron CPUs

## SYNOPSIS
athcool command

## DESCRIPTION
athcool is a program that controls the power-saving mode on AMD Athlon/Duron CPUs. The parameter command is one of:

on

Enable power-saving mode.

off

Disable power-saving mode.

stat

Query power-saving mode.

list

List supported chipsets.

## WARNINGS
athcool only sets/unsets the "Disconnect enable when STPGNT detected" bit in the northbridge of the chipset. To save power, someone has to send the STPGNT signal when the CPU is idle. This is done by the ACPI subsystem when the C2 state is entered. Hence, you need ACPI support in your kernel to achieve power savings.

Depending on your motherboard and/or hardware components, enabling power-saving mode may cause:

* noisy or distorted sound playback,

* a slowdown in disk performance,

* system freezes or instability,

* massive corruption of the filesystem (rare, but observed at least once).

Before use athcool, you must recognize these potential DANGERS. Please use athcool AT YOUR OWN RISK.

athcool is supplied "as is". The author disclaims all warranties, expressed or implied. The author and any other persons assume no liability for damages, direct or consequential, which may result from the use of athcool.

## AUTHOR
Copyright (C) 2002-2004 Osamu Kayasono <jacobi@jcom.home.ne.jp>

This manual page was written by Nicolas Boullis <nboullis@debian.org>. And many users reported to me it works (or not). Thanks to all who contributed to athcool.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

On Debian systems, the complete text of the GNU General Public License can be found in /usr/share/common-licenses/GPL.

## SEE ALSO
For more information about power-saving with Athlon/Duron CPUs, see the Athlon-Powersaving-HOWTO at http://www.daniel.nofftz.net/linux/Athlon-Powersaving-HOWTO.html.


atopacctd

package: atop

title: atopacctd(8)

text:
# atopacctd(8)

## NAME
atopacctd - process accounting daemon

## SYNOPSIS
atopacctd [-v | topdirectory]

## DESCRIPTION
The atopacctd daemon switches on the process accounting feature in the kernel and let the process accounting records be written to a file, called the source file from now. After process accounting is activated, the atopacctd daemon transfers every process accounting record that is available in the source file to a shadow file. Client processes (like atop processes) will read the shadow files instead of the process accounting source file.

In this way, the atopacctd daemon operates as a 'layer' between the process accounting file that is written by the kernel and the shadow accounting files that are read by atop processes.

This approach has the following advantages:

o

The atopacctd daemon takes care that the source file is kept to a limited size. As soon as its maximum size is reached, it is truncated to a size of zero again (this is not noticed by the atop processes).

o

The atopacct daemon takes care that a shadow file is kept to a limited size. As soon as the current shadow file reaches this maximum size, the atopacctd daemon creates a new (subsequent) shadow file. While client processes still have the possibility to read the previous shadow file(s), the atopacctd daemon continues writing accounting records to the newest (current) shadow file. For this reason, the name of a shadow file consists of a 10-digit sequence number followed by the extension '.paf' (process acounting file). Old shadow files that are not used by client processes any more, are automatically removed by the garbage collector in the atopacctd daemon.

o

When no client processes are active (any more), all shadow files will be deleted and no records will be transferred to a shadow file any more. As soon as at least one client is activate again, the atopacctd daemon continues writing shadow files.

The directory /var/run is used as the default topdirectory. Below this top-directory, the source file pacct_source is created to which the kernel writes the process accounting records.

Furthermore, the subdirectory pacct_shadow.d is created as a 'container' for the shadow files. Apart from the shadow files, also the file current is maintained in this subdirectory, containing the sequence number of the current (newest) shadow file and the maximum number of records that will be written in each shadow file.

An alternative topdirectory can be specified as command line argument. When an alternative topdirectory is defined, also modify the configuration file /etc/atoprc to inform atop clients about this alternative location (see the atoprc man page). Such alternative topdirectory should be owned by root and may not be writable for the group or others (security reasons).

Notice that the kernel suspends writing process accounting records when the free space of the filesystem on which the process accounting file resides drops below 2%. Writing is resumed when the free space is 4% or more. These lowwater and highwater percentages can be configured via the /proc/sys/kernel/acct pseudo-file.

The atopacctd daemon suspends transferring process accounting records to shadow files when the free space of the filesystem on which the process accounting file resides drops below 5%. Transfer is resumed when the free space is 5% or more. Log messages are generated via syslog when writing to the current shadow file is suspended or resumed.

The -v flag can be used to verify the version of the atopacctd daemon.

## FILES
/var/run/pacct_source

Regular file to which the kernel writes the process accounting records. This file will be regularly truncated.

/var/run/pacct_shadow.d/current

Regular file containing the sequence number of the current shadow file and the maximum number of records per shadow file.

/var/run/pacct_shadow.d/N.paf

Regular files containing the process accounting records that have been copied transparently from the source file (N represents a 10-digit sequence number).

## SEE ALSO
atop(1), atopsar(1), atoprc(5), netatop(4), netatopd(8)

https://www.atoptool.nl

## AUTHOR
Gerlof Langeveld (gerlof.langeveld@atoptool.nl)


atopgpud

title: atopgpud(8)

text:
# atopgpud(8)

## NAME
atopgpud - GPU statistics daemon

## SYNOPSIS
atopgpud [-v]

## DESCRIPTION
The atopgpud daemon gathers statistical information from all Nvidia GPUs in the current system. With a sampling rate of one second, it maintains the statistics of every GPU, globally (system level) and per process. When atopgpud is active on the target system, atop connects to this daemon via a TCP socket and obtains all GPU statistics with every interval.

The approach to gather all GPU statistics in a separate daemon is required, because the Nvidia driver only offers the GPU busy percentage of the last second. Suppose that atop runs with a 10-minute interval and would fetch the GPU busy percentage directly from the Nvidia driver, it would reflect the busy percentage of the last second instead of the average busy percentage during 600 seconds. Therefore, the atopgpud daemon fetches the GPU busy percentage every second and accumulates this into a counter that can be retrieved by atop regularly. The same approach applies to other GPU statistics.

When the atopgpud daemon runs with root privileges, more process level counters (i.e. GPU busy and GPU memory busy per process) are provided that are otherwise not applicable.

Notice that certain GPU statistics are only delivered for specific GPU types. For older or less sophisticated GPUs, the value -1 is returned for counters that are not maintained. In the output of atop these counters are shown as 'N/A'.

When no (Nvidia) GPUs can be found in the target system, atopgpud immediately terminates with exit code 0.

Log messages are written via the rsyslogd daemon with facility 'daemon'. With the -v flag (verbose), atopgpud also logs debug messages.

## INSTALLATION
The atopgpud daemon is written in Python, so a Python interpreter should be installed on the target system. This can either be Python version 2 or Python version 3 (the code of atopgpud is written in a generic way). Take care that the first line of the atopgpud script contains the proper command name to activate a Python interpreter that is installed on the target system!

The atopgpud daemon depends on the Python module pynvml to interface with the Nvidia driver. This module can be installed by the pip or pip3 command and is usually packaged under the name nvidia-ml-py

Finally, the pynvml module is a Python wrapper around the libnvidia-ml shared library that needs to be installed as well.

After installing the atop package, the atopgpud is not automatically started, nor will the service be enabed by default. When you want to activate this service (permanently), enter the following commands (as root):

systemctl enable atopgpu

systemctl start atopgpu

## INTERFACE DESCRIPTION
Client processes can connect to the atopgpud daemon on TCP port 59123. Subsequently, such client can send a request of two bytes, consisting of one byte request code followed by one byte integer being the API version number.

The request code in the first byte can be 'T' to obtain information about the GPU types installed in this system (usually only requested once).

The request code can be 'S' to obtain all statistical counter values (requested for every interval).

The response of the daemon starts with a 4-byte integer. The first byte is the API version number that determines the response format while the subsequent three bytes indicate the length (big endian order) of the response string that follows.

In the response strings the character '@' introduces system level information of one specific GPU and the character '#' introduces process level information related to that GPU.

For further details about the meaning of the counters in a response string, please consult the source code.

## SEE ALSO
atop(1), atopsar(1), atoprc(5), netatop(4), netatopd(8), atopacctd(8)

https://www.atoptool.nl

## AUTHOR
Gerlof Langeveld (gerlof.langeveld@atoptool.nl)


package: audit

title: audisp-af_unix(8)

text:
# audisp-af_unix(8)

## NAME
audisp-af_unix - plugin to push audit events to an af_unix socket

## SYNOPSIS
audisp-af_unix [ OPTIONS ]

## DESCRIPTION
audisp-af_unix is a plugin for the audit event dispatcher that sends audit events to an af_unix socket where other applications can read events. The args line of the af_unix.conf file expects three arguments: access mode, socket path, and output format, and optionally a fourth argument specifying the queue depth. The access mode determines the permissions for the socket and defaults to 0640. The socket path specifies where the socket will be created, with the default location being /run/audit/audispd_events. The output format determines the format in which events are delivered to the socket and supports two options: "string" and "binary". The "string" format delivers events in a human-readable form, while the "binary" format delivers events in their binary representation, which is essential for applications that need to process events in binary and reconstruct headers accurately. If the output format is not specified, the plugin defaults to the "string" format. If no queue depth is specified, it defaults to 512.

The af_unix.conf file must also include the line format = binary. This setting specifies the input format that the audisp-af_unix plugin expects from the audit event dispatcher. It ensures that the input delivered to the plugin is in binary format, enabling the plugin to reconstruct headers in their proper binary structure.

When the plugin is sent SIGUSR1, it writes a state report to af_unix.state.

## FILES
/etc/audit/plugins/af_unix.conf /run/audit/audispd_events /run/audit/af_unix.state /etc/audit/auditd.conf

## SEE ALSO
auditd.conf(8), auditd-plugins(5).

## AUTHOR
Steve Grubb


audisp-filter

title: audisp-filter(8)

text:
# audisp-filter(8)

## NAME
audisp-filter - plugin to filter audit events and forward them to other plugins

## SYNOPSIS
audisp-filter MODE CONFIG_FILE BINARY [ BINARY_ARGS ]

## DESCRIPTION
audisp-filter is an audit event dispatcher plugin designed to filter out specific events based on its provided configuration. Moreover, it possesses the capability to forward the remaining logs to other plugins. The plugin is universally compatible, allowing seamless integration with any existing audit plugin that expects audit messages on its standard input. Currently it supports the following arguments:

MODE

The operational mode can be either allowlist or blocklist. In allowlist mode, the plugin forwards everything except for events that match the specified ausearch expressions in the configuration. Conversely, in blocklist mode, it refrains from forwarding anything except for events listed in the configuration.

CONFIG_FILE

Path to the main configuration file containing ausearch expressions.

BINARY

Path to an external program that will consistently receive filtered audit events through its standard input.

BINARY_ARGS

Optionally, you can pass additional arguments to the external program.

## CONFIGURATION AND RULES EVALUATION
Every single plugin that wants to benefit from the event filtering capability needs to create its own configuration file. It's a good practice to place this file inside the audit config directory, following the naming convention audisp-filter-pluginname.conf, for instance, audisp-filter-syslog.conf to filter audit events before sending them to syslog.

Each line within a configuration represents an ausearch-expression (5). Internally, these expressions are joined using the OR operator. Therefore, every expression is substituted with (PE || CE), where PE represents the previous expression and CE denotes the current expression being processed. Lines starting with a '#' character are treated as comments and do not influence the final rule set.

Upon the creation of an audit event, the filtering engine goes through the list of expressions, constructing the final expression representing our rule set. The event in question will be searched using this expression. The decision to forward an audit event to the configured binary depends on two factors: the operational mode of audisp-filter and whether the expression matches the ongoing event.

## EXAMPLE
Example1: Do not syslog audit events containing unsuccessful openat syscalls.

First, in the plugin config, make sure that operation mode is set to allowlist, the binary points to /sbin/audispFyslog and provide any additional arguments if needed. Next, create the plugin specific config file with the content below. Before enabling the audit plugin, always make sure the syntax is correct. This can be checked by calling audisp-filter --check path/to/config/file.

(type r= SYSCALL && syscall i= openat && success r= yes)

## FILES
/etc/audit/plugins/filter.conf /etc/audit/auditd.conf

## SEE ALSO
auditd.conf(8), ausearch-expression(5), auditd-plugins(5).

## AUTHOR
Attila Lakatos


audisp-remote

title: audisp-remote(8)

summary: plugin for remote logging

text:
# audisp-remote(8)

## NAME
audisp-remote - plugin for remote logging

## SYNOPSIS
audisp-remote

## DESCRIPTION
audisp-remote is a plugin for the audit event dispatcher that performs remote logging to an aggregate logging server. When the plugin is sent SIGUSR1, it writes a state report to remote.state.

## TIPS
If you are aggregating multiple machines, you should edit auditd.conf to set the name_format to something meaningful and the log_format to enriched. This way you can tell where the event came from and have the user name and groups resolved locally before it is sent off of the machine.

## SIGNALS
SIGUSR1

Causes the audisp-remote program to write a state report to remote.state in /run/audit. The suspend flag tells whether or not logging has been suspended. The remote_ended flag tells if the connection was broken by the server saying it can't log events. The transport_ok flag tells whether or not the connection to the remote server is healthy. The queue_length tells how many records are enqueued to be sent to the remote server. The max_queued_length shows the peak queue length since startup. The report also records glibc memory consumption when available.

SIGUSR2

Causes the audisp-remote program to resume logging if it were suspended due to an error.

## FILES
/etc/audit/audisp-remote.conf /etc/audit/plugins.d/au-remote.conf /etc/audit/auditd.conf /run/audit/remote.state

## SEE ALSO
auditd.conf(8), auditd-plugins(5), audisp-remote.conf(5).

## AUTHOR
Steve Grubb


audisp-statsd

title: audisp-statsd(8)

text:
# audisp-statsd(8)

## NAME
audisp-statsd - plugin to push audit metrics to a statsd service

## SYNOPSIS
audisp-statsd [ OPTIONS ]

## DESCRIPTION
audisp-statsd is a plugin for the audit event dispatcher that pushes audit metrics to a statsd service using UDP. It reads auditd's state report at regular intervals and forwards the data. Generation of the state report must be enabled in auditd.conf.

## CONFIGURATION
The plugin's configuration file is /etc/audit/audisp-statsd.conf. The following parameters are recognized:

address

The name or address of the statsd server.

port

The UDP port of the statsd service.

interval

Time interval between reading auditd's report. The value is a time string such as 10m, 1h, 2d, or 6M where the suffix is s for seconds, m for minutes, h for hours, d for days, and M for months. The default is 15s.

## REPORT METRICS
The plugin collects the following metrics as gauges:

backlog

number of kernel events pending transfer to user space

lost

number of kernel events dropped

free_space

how much disk free space auditd sees in MiB

plugin_current_depth

number of events in auditd pending transfer to plugins

plugin_max_depth

historical maximum number of events backlogged while pending transfer to plugins

total_memory

current total memory in use by glibc in KiB

memory_in_use

how much of the total memory is actively used in KiB

memory_free

amount of free memory available in the glibc arenas in KiB

The following metrics are counters:

events_total_count

total number of events seen during interval

events_total_failed

total number of events seen during interval with failed outcome

events_avc_count

total number of AVC events seen during interval

events_fanotify_count

total number of FANOTIFY events seen during interval

events_logins_success

total number of successful login events seen during interval

events_logins_failed

total number of failed login events seen during interval

events_anamoly_count

total number of anamoly events seen during interval

events_response_count

total number of anamoly response events seen during interval

## FILES
/etc/audit/audisp-statsd.conf /etc/audit/plugins/au-statsd.conf

## SEE ALSO
auditd.conf(8), auditd-plugins(5).

## AUTHOR
Steve Grubb


audisp-syslog

title: audisp-syslog(8)

summary: plugin to push audit events into syslog

text:
# audisp-syslog(8)

## NAME
audisp-syslog - plugin to push audit events into syslog

## SYNOPSIS
audisp-syslog [ OPTIONS ]

## DESCRIPTION
audisp-syslog is a plugin for the audit event dispatcher that wraps audit events back around to syslog. It can be passed three options: one which is the syslog facility, one that is the syslog level that all events are logged with, and one that determines if events should be interpreted. Valid facilities are LOG_LOCAL0 through 7, LOG_AUTH, LOG_AUTHPRIV, LOG_DAEMON, LOG_SYSLOG, and LOG_USER. Valid levels are LOG_DEBUG through LOG_EMERG. Setting these options is done in the /etc/audit/syslog.conf file on the args line.

If it is desired that events are interpreted, add the word interpret to the args line. This will cause all events to be interpreted. The drawback to this approach is that naive parsers can be tricked by an adversary that has the ability to name files, processes, or other user controlled objects.

If you are aggregating multiple machines, you should edit auditd.conf to set the name_format to something meaningful and the log_format to enriched. This way you can tell where the event came from and have the user name and groups resolved locally before it is sent off of the machine.

## FILES
/etc/audit/plugins/syslog.conf /etc/audit/auditd.conf

## SEE ALSO
auditd.conf(8), auditd-plugins(5), syslog(3).

## AUTHOR
Steve Grubb


audispd-zos-remote

title: audispd-zos-remote(8)

text:
# audispd-zos-remote(8)

## NAME
audispd-zos-remote - z/OS Remote-services Audit dispatcher plugin

## SYNOPSIS
audispd-zos-remote [ config-file ]

## DESCRIPTION
audispd-zos-remote is a remote-auditing plugin for the Audit subsystem. It should be started by the auditd(8) daemon and will forward all incoming audit events, as they happen, to a configured z/OS SMF (Service Management Facility) database, through an IBM Tivoli Directory Server (ITDS) set for Remote Audit service. See SMF MAPPING section below for more information about the resulting SMF record format.

auditd(8) must be configured to start the plugin. This is done by a configuration file usually located at /etc/audit/plugins.d/audispd-zos-remote.conf, but multiple instances can be spawned by having multiple configuration files in /etc/audit/plugins.d for the same plugin executable (see auditd(8)).

Each instance needs a configuration file, located by default at /etc/audit/zos-remote.conf. Check zos-remote.conf(5) for details about the plugin configuration.

## OPTIONS
config-file

Use an alternate configuration file instead of /etc/audit/zos-remote.conf.

## SIGNALS
audispd-zos-remote reacts to SIGTERM and SIGHUP signals (according to the auditd(8) specification):

SIGHUP

Instructs the audispd-zos-remote plugin to re-read it's configuration and flush existing network connections.

SIGTERM

Performs a clean exit. audispd-zos-remote will wait up to 10 seconds if there are queued events to be delivered, dropping any remaining queued events after that time.

## IBM z/OS ITDS Server and RACF configuration
In order to use this plugin, you must have an IBM z/OS v1R8 (or higher) server with IBM Tivoli Directory Server (ITDS) configured for Remote Audit service. For more detailed information about how to configure the z/OS server for Remote Auditing, refer to z/OS V1R8.0-9.0 Integrated Security Services Enterprise Identity Mapping (EIM) Guide and Reference

```
(http://publibz.boulder.ibm.com/cgi-bin/bookmgr_OS390/FRAMESET/EIMA1140/CCONTENTS?DT=20070827115119),
chapter "2.0 - Working with remote services".
```

### Enable ITDS to process Remote Audit requests
To enable ITSD to process Remote Audit requests, the user ID associated with ITDS must be granted READ access to the IRR.AUDITX FACILITY Class profile (the profile used to protect the R_Auditx service). This user ID can usually be found in the STARTED Class profile for the ITDS started procedure. If the identity associated with ITDS is ITDSUSER, the administrator can configure RACF to grant Remote Auditing processing to ITDS with the following TSO commands:

TSO Commands: Grant ITDSUSER READ access to IRR.AUDITX FACILITY Class profile

```
rdefine FACILITY IRR.RAUDITX uacc(none)
permit IRR.RAUDITX class(FACILITY) id(ITDSUSER) access(READ)
```

### Create/enable RACF user ID to perform Remote Audit requests
A z/OS RACF user ID is needed by the plugin - Every Audit request performed by the plugin will use a RACF user ID, as configured in the plugin configuration zos-remote.conf(5). This user ID needs READ access to FACILITY Class resource IRR.LDAP.REMOTE.AUDIT. If the user ID is BINDUSER, the administrator can configure RACF to enable this user to perform Remote Auditing requests with the following TSO commands:

TSO Commands: Enable BINDUSER to perform Remote Audit requests

```
rdefine FACILITY IRR.LDAP.REMOTE.AUDIT uacc(none)
permit IRR.LDAP.REMOTE.AUDIT class(FACILITY) id(BINDUSER) access(READ)
```

### Add @LINUX Class to RACF
When performing remote auditing requests, the audispd-zos-remote plugin will use the special @LINUX CDT Class and the audit record type (eg.: SYSCALL, AVC, PATH...) as the CDT Resource Class for all events processed. To make sure events are logged, the RACF server must be configured with a Dynamic CDT Class named @LINUX with correct sizes and attributes. The following TSO commands can be used to add this class:

TSO Commands: Add @LINUX CDT Class

```
rdefine cdt @LINUX cdtinfo(posit(493) FIRST(alpha,national,numeric,special) OTHER(alpha,national,numeric,special) RACLIST(REQUIRED) case(asis) generic(allowed) defaultuacc(none) maxlength(246))
setr classact(cdt)
setr raclist(cdt)
setr raclist(cdt) refresh
setr classact(@LINUX)
setr raclist(@LINUX)
setr generic(@LINUX)
```

### Add profiles to the @LINUX Class
Once the CDT Class has been defined, you can add profiles to it, specifying resources (wildcards allowed) to log or ignore. The following are examples:

TSO Commands: Log only AVC records (One generic and one discrete profile):

```
rdefine @LINUX * uacc(none) audit(none(read))
rdefine @LINUX AVC uacc(none) audit(all(read))
setr raclist(@LINUX) refresh
```

TSO Commands: Log everything (One generic profile):

```
rdefine @LINUX * uacc(none) audit(all(read))
setr raclist(@LINUX) refresh
```

Resources always match the single profile with the best match.

There are many other ways to define logging in RACF. Please refer to the server documentation for more details.

## SMF Mapping
The ITDS Remote Audit service will cut SMF records of type 83 subtype 4 every time it processes a request. This plugin will issue a remote audit request for every incoming Linux Audit record (meaning that one Linux record will map to one SMF record), and fill this type's records with the following:

### Link Value
The Linux event serial number, encoded in network-byte order hexadecimal representation. Records within the same Event share the same Link Value.

### Violation
Always zero (0) - False

### Event Code
Always two (2) - Authorization event

### Event Qualifier
Zero (0) - Success, if the event reported success=yes or res=success, Three (3) - Fail, if the event reported success=no or res=failed, or One (1) - Info otherwise.

### Class
Always @LINUX

### Resource
The Linux record type for the processed record. e.g.: SYSCALL,AVC,PATH,CWD etc.

### Log String
Textual message bringing the RACF user ID used to perform the request, plus the Linux hostname and the record type for the first record in the processed event. e.g.: Remote audit request from RACFUSER. Linux (hostname.localdomain):USER_AUTH

### Data Field List
Also known as relocates, this list will bring all the field names and values in a fieldname=value format, as a type 114 (Application specific Data) relocate. The plug-in will try to interpret those fields (i.e.: use human-readable username root instead of numeric userid 0) whenever possible. Currently, this plugin will also add a relocate type 113 (Date And Time Security Event Occurred) with the Event Timestamp in the format as returned by ctime(3).

## ERRORS
Errors and warnings are reported to syslog (under DAEMON facility). In situations where the event was submitted but the z/OS server returned an error condition, the logged message brings a name followed by a human-readable description. Below are some common errors conditions:

NOTREQ - No logging required

Resource (audit record type) is not set to be logged in the RACF server - The @LINUX Class profile governing this audit record type is set to ignore. See IBM z/OS RACF Server configuration

UNDETERMINED - Undetermined result

No profile found for specified resource. There is no @LINUX Class configured or no @LINUX Class profile associated with this audit record type. See IBM z/OS RACF Server configuration

UNAUTHORIZED - The user does not have authority the R_auditx service

The user ID associated with the ITDS doesn't have READ access to the IRR.AUDITX FACILITY Class profile. See IBM z/OS RACF Server configuration

UNSUF_AUTH - The user has insufficient authority for the requested function

The RACF user ID used to perform Remote Audit requests (as configured in zos-remote.conf(5)) don't have access to the IRR.LDAP.REMOTE.AUDIT FACILITY Class profile. See IBM z/OS RACF Server configuration

## BUGS
The plugin currently does remote auditing in a best-effort basis, and will discard events in case the z/OS server cannot be contacted (network failures) or in any other case that event submission fails.

## FILES
/etc/audit/plugins.d/audispd-zos-remote.conf /etc/audit/zos-remote.conf

## SEE ALSO
auditd(8), zos-remote.conf(5).

## AUTHOR
Klaus Heinrich Kiwi <klausk@br.ibm.com>