Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
screen(2)							     screen(2)

       screen -	gateway	packet screening facility

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

       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 system call.

		 The  mode parameter, passed by	reference, can be or Upon com-
		 pletion of the	system call, the mode parameter	 contains  the
		 previous  value  of  the screen mode.	Unprivileged users may
		 only use the request.

		 This is the most important request and	 is  described	below.
		 Only the super-user may make this request.

		 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 */ };

       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.

       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_fam-
       ily sd_hdr.sdh_family The sd_family field indicates the protocol	family
       (for example, under which the packet is being handled; there is no pro-
       tocol-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  (indicating	that  the user process is willing to handle all	proto-

       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  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 sup-
       ported 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	incom-
       ing decisions with pending packets by comparing both the	transaction id
       (sd_xid)	 field,	 and the user's	process	id (so one process cannot pro-
       vide 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 indi-
       cate the	error.

       In  addition  to	 those	error codes described for the request can also

       [ENOPROTOOPT]	   If the screen mode is set to	the request  is	 mean-

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

See Also
       screenmode(8), screend(8), screenstat(8), ioctl(2)


Name | Syntax | Arguments | Description | Return Values | Diagnostics | See Also

Want to link to this manual page? Use this URL:

home | help