unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (HP-UX-11.11)
Page:
Section:
Apropos / Subsearch:
optional field



 ppp.Filter(4)						       ppp.Filter(4)




 NAME
      ppp.Filter - PPP packet filter specification file format

 DESCRIPTION
      The file /etc/ppp/Filter describes how on-demand PPP links are to be
      managed.	By default, any type of packet causes the link (if down) to
      be brought up (connected to its remote end); any packet is allowed to
      traverse the link; and any packet is sufficient to reset the idle
      timer, expiration of which would cause the link to be shut down.	This
      combination is not always appropriate behavior, so the filter file
      allows individual control based on the packet type and its source or
      destination.  These selection criteria may be specified for any of the
      three phases of operation:  bringing up the link, passing packets on
      the link, and shutting down the link due to inactivity.  Packet
      logging detail may also be selected using the same criteria.

    Format
      Comments begin with a `#' and extend to the end of the line; blank
      lines, or lines beginning with a `#', are ignored.  Upper/lower case
      distinctions are ignored in hostname specifications, but are
      significant elsewhere.  Fields are separated by horizontal or vertical
      white space (blanks or tabs or newlines).

      If a line begins with a hostname or IP address or the special word
      `default', that line is considered to be the beginning of a new set of
      filtering specifications. The filtering specifications will be applied
      to any packet crossing the point-to-point link connecting this host to
      the peer named by that initial hostname or IP address.  The hostname
      or IP address in the first column of the filter file refers to the
      peer (system or router or terminal server) at the remote end of the
      point-to-point (PPP or SLIP) link.  The hostname or IP address in the
      first column of the filter file, and associated with the link peer, is
      unrelated to the source or destination IP address of any packet
      crossing the link.  If the link peer's address doesn't match any name
      or address specified in the first column of filter file, the filter
      specification following the special word `default' will be used.

      If a newline is followed by white space, that line is a continuation
      of the filtering specification already in progress.

      There are four keywords to describe the actions taken by pppd in
      response to a particular packet:

	   bringup     Describes those packets that will cause a call to be
		       placed and a connection initiated.  Packets of this
		       sort also must qualify to `pass' across the link,
		       either by being explicitly mentioned or by inclusion
		       in a larger class in the `pass' section.

	   pass	       Describes those packets that will be allowed to
		       traverse the link on an already-established



 Hewlett-Packard Company	    - 1 -   HP-UX Release 11i: November 2000






 ppp.Filter(4)						       ppp.Filter(4)




		       connection.  Only packets which would be passed can
		       cause the link to be brought up.	 Any packet that is
		       not passed is optionally logged, then discarded.

	   keepup      Describes packets that will reset the idle timer,
		       thereby keeping the line connected.

	   log	       Describes packets whose headers or contents are to be
		       noted in the log file.

      After each action keyword comes stanzas, separated by white space,
      describing packets that fit the criteria for that action.	 Each stanza
      is processed in the order shown in the file, and contain restrictions
      or permissions on the packets encountered.  As soon as a pattern or a
      condition is found that matches the packet in question, pppd takes the
      indicated action and ignores the rest of the listed stanzas (i.e.
      inclusive or with shortcut evaluation).

      Stanzas may contain IP protocol numbers, optionally hyphen-separated
      ranges of TCP or UDP port numbers along with the /tcp or /udp
      qualifier, numbers representing ICMP message types or codes (which can
      be found in <&lt&lt&lt;netinet/ip_icmp.h>&gt&gt&gt;) along with the `/icmp' qualifier,
      service names corresponding to entries in /etc/services, or names or
      IP addresses of hosts or networks, or the special keyword `all', which
      is the default for all actions except `log', where the default is
      `!all'.  (Usually, it is unnecessary to use `all'; as a convenience,
      pppd automatically adds a `!all' at the end of a stanza list if the
      last stanza is not negated, and add an `all' at the end of a stanza
      list if the last stanza is negated. For example, in the typical case
      of `log' this sensibly results in only those packets matching the
      stanzas shown being logged, and no others.  In the typical case of
      `pass', this results in certain listed packets being restricted, but
      allowing the passage of all others.)

      If a network is specified, either by name or by address, then the
      corresponding network mask must also be specified if it is of a
      different size than the default for that class of network.  The
      network mask and additional `and' conditions within a stanza are
      separated by slashes (`/'), and may be specified either as a series of
      decimal numbers separated by periods, or as a single 32-bit
      hexadecimal number.  The sense of a stanza may be negated by prefixing
      it with an exclamation mark (`!').

      In the `log' filter specification, the special keyword `trace' causes
      the contents (as well as headers) of the indicated type of packet to
      be written to the log file.  Also in the `log' filter specification,
      the special flag `rejected' signifies that the packet is to be logged
      only if it was rejected by the `pass' filter.

      Since TCP data streams are opened when the initiator sends a SYN
      packet to the intended recipient, pppd can distinguish between



 Hewlett-Packard Company	    - 2 -   HP-UX Release 11i: November 2000






 ppp.Filter(4)						       ppp.Filter(4)




      outbound (sent from this host) and inbound (coming from the other end
      of the link) uses of TCP applications such as telnet or FTP.  The
      special keyword `syn' allows filtering or logging these connection
      starters. Qualifying it with `recv' or `send' allows sessions to be
      started or logged only if they are initiated in the indicated
      direction.  The special keyword `fin' allows filtering or logging the
      packets that close TCP connections.

      The `src' and `dst' keywords serve to distinguish ports, addresses or
      hostnames, as applying to the source or destination, respectively, of
      the packet.  If both are applied to the same stanza (e.g.
      .../src/dst), then both the source and destination address and/or port
      must match.

      The unreach= keyword causes an ICMP Destination Unreachable message
      (RFC 792 and RFC 1122 section 3.2.2.1) to be sent to the packet's
      source address, bearing the indicated code field, which may be chosen
      from

	   net		  The destination network is unreachable.

	   host		  The destination host is unreachable.

	   prot		  The designated transport protocol is not
			  supported.

	   protocol	  The designated transport protocol is not
			  supported.

	   port		  The designated transport protocol (e.g., UDP) is
			  unable to demultiplex the datagram but has no
			  protocol mechanism to inform the sender.

	   needfrag	  Fragmentation is needed and the Don't Fragment
			  flag is set.

	   srcfail	  Source route failed.

	   net-unknown	  The destination network is unknown.

	   host-unknown	  The destination host is unknown.

	   host-isolated  The source host is  isolated.

	   net-prohibited Communication with the destination network is
			  administratively prohibited.

	   host-prohibited
			  Communication with the destination host is
			  administratively prohibited.




 Hewlett-Packard Company	    - 3 -   HP-UX Release 11i: November 2000






 ppp.Filter(4)						       ppp.Filter(4)




	   net-tos	  The destination network is unreachable for the
			  designated type of service.

	   host-tos	  The destination host is unreachable for the
			  designated type of service.

      The ip-opt= keyword can be used to select packets based on whether
      they bear various IP options (RFC 1122 section 3.2.1.8 and RFC 791
      section 3.1 (pps 16ff)), selected from

	   rr		  Record Route is used to trace the route an
			  internet datagram takes.

	   ts		  Time Stamp.

	   security	  Security is used to carry Security,
			  Compartmentation, User Group (TCC), and Handling
			  Restriction Codes compatible with DOD
			  requirements.

	   lsrr		  Loose Source Routing is used to route the internet
			  datagram based on information supplied by the
			  source.

	   ssrr		  Strict Source Routing is used to route the
			  internet datagram based on information supplied by
			  the source.

	   srcrt	  Either Loose Source Routing or Strict Source
			  Routing.

	   any		  Any IP option - could even match the No Operation
			  option.

 EXAMPLES
    Default Behavior
      The following Filter file describes the default behavior of pppd,
      either in the absence of a filter specification file or in the case of
      an empty file:

	   #	   Filter - PPP configuration file,
	   #	   binding packet types to actions.
	   #	   Describes the default behavior of the daemon:
	   default   bringup all pass all keepup all log !all

      The default behavior is no restriction of packets, and no logging.

    Internet Firewall
      A `pass' line like this might be appropriate as a security firewall
      between an organizational network and the larger Internet:




 Hewlett-Packard Company	    - 4 -   HP-UX Release 11i: November 2000






 ppp.Filter(4)						       ppp.Filter(4)




	   internet-gateway
		   bringup !ntp !3/icmp !5/icmp !11/icmp !who !route
			   !nntp !89
		   pass	   nntp/137.39.1.2 !nntp
			   telnet/syn/recv/137.175.0.0
			   !telnet/syn/recv !ftp/syn/recv
			   !login/syn/recv !shell/syn/recv !who
			   !sunrpc !chargen !tftp !supdup/syn/recv
			   !exec !syslog !route !6000/tcp/syn/send
		   keepup  !send !ntp !3/icmp !5/icmp !11/icmp
			   !who !route !89
		   log	   rejected

      This `pass' specification allows NNTP (Usenet news) transactions with
      one peer and no others.  It allows incoming Telnet sessions from hosts
      on only one network, disallows all other incoming Telnet, SUPDUP, and
      FTP sessions, and allows all outgoing Telnet SUPDUP, and FTP sessions.

      It allows X Window System clients running elsewhere to display on
      local window servers, but it allows no local X clients to use displays
      located elsewhere.  It disallows all SUN RPC traffic, thereby guarding
      the local YP/NIS and NFS servers from outside probes and filesystem
      mounts.  Alas, it also disallows local machines from mounting
      filesystems resident on NFS servers elsewhere, but this can't be
      helped because NFS uses RPC which is a UDP service, and therefore
      without the SYN and FIN packets that can be used to characterize the
      direction in which a TCP stream is being initiated.  It blocks several
      other sorts of traffic that could be used for nefarious purposes, and
      the absence of a trailing `!all' means that any traffic not explicitly
      blocked is permitted to pass.

      The `bringup' and `keepup' lines are appropriate for an intermittent
      dial-up connection, so that various error conditions won't cause the
      link to be established, nor to keep the call open beyond its
      usefulness.  OSPF (Open Shortest Path First) routing packets (IP
      protocol number 89, from RFC-1340) will cross the link, but won't
      cause it to be brought up, nor keep it up if it's otherwise idle.
      Usenet news traffic won't bring up the link, but once started, the
      link won't be shut off in the middle of a news batch.  The `log
      rejected' line keeps a record of every packet that is blocked by the
      `pass' line, so that unsuccessful penetration attempts will be noted.

    An Extremely Complex Example
      The following Filter file instructs the daemon that a connection to
      any neighbor except the host `backbone' be brought up in response to
      any packet except for those generated by NTP, ICMP Destination
      Unreachable, and rwhod.  If those are the only types of packets
      flowing across the link, it will not be kept up, but all packets are
      allowed to cross the link while it is up.	 Packets sent out will not
      reset the idle timer, but packets received from the peer will.  If the
      peer goes down and modem problems cause the phone not to be hung up,



 Hewlett-Packard Company	    - 5 -   HP-UX Release 11i: November 2000






 ppp.Filter(4)						       ppp.Filter(4)




      (and the idle command-line argument has been specified) pppd will hang
      up the connection and retry.

      In the special case of the host `backbone' (perhaps a server belonging
      to a network connectivity vendor), only telnet and FTP sessions, SMTP
      electronic mail, NNTP network news, and Domain Name System queries are
      considered sufficient cause to bring the link up or to keep it up if
      otherwise idle.

      Once the link is up, all the above plus NTP clock chimes and ICMP
      messages may flow across the link.  No packets to or from a particular
      host, nor any packets except Domain Name System queries and responses
      for any host on subnet 42 of the class B network 137.175 are ever
      allowed to cross the link, nor would they cause the link to be
      initiated.  We allow telnet and FTP sessions only if they are
      initiated in the outbound direction.

      We log one-line descriptions of various ICMP problem messages
      (Unreachable, Time Exceeded), and the complete contents of ICMP
      messages reporting IP header problems.  We log all telnet and FTP
      sessions, including inbound attempts (though they will fail because
      they are excluded in the `pass' specification above).  We also log the
      header of the first packet of any electronic mail message flowing over
      this link on its way to or from a specific host.

	   #
	   #	Filter -  PPP configuration file binding packet
	   #	     types to actions.
	   #
	   #	For packets that would pass, these services
	   #	will bring up the link:
	   #
	   backbone bringup smtp nntp domain telnet ftp
	   #
	   #	Once brought up, these will pass (or not):
	   #
		pass !131.119.250.104
		     domain/137.175.42.0/255.255.255.0
		     !137.175.42.0/0xffffff00
	   #		  (alternative ways of
	   #		   expressing subnet mask)
		     !telnet/syn/recv !ftp/syn/recv
		     domain smtp nntp ntp icmp telnet ftp
	   #
	   #	Packets received for the services shown will
	   #	reset the idle timer.
	   #
		keepup	  !send smtp nntp domain telnet ftp
	   #
	   #	Only these messages will have headers or contents
	   #	logged, unless higher-level debugging is set:



 Hewlett-Packard Company	    - 6 -   HP-UX Release 11i: November 2000






 ppp.Filter(4)						       ppp.Filter(4)




	   #
		log  3/icmp 11/icmp 12/icmp/trace
		     telnet/syn ftp/syn
		     smtp/syn/terminus.netsys.com
	   #
	   default bringup     !ntp !3/icmp !who
		   keepup      !send !ntp !3/icmp !who

 RECOMMENDATIONS
      Simpler filter specifications allow pppd to start up quicker and run
      faster, with less processing overhead for each packet, but that
      overhead is likely to present a problem only at very high line speeds
      (like T1).  The `backbone' example shown above is severe overkill for
      the sake of illustration, evolved over a period of several weeks, and
      took the authors several tries to get right.  Start with a simple
      filter specification and add each special case only as the need
      arises, usually as the result of watching packet logs.  Then test
      carefully to ensure that your change had only the desired effect.

      Be very careful with header logging and even more careful with packet
      content tracing.	Make the selection criteria very narrow, or the log
      file will grow extremely large in a short period of time.	 Also, if
      the daemon is running on a diskless workstation or if the log file is
      on a NFS-mounted file system, excessive amounts of logging information
      will drastically impede the daemon's ability to process at high packet
      rates.  Remember, NFS writes are synchronous.

      If you specify host names, be sure that their addresses are available
      locally, even with the connection down.  If you find that you must
      bring up a connection to resolve a domain name, consider using that
      host's IP address (decimal numbers separated by periods) in both
      Filter and Systems instead.

      If you want to specify all Domain Name System traffic, use `domain'
      which will be expanded to entries for both 53/tcp and 53/udp.  (Some
      DNS traffic uses each transport.)	 To allow queries but disable domain
      transfers, use !domain/tcp.  Similarly, some systems' older
      /etc/services files, as distributed by the manufacturer, list NTP as a
      TCP service.  When the current UDP NTP implementation was installed on
      your system, the administrator may have left the old 123/tcp entry
      along with the correct 123/udp.  The correct solution is to remove the
      123/tcp entry from /etc/services.	 A workaround would be to specify
      123/udp in Filter.

      DEC ULTRIX 4.2 and some other systems may have no entry for FTP's data
      socket in their /etc/services file.  If you want to log the bulk data
      connections as well as the control connections, you'll need to either
      add an entry for `ftp-data' to /etc/services, or use 20/tcp explicitly
      in Filter.  The former is preferable because it will cause the log
      file entry to contain the symbolic name (`ftp-data') rather than the
      socket/protocol notation.



 Hewlett-Packard Company	    - 7 -   HP-UX Release 11i: November 2000






 ppp.Filter(4)						       ppp.Filter(4)




      If your /etc/services file is missing some application-level protocols
      that you consider useful, you can populate it with entries from the
      Assigned Numbers RFC, number 1340.  For example, you may find it
      useful to add lines like

	   gopher    70/tcp
	   gopher    70/udp
	   kerberos  88/tcp
	   kerberos  88/udp
	   snmp	     161/tcp
	   snmp	     161/udp
	   nextstep  178/tcp
	   nextstep  178/udp
	   prospero  191/tcp
	   prospero  191/udp
	   x11	     6000/tcp
      if you're using those applications, and if they're not already in your
      /etc/services file as received from your system's manufacturer.  If
      you augment your /etc/services this way, then instead of using entries
      like

		pass !6000/tcp/syn/send

      your Filter could use entries like

		pass !x11/syn/send

      which is much more readable.  A list of TCP and UDP service numbers
      and names, culled from the Assigned Numbers RFC, is available in
      Examples/services.ex.

 AUTHOR
      ppp.Filter was developed by the HP.

 SEE ALSO
      tun(4), ppp.Auth(4), ppp.Devices(4), ppp.Dialers(4), ppp.Keys(4),
      ppp.Systems(4), services(4), pppd(1), RFC 791, RFC 792, RFC 1055, RFC
      1548, RFC 1332, RFC 1122, RFC 1144, RFC 1340.
















 Hewlett-Packard Company	    - 8 -   HP-UX Release 11i: November 2000