dbgserver: add man page for dbgserver-find.1

... with a lot of shared text between it and dbgserver.8

4 files changed, 199 insertions, 34 deletions

diff --git a/dbgserver/Makefile.am b/dbgserver/Makefile.am
index a447e387..3c27760c 100644
--- a/dbgserver/Makefile.am
+++ b/dbgserver/Makefile.am
@@ -53,6 +53,7 @@ AM_LDFLAGS = -Wl,-rpath-link,../libelf:../libdw:.
 bin_PROGRAMS = dbgserver dbgserver-find
 dbgserver_SOURCES = dbgserver.cxx
 man8_MANS = dbgserver.8
+man1_MANS = dbgserver-find.1
 dbgserver_LDADD = $(libdw) $(libelf) $(libeu) $(libdbgserver) $(libmicrohttpd_LIBS) $(libcurl_LIBS) $(sqlite3_LIBS) $(libarchive_LIBS) -lpthread -ldl
 
 dbgserver_find_SOURCES = dbgserver-find.c
@@ -91,6 +92,6 @@ uninstall: uninstall-am
 	rm -f $(DESTDIR)$(libdir)/libdbgserver.so
 	rmdir --ignore-fail-on-non-empty $(DESTDIR)$(includedir)/elfutils
 
-EXTRA_DIST = libdbgserver.map dbgserver.8
+EXTRA_DIST = libdbgserver.map dbgserver.8 dbgserver-find.1
 MOSTLYCLEANFILES = $(am_libdbgserver_pic_a_OBJECTS) libdbgserver.so.$(VERSION)
 CLEANFILES += $(am_libdbgserver_pic_a_OBJECTS) libdbgserver.so
diff --git a/dbgserver/dbgserver-find.1 b/dbgserver/dbgserver-find.1
new file mode 100644
index 00000000..a05bc456
--- /dev/null
+++ b/dbgserver/dbgserver-find.1
@@ -0,0 +1,131 @@
+'\"! tbl | nroff \-man
+'\" t macro stdmacro
+
+.de SAMPLE
+.br
+.RS 0
+.nf
+.nh
+..
+.de ESAMPLE
+.hy
+.fi
+.RE
+..
+
+.TH DBGSERVER-FIND 1
+.SH NAME
+dbgserver-find \- request debuginfo-related data
+
+.SH SYNOPSIS
+.B dbgserver-find debuginfo \fIBUILDID\fP
+
+.B dbgserver-find executable \fIBUILDID\fP
+
+.B dbgserver-find source \fIBUILDID\fP \fI/FILENAME\fP
+
+.SH DESCRIPTION
+\fBdbgserver-find\fP queries one or more \fBdbgserver\fP servers for
+debuginfo-related data.  In case of a match, it saves the the
+requested file into a local cache, prints the file name to standard
+output, and exits with a success status of 0.  In case of any error,
+it exits with a failure status and an error message to standard error.
+
+.\" Much of the following text is duplicated with dbgserver.8
+
+The dbgserver system uses buildids to identify debuginfo-related data.
+These are stored as binary notes in ELF/DWARF files, and are
+represented as lowercase hexadecimal.  For example, for a program
+/bin/ls, look at the ELF note GNU_BUILD_ID:
+
+.SAMPLE
+% readelf -n /bin/ls | grep -A4 build.id
+Note section [ 4] '.note.gnu.buildid' of 36 bytes at offset 0x340:
+Owner          Data size  Type
+GNU                   20  GNU_BUILD_ID
+Build ID: 8713b9c3fb8a720137a4a08b325905c7aaf8429d
+.ESAMPLE
+
+Then the hexadecimal BUILDID is simply:
+
+.SAMPLE
+8713b9c3fb8a720137a4a08b325905c7aaf8429d
+.ESAMPLE
+
+.SS debuginfo \fIBUILDID\fP
+
+If the given buildid is known to a server, this request will result
+in a binary object that contains the customary \fB.*debug_*\fP
+sections.  This may be a split debuginfo file as created by
+\fBstrip\fP, or it may be an original unstripped executable.
+
+.SS executable \fIBUILDID\fP
+
+If the given buildid is known to the server, this request will result
+in a binary object that contains the normal executable segments.  This
+may be a executable stripped by \fBstrip\fP, or it may be an original
+unstripped executable.  \fBET_DYN\fP shared libraries are considered
+to be a type of executable.
+
+.SS source \fIBUILDID\fP \fI/SOURCE/FILE\fP
+
+If the given buildid is known to the server, this request will result
+in a binary object that contains the source file mentioned.  The path
+should be absolute.  Relative path names commonly appear in the DWARF
+file's source-file directory, but these paths are relative to
+individual compilation unit AT_comp_dir paths, and yet an executable
+is made up of multiple CUs.  Therefore, to disambiguate, dbgserver
+expects source-file queries to prefix relative path names with the CU
+compilation-directory.
+
+Note: you should not elide \fB../\fP or \fB/./\fP sorts of relative
+path components in the directory names, because if this is how those
+names appear in the DWARF files, that is what dbgserver needs to see
+too.
+
+For example:
+.TS
+l l.
+#include <stdio.h>	source BUILDID /usr/include/stdio.h
+/path/to/foo.c	source BUILDID /path/to/foo.c
+\../bar/foo.c AT_comp_dir=/zoo	source BUILDID /zoo/../bar/foo.c
+.TE
+
+.SH "SECURITY"
+
+dbgserver-find \fBdoes not\fP include any particular security
+features.  It trusts that the binaries returned by the dbgserver(s)
+are accurate.  Therefore, the list of servers should include only
+trustworthy ones.  If accessed across HTTP rather than HTTPS, the
+network should be trustworthy.
+
+.SH "ENVIRONMENT VARIABLES"
+
+.TP 21
+.B DBGSERVER_URLS
+This environment variable contains a list of URL prefixes for trusted
+dbgserver instances.  Alternate URL prefixes are separated by space.
+
+.TP 21
+.B DBGSERVER_TIMEOUT
+This environment variable governs the timeout for each dbgserver HTTP
+connection.  A server that fails to respond within this many seconds
+is skipped.  The default is 5.
+
+.TP 21
+.B DBGSERVER_CACHE_PATH
+This environment variable governs the location of the cache where
+downloaded files are kept.  It is cleaned periodically as this
+program is reexecuted.  The default is $HOME/.dbgserver_client_cache.
+.\" XXX describe cache eviction policy
+
+.SH "FILES"
+.LP
+.PD .1v
+.TP 20
+.B $HOME/.dbgserver_client_cache
+Default cache directory.
+.PD
+
+.SH "SEE ALSO"
+.I "dbgserver(8)"
diff --git a/dbgserver/dbgserver-find.c b/dbgserver/dbgserver-find.c
index 23b3ed2f..befbfe71 100644
--- a/dbgserver/dbgserver-find.c
+++ b/dbgserver/dbgserver-find.c
@@ -27,30 +27,22 @@
    the GNU Lesser General Public License along with this program.  If
    not, see <http://www.gnu.org/licenses/>.  */
 
