#
# radbserver-usage.pl
#
# various help commands for the radbserver
#

sub Usage {
print <<"EOF";
Usage: $0 [-h|-H|-q] -C<cfile> [-S<SrcDBs>|-A] [-f<dbpath>] [-N] [-d] [-D [-P<port>]] [<cmd>]

    -h -H -q   short/long help, and print protocol codes.
    -C<cfile>  config file to use (default ./conf)
    -S<SrcDB>  search the specified source database, and
               (if not -G) db's for which indexes will be built.
               If not supplied, searches ALLOK in conf file, unless...
    -A         use ALL databases defined in the conf file (even those not
               in ALLOK;  useful for making indexes).
    -f<dbpath> path to location of index files.  The path must exist.
               One file will be built for each of the sources named, eg,
               <dbpath>/MERITRR, <dbpath>/PRRDB, and so on.
    -d         debug messages on
    -N         build new index files and then quits.
    -p         run as prompter for the commands.  h at prompt for additional commands.
    -D         run as daemon
    -P<port>   port to use (if -D); defaults to 43 (whois port)
    <cmd>      single command to execute.  See below for details.

Ex: To have $0 build indexes for four db's in one directory:

       $0 -N -SMERITRR,PRDB,PRRDB,RIPE -C/f/rrdb/dbase-beta/conf  -f/f/rrdb/bin/radbserver.indexes.New

    then cp them to a production directory, and start daemon on the whois port:

       $0 -D -P 43 -SMERITRR,PRDB,PRRDB,RIPE -C/f/rrdb/dbase-beta/conf -f/f/rrdb/bin/radbserver.indexes.Prod &

EOF
}

#########################################################################################

sub Explain_Protocol {
print <<"EOF";
The server may be queried in three ways:
1. a standard RIPE-whois query:   35/8    or   -SMERITRR AS233
   This also accepts special commands:
   -q    print protocol query codes
   -H    print full radbserver.pl help
2. a one-shot protocol command:   !<protocol-cmd>
   where the ! indicates non-whois mode, and <protocol-cmd> is as described below).
   This may be sent as a command via whois.
3. in multi-query mode:           !!   on one line to enter this mode,
   then <protocol-cmd>'s sent on subsequent lines, with answers returned after each.
   The connection is closed by the quit-protocol command.
   This is not available via whois command, only via telnet or other means
   (e.g., see the example client.pl source the RA distributes).
Each query (of any type) is terminated by a newline.

The protocol commands have the general format
    <code><string><newline>
where <code> is a one byte code, and string is the query parameter.
EOF

&Print_Protocol_Query_Codes();

print <<"EOF";
Note that there are some special-purpose queries (get as-in lines for an AS),
but also a generic get(obj,keyvalue,attr) query which can be used to get
any attribute of any object.

All non-whois queries will return one or more lines of the form
    <byte-code><msg-string><newline>
where the codes and meanings are:
    65(A)      msg is (ascii) length of data to be returned (total) in upcoming data (code=220) lines.
    66(B)      data in msg-string (may be several of these lines)
    67(C)      end-of-data; For multi-source non-indexed query, <msg-string> is <diffcnt>,<diffsources>
               where <diffcount> is the of number of sources with values different from that returned
               (ie, from the first source with a non-null value), and <diffsources> is a list of blank
               separated source-names that have the different values.
               This code also returned for successful s (set source) commands.
    68(D)      key not found
    69(E)      multiple copies of key in one DB!
    70(F)      some other error---details in <msg-string>.
EOF
}

#########################################################################################

sub Print_Protocol_Update_Codes {
if ( !grep(/$rhostname/,@TrustedHosts) ) {
   	$msg = "Host '$rhostname' not allowed to do index updates.";
   	return;
}
print <<"EOF";
The radbserver accepts the following codes for updating its special search indexes:

    65(A) <source>,AS<asnum>,<route>         add    <route> with origin <asnum>
    66(B) <source>,AS<asnum>,<route>         delete
    67(C) <source>,<metric=asnum>,<route>    add    <route> for nsflist <metric=asnum>
    68(D) <source>,<metric=asnum>,<route>    delete
    69(E) <source>,<commname>,<route>        add    <route> for community <commname>
    70(F) <source>,<commname>,<route>        delete
    71(G) <source>,<countrycode>,<route>     add    <route> for country <countrycode>
    72(H) <source>,<countrycode>,<route>     delete
    73(I) <source>,$LOOKinetrtrKey,<value>   add    <inet-rtr> to special LOOK (List Of Objects Keys).
    74(J) <source>,$LOOKinetrtrKey,<value>   delete

    82(R) <source>,...                       Rebuild indexes for specified sources

These commands are accepted only from trusted hosts.

Note that these are just for updating the radbserver indexes, NOT for updating the
underlying registry database objects.  The idea is that the normal mail/dbupdate
procedure is used to update the underlying registry objects, and when that is successful,
dbupdate will open a connection and update the appropriate radbserver indexes.

Also note that the update occurs only in the indexes for specified source file.
EOF
}

