$NetBSD: rfilter.2,v 1.4 2020/03/22 23:24:08 gutteridge Exp $

Advanced rfilter usage:  the strip key, and cmd:// notation


1.  The strip key

All examples so far have had a match field of foo/, and have
subsequently stripped out foo/ from the path before calling the
designated program.  This example shows how to not strip, if
desired.

Remember that the third parameter in a configuration specifies
the leading pathname component to strip (the ``strip key'' in my
nomenclature).  This must match the leading characters in the
path, otherwise no stripping is done.  To see the difference
between stripping and no stripping, use the following
configuration (or rfilter.2.conf):

  echo/		rfilter	echo/		echo %s
  echo_nostrip/	rfilter	no_strip	echo %s

Mount, and try a few things:

  % mkdir portal

  % mount_portal /usr/share/examples/mount_portal/rfilter.2.conf `pwd`/portal

  % cat portal/echo/"Hello there."
  Hello there.

  % cat portal/echo_nostrip/"Hello there."
  echo_nostrip/Hello there.

Notice that in the second case, the full path name (after
removing the mountpoint) was substituted for %s, and not just the
portion beyond the match key.


2.  cmd://, and how it can cause problems

With the proliferation of the web, URLs like
http://host/path/path and ftp://host/path/path,
gopher://host/path, etc. have become common.  We can provide web
access through the file system by parsing such names, and
treating them appropriately.  Use rfilter.2.conf, in particular,
the following lines:

  ftp://          rfilter nostrip ftp -Vo - %s
  http://         rfilter nostrip ftp -Vo - %s

Now, access the web!

  % mount_portal /usr/share/examples/mount_portal/rfilter.2.conf `pwd`/portal

  % cksum portal/http://www.NetBSD.org/
  362001418 6920 portal/http://www.NetBSD.org/

  % more portal/http://www.NetBSD.org/
  <html>
  <head>
  <!-- Copyright (c) 1996, 1997, 1998, 1999
	  The NetBSD Foundation, Inc.  ALL RIGHTS RESERVED. -->
  ...

Similarly, we can access ftp sites via ftp://

  % cat portal/ftp://ftp.NetBSD.org/pub/NetBSD/.message
  GIVEN THE NATURE OF THE SOFTWARE MADE AVAILABLE UNDER THIS PROGRAM
  IT IS HEREBY NOTED THAT ALL SOFTWARE, WITH THE EXCEPTION ...


The difficulty with the URL format becomes clear if we try to tar
a file from ftp://...:

  % tar tzf portal/ftp://ftp.NetBSD.org/pub/NetBSD-current/tar_files/doc.tar.gz
  portal/ftp: Unknown host
  tar (child): can't open archive portal/ftp://ftp.NetBSD.org/pub/NetBSD-current/tar_files/doc.tar.gz : Input/output error

The problem is, when tar sees a file of the form A:B, it assumes
A is a hostname.  In this case, A is "portal/ftp", which is
obviously not a hostname.

If we want to avoid this problem, there are at least two
solutions:
  1.  cat portal/ftp://ftp.NetBSD.org/pub/NetBSD-current/tar_files/doc.tar.gz | tar tzf -

  2.  Use ftp%// in the configuration file:

  ftp%//		rfilter	ftp%// ftp -Vo - ftp://%s

  % tar tzf portal/ftp%//ftp.NetBSD.org/pub/NetBSD-current/tar_files/doc.tar.gz

Note that in this case, we strip out ftp%//, and prepend ftp://
to the path argument to ftp.

tar is not the only application which treats a colon specially --
some others include dump, restore, and rcp/scp.  For this reason,
it is recommended to use %, rather than :, for URL-like cmd%//
portal configurations.


3.  Guru usage

We conclude this file with an outlandish example showing the full
utility of the rfilter portal.  Assume we want a single command
that can extract files from a bzip2'd tar archive that is on
an ftp site.  Currently, tar does not understand bzip2 format, so
it requires at least 3 commands:
  1.  fetch from ftp site
  2.  bunzip2 the file
  3.  extract.

With appropriate portal configurations, the following single command
would also work.

tar xf portal/bzcat%//`pwd`/portal/ftp%//FTP.SITE.NET/path/path/tar.bz2