+#include "config.h"
 #include "dbgserver-client.h"
 #include <errno.h>
 #include <stdio.h>
 #include <string.h>
 
 
-/*
-   Command-line frontend for dbgserver.
-
-   Query dbgserver for the file with the FILETYPE and BUILDID given as
-   command-line arguments. FILETYPE must be one of "debuginfo", "executable"
-   or "source-file". BUILDID must be a hex string with even length. If
-   FILETYPE is "source-file" then a FILENAME must also be supplied as a
-   command-line argument, otherwise FILENAME is ignored and may be omitted.
-
-   If the file is successfully retrieved from the server, print the file's
-   path to stdout, otherwise print an error message describing the failure.
-*/
 int
 main(int argc, char** argv)
 {
   if (argc < 3 || argc > 4)
     {
-      fprintf(stderr, "usage: %s FILETYPE BUILDID FILENAME\n", argv[0]);
+      fprintf(stderr, "%s (%s) %s\n", argv[0], PACKAGE_NAME, PACKAGE_VERSION);
+      fprintf(stderr, "Usage: %s debuginfo BUILDID\n", argv[0]);
+      fprintf(stderr, "       %s executable BUILDID\n", argv[0]);
+      fprintf(stderr, "       %s source BUILDID /FILENAME\n", argv[0]);
       return 1;
     }
 
@@ -64,11 +56,11 @@ main(int argc, char** argv)
     rc = dbgserver_find_debuginfo((unsigned char *)argv[2], 0, &cache_name);
   else if (strcmp(argv[1], "executable") == 0)
     rc = dbgserver_find_executable((unsigned char *)argv[2], 0, &cache_name);
-  else if (strcmp(argv[1], "source-file") == 0)
+  else if (strcmp(argv[1], "source") == 0)
     {
-      if (argc != 4)
+      if (argc != 4 || argv[3][0] != '/')
         {
-          fprintf(stderr, "If FILETYPE is \"source-file\" then FILENAME must be given\n");
+          fprintf(stderr, "If FILETYPE is \"source\" then absolute /FILENAME must be given\n");
           return 1;
         }
       rc = dbgserver_find_source((unsigned char *)argv[2], 0, argv[3], &cache_name);
diff --git a/dbgserver/dbgserver.8 b/dbgserver/dbgserver.8
index 7963329c..8c146b9f 100644
--- a/dbgserver/dbgserver.8
+++ b/dbgserver/dbgserver.8
@@ -29,6 +29,13 @@ build an index by their buildid.  This index is used when remote
 clients use the HTTP webapi, to fetch these files by the same
 buildid.
 
+If a dbgserver cannot service a given buildid artifact request itself,
+and it is configured with information about upstream dbgservers, it
+will query them for the same information, just as \fBdbgserver-find\fP
+would.  If successful, it locally caches then relays the file content
+to the original requester.
+
+
 .SH OPTIONS
 .TP
 .BR \-F, \-\-source\-files=PATH
@@ -75,6 +82,8 @@ May be repeated to increase details.  The default verbosity is 0.
 
 .SH WEBAPI
 
+.\" Much of the following text is duplicated with dbgserver-find.1
+
 The dbgserver's webapi resembles ordinary file service, where a GET
 request with a path containing a known buildid results in a file.
 Unknown buildid / request combinations result in HTTP error codes.
@@ -83,7 +92,7 @@ can take advantage of standard HTTP management infrastructure.
 
 There are three requests.  In each case, the buildid is encoded as a
 lowercase hexadecimal string.  For example, for a program /bin/ls,
-looking at the ELF note GNU_BUILD_ID:
+look at the ELF note GNU_BUILD_ID:
 
 .SAMPLE
 % readelf -n /bin/ls | grep -A4 build.id
@@ -93,20 +102,20 @@ GNU                   20  GNU_BUILD_ID
 Build ID: 8713b9c3fb8a720137a4a08b325905c7aaf8429d
 .ESAMPLE
 
-Then the buildid HEXCODE is simply:
+Then the hexadecimal BUILDID is simply:
 
 .SAMPLE
 8713b9c3fb8a720137a4a08b325905c7aaf8429d
 .ESAMPLE
 
-.SS /buildid/\fIHEXCODE\fP/debuginfo
+.SS /buildid/\fIBUILDID\fP/debuginfo
 
 If the given buildid is known to the server, this request will result
-in a binary object that contains the customary \fB.debug_*\fP
+in a binary object that contains the customary \fB.*debug_*\fP
 sections.  This may be a split debuginfo file as created by
 \fBstrip\fP, or it may be an original unstripped executable.
 
-.SS /buildid/\fIHEXCODE\fP/executable
+.SS /buildid/\fIBUILDID\fP/executable
 
 If the given buildid is known to the server, this request will result
 in a binary object that contains the normal executable segments.  This
@@ -114,7 +123,7 @@ may be a executable stripped by \fBstrip\fP, or it may be an original
 unstripped executable.  \fBET_DYN\fP shared libraries are considered
 to be a type of executable.
 
-.SS /buildid/\fIHEXCODE\fP/source\fI/SOURCE/FILE\fP
+.SS /buildid/\fIBUILDID\fP/source\fI/SOURCE/FILE\fP
 
 If the given buildid is known to the server, this request will result
 in a binary object that contains the source file mentioned.  The path
@@ -133,9 +142,9 @@ is what dbgserver needs to see too.
 For example:
 .TS
 l l.
-#include <stdio.h>	/buildid/HEXCODE/source/usr/include/stdio.h
-/path/to/foo.c	/buildid/HEXCODE/source/path/to/foo.c
-\../bar/foo.c AT_comp_dir=/zoo	/buildid/HEXCODE/source/zoo/../bar/foo.c
+#include <stdio.h>	/buildid/BUILDID/source/usr/include/stdio.h
+/path/to/foo.c	/buildid/BUILDID/source/path/to/foo.c
+\../bar/foo.c AT_comp_dir=/zoo	/buildid/BUILDID/source/zoo/../bar/foo.c
 .TE
 
 .SH SECURITY
@@ -145,20 +154,52 @@ While it is robust with respect to inputs, some abuse is possible.  It
 forks a new thread for each incoming HTTP request, which could lead to
 a denial-of-service in terms of RAM, CPU, disk I/O, or network I/O.
 If this is a problem, users are advised to install dbgserver with a
-reverse-proxy HTTP front-end that enforces site policies for
-firewalling, authentication, authorization, and load control.
+HTTPS reverse-proxy front-end that enforces site policies for
+firewalling, authentication, integrity, authorization, and load
+control.
+
+When relaying queries to upstream dbgservers, dbgserver \fBdoes not\fP
+include any particular security features.  It trusts that the binaries
+returned by the dbgservers are accurate.  Therefore, the list of
+servers should include only trustworthy ones.  If accessed across HTTP
+rather than HTTPS, the network should be trustworthy.
+
+
+.SH "ENVIRONMENT VARIABLES"
+
+.TP 21
+.B DBGSERVER_URLS
+This environment variable contains a list of URL prefixes for trusted
+dbgserver instances.  Alternate URL prefixes are separated by space.
+Avoid referential loops that cause a server to contact itself, directly
+or indirectly - the results would be hilarious.
+
+.TP 21
+.B DBGSERVER_TIMEOUT
+This environment variable governs the timeout for each dbgserver HTTP
+connection.  A server that fails to respond within this many seconds
+is skipped.  The default is 5.
+
+.TP 21
+.B DBGSERVER_CACHE_PATH
+This environment variable governs the location of the cache where
+downloaded files are kept.  It is cleaned periodically as this
+program is reexecuted.  The default is $HOME/.dbgserver_client_cache.
+.\" XXX describe cache eviction policy
 
 .SH FILES
 .LP
 .PD .1v
 .TP 20
 .B $HOME/.dbgserver.sqlite
-default database file
+Default database file.
 .PD
 
+.TP 20
+.B $HOME/.dbgserver_client_cache
+Default cache directory for content from upstream dbgservers.
+.PD
+
+
 .SH "SEE ALSO"
-.I "dbgserver-find(1),"
-.LP
-.I "stap(1),"
-.LP
-.I "gdb(1),"
+.I "dbgserver-find(1)"