screenstat(8) System Manager's Manual screenstat(8)NAME
screenstat - Show gateway screening statistics
SYNOPSIS
/usr/sbin/screenstat
DESCRIPTION
The screenstat command displays statistics about kernel gateway screening. The display is sent to the standard output.
The format of the screenstat report is as follows:
total packets screened: 16754 total accepted: 15149 total rejected: 12 packets dropped:
because buffer was full: 0
because user was out of sync: 0
because too old: 1592 total dropped: 1592
The total packets screened count shows how many packets have been received for forwarding. The accepted and rejected counts show how many
packets were forwarded or dropped based on instructions from a user-level process. The total dropped count shows how many packets were
dropped for other reasons: lack of space in the kernel buffer, errors by a user process, or packets that were queued for too long. If the
counts do not add up, some packets are currently queued in the kernel.
SEE ALSO
Commands: screend(8), screenmode(8)
Functions: screen(2)screenstat(8)
Check Out this Related Man Page
screen(2) System Calls Manual screen(2)Name
screen - gateway packet screening facility
Syntax
#include <sys/types.h>
#include <net/gw_screen.h>
int mode;
struct screen_data sdata;
struct screen_stats sstats;
ioctl(s, SIOCSCREENON, (caddr_t)&mode);
ioctl(s, SIOCSCREEN, (caddr_t)&sdata);
ioctl(s, SIOCSCREENSTATS, (caddr_t)&sstats);
Arguments
The interface to the gateway screen facility is a set of ioctl requests. All these requests are meant to be used on a file descriptor cre-
ated by the system call.
SIOCSCREENON
The mode parameter, passed by reference, can be or Upon completion of the system call, the mode parameter contains the previous
value of the screen mode. Unprivileged users may only use the request.
SIOCSCREEN
This is the most important request and is described below. Only the super-user may make this request.
SIOCSCREENSTATS
Returns, by reference using the sstats parameter, statistics in this structure:
struct screen_stats {
u_long ss_packets; /* total packets screened */
u_long ss_nobuffer; /* dropped, buffer was full */
u_long ss_accept; /* total accepted */
u_long ss_reject; /* total rejected */
u_long ss_badsync; /* dropped, user was out of sync */
u_long ss_stale; /* dropped, too old */
};
Description
The gateway screen facility allows a user-level process to decide which network packets should be forwarded by the kernel (when the system
is acting as a gateway). When the screen mode is set to ``off,'' all packets are forwarded normally; when the screen mode is set to
``on,'' all packets that would be forwarded must be approved through the use of this facility.
Use of SIOCSCREEN
The request is used in the main loop of the user-level daemon. Each time it is called, it returns (by reference using the sdata parameter)
a structure containing a prefix of a packet (normally containing the packet headers) and some additional information:
struct screen_data_hdr {
short sdh_count; /* length of entire record */
short sdh_dlen; /* bytes of packet header */
u_long sdh_xid; /* transaction ID */
struct timeval sdh_arrival; /* time packet arrived */
short sdh_family; /* address family */
int sdh_action; /* disposition for packet */
#define SCREEN_ACCEPT 0x0001 /* Accept this packet */
#define SCREEN_DROP 0x0000 /* Do not accept this packet */
#define SCREEN_NOTIFY 0x0002 /* Notify sender of failure */
#define SCREEN_NONOTIFY 0x0000 /* Do not notify sender */
};
struct screen_data {
struct screen_data_hdr sd_hdr;
char sd_data[SCREEN_DATALEN]; /* sd_dlen bytes of packet header */
};
#define sd_count sd_hdr.sdh_count
#define sd_dlen sd_hdr.sdh_dlen
#define sd_xid sd_hdr.sdh_xid
#define sd_action sd_hdr.sdh_action
#define sd_arrival sd_hdr.sdh_arrival
#define sd_family sd_hdr.sdh_family
The sd_family field indicates the protocol family (for example, under which the packet is being handled; there is no protocol-specific code
in the kernel implementation of the gateway screen. Either the sd_family field should be initialized to a specific family before the
request is invoked (indicating that the user process is willing to handle requests for this family only), or it should be set to (indicat-
ing that the user process is willing to handle all protocols).
The user-level process examines the packet headers and decides whether or not the packet should be forwarded. It communicates this deci-
sion to the kernel by filling in the sd_action field in the structure with either or bit-wise ORed with the last choice causes the gateway
to drop the packet but send an error packet to the source host (if this is supported in the protocol family). The process then passes that
structure back to the kernel in another invocation of the request. That ioctl call then blocks until a new packet is available, at which
point the cycle repeats.
Note that two actions are being carried out through one system call, and that each cycle starts mid-way through a system call. Thus, the
first time a daemon uses this ioctl request, it has to pass in a no-op decision to complete the first (half) cycle. The kernel matches
incoming decisions with pending packets by comparing both the transaction id (sd_xid) field, and the user's process id (so one process can-
not provide decisions on packets presented to a different process). Decisions must be supplied in first-in, first-out order; decisions
supplied in the wrong order may result in packets being dropped.
Return Values
If an error has occurred, a value of -1 is returned and is set to indicate the error.
Diagnostics
In addition to those error codes described for the request can also return:
[ENOPROTOOPT] If the screen mode is set to the request is meaningless.
[EPERM] If an operation reserved for the superuser is attempted by a non-superuser.
See Alsoscreenmode(8), screend(8), screenstat(8), ioctl(2)screen(2)