pkg/43013: Clarification of URL handling for pkg_add/pkgin

[brook%nmsu.edu@localhost]

>Number:         43013
>Category:       pkg
>Synopsis:       Clarification of URL handling for pkg_add/pkgin
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    pkg-manager
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Fri Mar 19 14:50:00 +0000 2010
>Originator:     Brook Milligan
>Release:        5.0/i386
>Organization:
New Mexico State University
>Environment:
NetBSD viola.nmsu.edu 5.0_STABLE NetBSD 5.0_STABLE (VIOLA) #0: Thu Jan 28 
19:18:43 MST 2010  
root%viola.nmsu.edu@localhost:/usr/obj/sys/arch/i386/compile/VIOLA i386

>Description:
I recently tried to use pkg_add and pkgin with a remote repository for
the first time.  Being very familiar with using full URLs with ftp, I
interpreted the man pages for setting up these programs to mean that
the URLs specified to them would be equivalent to those specified to
ftp for downloading the same file.  This of course did not work
because of the following:

- ftp interprets paths relative to the default login directory.

- pkg_add/pkgin use libfetch which precedes accesses with CDUP
  commands to reach the root; therefore, paths are relative to the
  root of the ftp server.

In my case, these were not the same place, so while ftp worked fine
the other commands did not.  Needless to say, this was confusing.

I suggest that an addition to the pkg_add man page (see below) might
have helped me avoid some confusion.

Please improve this if it is technically incorrect or incomplete
(e.g., if http behaves differently), but this does appear to be the
behavior I have observed with ftp.

>How-To-Repeat:
Create an ftp repository with a login directory that is different from the 
root.  Retreive a file with ftp using a URL relative to the login directory.  
Try to use pkg_add or pkgin to retrieve the same file with the same URL.  It 
will fail.  Successfully retrieve the file with pkg_add or pkgin using a URL 
relative to the root.
>Fix:
Note that this patches only pkg_add.1; it seems that pkg_add.cat1 also exists 
in the distribution and should be made consistent.

--- pkg_add.1.orig      2010-03-19 08:41:02.000000000 -0600
+++ pkg_add.1   2010-03-19 08:42:22.000000000 -0600
@@ -212,6 +212,8 @@
 .Dq .tgz
 suffix) or a
 URL pointing at a file available on an ftp or web site.
+In the latter case, URLs will be resolved relative to the root of the
+server filesystem not the login directory.
 Thus you may extract files directly from their anonymous ftp or WWW
 locations (e.g.,
 .Nm