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 created by the socket() system call.
SIOCSCREENON
The mode parameter, passed by reference, can be SCREENMODE_OFF, SCREENMODE_ON, or SCREENMODE_NOCHANGE. Upon completion of the system call, the mode parameter contains the previous value of the screen mode. Unprivileged users may only use the SCREENMODE_NOCHANGE 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_longss_packets;/* total packets screened */
u_longss_nobuffer;/* dropped, buffer was full */
u_longss_accept;/* total accepted */
u_longss_reject;/* total rejected */
u_longss_badsync;/* dropped, user was out of sync */
u_longss_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 SIOCSCREEN 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 screen_data structure containing a prefix of a packet (normally containing the packet headers) and some additional information:
struct screen_data_hdr {
shortsdh_count;/* length of entire record */
shortsdh_dlen;/* bytes of packet header */
u_longsdh_xid;/* transaction ID */
struct timevalsdh_arrival;/* time packet arrived */
shortsdh_family;/* address family */
intsdh_action;/* disposition for packet */
#defineSCREEN_ACCEPT0x0001/* Accept this packet */
#defineSCREEN_DROP0x0000/* Do not accept this packet */
#defineSCREEN_NOTIFY0x0002/* Notify sender of failure */
#defineSCREEN_NONOTIFY0x0000/* Do not notify sender */
};
struct screen_data {
struct screen_data_hdr sd_hdr;
char sd_data[SCREEN_DATALEN];/* sd_dlen bytes of packet header */
};
#definesd_countsd_hdr.sdh_count
#definesd_dlensd_hdr.sdh_dlen
#definesd_xidsd_hdr.sdh_xid
#definesd_actionsd_hdr.sdh_action
#definesd_arrivalsd_hdr.sdh_arrival
#definesd_familysd_hdr.sdh_family
The sd_family field indicates the protocol family (for example, AF_INET) 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 AF_UNSPEC (indicating 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 decision to the kernel by filling in the sd_action field in the screen_data structure with either SCREEN_ACCEPT, SCREEN_DROP, or SCREEN_DROP bit-wise ORed with SCREEN_NOTIFY; 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 SIOCSCREEN 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 cannot 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 errno is set to indicate the error.
Diagnostics
In addition to those error codes described for ioctl(,), the SIOCSCREEN request can also return:
[ENOPROTOOPT] If the screen mode is set to SCREENMODE_OFF, the SIOCSCREEN request is meaningless.
[EPERM] If an operation reserved for the superuser is attempted by a non-superuser.