#########################################################################################

sub Print_Protocol_Query_Codes {
print <<"EOF";
The following queries/commands are supported (the codes are in decimal,
followed by the equivalent ascii character):
     code   string parameter          action:
     ------ ----------------          --------------------------------
     101(e) as<asnum>                 get_as_in_lines (note lowercase 'as' on all these!)
     102(f) as<asnum>                 get_as_out_lines
     103(g) as<asnum>                 get_routes_by_origin
     104(h) community-name            get_routes_by_community
     105(i) as-macro-name             expand_as_macro
     106(j) <metric>:<asnum>[(nss)]   get_routes_by_as_metric_nss (from local-route AS690 lines)
     107(k) <country-code>            get_routes_by_country_code
     108(l) [<fmt>[,<sourcedb>]]      dump_all_routes  (under development)
		                              fmt=0    routes only
     109(m) <obj>,<key>               get whole object of type <obj> by key (not following sub-references)
     110(n) <obj>,<key>,<attr>        get <attr> value for object of type <obj> with key <key>
     111(o) <obj>,<value>,<attr>      get keys of <obj>s which have <attr>=<value> lines in them
     112(p) <type>=<key>              special search of <type>, for key <key>:
                                      type                            key       returns
                                      ----------------------------    ---       -----------------
                                      LOOK (list of object keys)      ir        all inet-rtr keys

     113(q)                           quit (when in multi-command mode)
     114(r) <comm>[,<asnum>[,<file>]] get routes for community from special <file>.
                                      optionally, get only those for specified <asnum>.
                                      If no file specified, looks in /f/rrdb/guarded/users/<comm> .
                                      The format is:
                                         AS<num> <route1> <route2> ...
                                         ...
     115(s) <sourcedb>,...            use only <sourcedb's>, eg MERITRR,RIPE,ISITEST
     116(t) [<as>]                    Return all m:a[(n)] tokens from av: lines in current source dbs.
                                      if <as> present, return only tokens with that in them.  
EOF
}

#########################################################################################

sub Examples {
print <<"EOF";
Examples:

1. To start the server as a whois daemon, rebuilding indexes, as root enter:

   $0 -D -P 43 -N -SMERITRR,PRDB,RIPE -C/f/rrdb/dbase-beta/conf -f/f/rrdb/bin/radbserver.indexes.Prod &

   The indexes are built from the three listed sources and placed in the path specified by -f.
   Note that a client may select other sources, but unless the indexes for those
   other source exist, indexed queries will fail for those other sources.
   (Non-indexed queries will work, however.)
   Thus its a good idea to have indexes for all possible sources.

2. To use whois to get the entry for 35/8 in source PRDB:

   whois -h toad.merit.edu -- -s PRDB 35/8

   Note this assumes the radbserver is running on toad!

3. To use whois to get the as-in lines for AS237:

   whois -h toad.merit.edu \!eas237

   The \! is to tell tcsh to not interpret ! as an event.
   This would return something like:

       A135
       Bfrom AS690 1 accept AS690
       Bfrom AS266 1 accept {192.68.143/24, 128.146/16, 131.167/16, 140.254/16,131.103/16}
       Bfrom AS233 1 accept AS233
       C1

   The first characters are ascii forms of protocol-return codes.
   The first line says '135 bytes coming'; the B lines are as-in lines; the C line
   is end-of-data, and it says there is a different answer in one of the source databases
   (in one of the sources specified when the daemon was started).

4. To use telnet to get the same answer:

   telnet toad.merit.edu 43
   !eas237

5. To enter prompting mode, using existing index files in ./ directory:

   $0 -p -SMERITRR,PRDB,RIPE,TESTRR,ISITEST -C./conf -f./

   At the prompt enter whois or !<protocolcmd> commands, or h for help.
   Also enter !! to enter multi-query mode, followed by 
   <protocol-cmd> lines followed by a <quit-protocol> command.

EOF
}

1;
