unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



screen(2)							    screen(2)



NAME

  screen - Gateway packet screening facility

SYNOPSIS

  #include <&lt;sys/types.h>&gt;
  #include <&lt;net/gw_screen.h>&gt;

  int mode;
  struct screen_data sdata;
  struct screen_stats sstats;

  ioctl(s, SIOCSCREENON, (caddr_t)&&amp;mode);
  ioctl(s, SIOCSCREEN, (caddr_t)&&amp;data);
  ioctl(s, SIOCSCREENSTATS, (caddr_t)&&amp;sstats);



PARAMETERS

  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_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	act-
  ing 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 contain-
  ing 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_int 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, 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 proto-
  col 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 pack-
  ets being dropped.



RETURN VALUES

  If an	error has occurred, a value of -1 is returned and errno	is set to
  indicate the error.

ERRORS

  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.

  [EACCES]
      If an operation reserved for the superuser is attempted by a non-
      superuser.

SEE ALSO

  Functions:  ioctl(2)

  Daemons:  screenmode(8), screend(8), screenstat(8)