SpaceKit Documentation Series B. Burdick Invisible Worlds, Inc. April 2000 Blocks SpaceKit for Perl Abstract The Blocks SpaceKit for Perl is a software development kit that implements the Blocks eXtensible eXchange Protocol (BXXP[1]) in Perl. The SpaceKit provides tools to access existing Blocks servers as well as providing a framework for developing Blocks clients and servers using Perl. To subscribe to the Blocks discussion list, send e-mail[6]; there is also a developers' site[7]. Burdick [Page 1] Technical Memo Blocks SpaceKit for Perl April 2000 Table of Contents 1. What Do I Need To Use The Blocks SpaceKit For Perl? . . . 3 1.1 Additional Documentation . . . . . . . . . . . . . . . . . 3 2. Example Client Applications . . . . . . . . . . . . . . . 3 2.1 Blocks Information Groper (big.pl) . . . . . . . . . . . . 3 2.1.1 Search Operation . . . . . . . . . . . . . . . . . . . . . 3 2.1.2 Fetch Operation . . . . . . . . . . . . . . . . . . . . . 4 2.1.3 Store Operation . . . . . . . . . . . . . . . . . . . . . 5 2.1.3.1 Store create . . . . . . . . . . . . . . . . . . . . . . . 5 2.1.3.2 Store delete . . . . . . . . . . . . . . . . . . . . . . . 5 2.1.3.3 Store update . . . . . . . . . . . . . . . . . . . . . . . 5 2.1.3.4 Store write . . . . . . . . . . . . . . . . . . . . . . . 5 2.2 BXXP Ping (bxxpng.pl) . . . . . . . . . . . . . . . . . . 5 2.2.1 BXXPng echo . . . . . . . . . . . . . . . . . . . . . . . 6 2.2.2 BXXPng sink . . . . . . . . . . . . . . . . . . . . . . . 6 3. Example Server Implementation (bxxd.pl) . . . . . . . . . 6 3.1 Configuration . . . . . . . . . . . . . . . . . . . . . . 6 3.1.1 Configuration File Format . . . . . . . . . . . . . . . . 6 3.1.2 Running bxxd.pl from INETD . . . . . . . . . . . . . . . . 8 3.1.3 Running bxxd.pl from the Command Line . . . . . . . . . . 8 3.1.4 Simple Authentication and Authorization Layer (SASL) . . . 8 3.2 A Complete Module Example For The Impatient . . . . . . . 9 3.2.1 Profile Definition . . . . . . . . . . . . . . . . . . . . 9 3.2.2 Module Structure . . . . . . . . . . . . . . . . . . . . . 9 3.2.2.1 Module boot . . . . . . . . . . . . . . . . . . . . . . . 9 3.2.2.2 Module info . . . . . . . . . . . . . . . . . . . . . . . 10 3.2.2.3 Module init . . . . . . . . . . . . . . . . . . . . . . . 10 3.2.2.4 Module exch . . . . . . . . . . . . . . . . . . . . . . . 11 3.2.2.5 Module fin . . . . . . . . . . . . . . . . . . . . . . . . 11 3.2.2.6 Module version . . . . . . . . . . . . . . . . . . . . . . 12 3.3 Utilities . . . . . . . . . . . . . . . . . . . . . . . . 12 3.3.1 SASL Administration Tool . . . . . . . . . . . . . . . . . 12 References . . . . . . . . . . . . . . . . . . . . . . . . 13 Author's Address . . . . . . . . . . . . . . . . . . . . . 14 A. BXXD Configuration DTD . . . . . . . . . . . . . . . . . . 14 B. Blocks Public License . . . . . . . . . . . . . . . . . . 16 Burdick [Page 2] Technical Memo Blocks SpaceKit for Perl April 2000 1. What Do I Need To Use The Blocks SpaceKit For Perl? SpaceKit requirements: Perl version 5.004 or later. Additional Perl modules required by the SpaceKit include: o Date::Format o Digest::MD5 o IO::Scalar o MIME::Base64 o MIME::Lite o MIME::Parser o Time::HiRes o XML::Parser Additional Perl modules required by the SpaceKit client and server example applications: o App::Config o NetServer::Generic o XML::Simple All of the above modules should be available from your nearest CPAN[8] site. 1.1 Additional Documentation Additional documentation on the Blocks protocol is available at: http://xml.resource.org/profiles/BXXP/bxxp.html[1] http://xml.resource.org/profiles/SEP/sep.html[2] 2. Example Client Applications Example client applications are located in the top-level examples/client directory. 2.1 Blocks Information Groper (big.pl) Implements the basic client (mixer) interface. The search, fetch, and store mixer operations are supported. 2.1.1 Search Operation Returns a list of valid "name" attributes (e.g., "doc.rfc.2629") matching the search criteria. These names are suitable as arguments to the fetch operation. Burdick [Page 3] Technical Memo Blocks SpaceKit for Perl April 2000 % perl big.pl -server sqa.invisible.net search "mrose@" doc.rfc.2629 See SEP[2] for further details on the set-union specification used by the search operation. 2.1.2 Fetch Operation Fetch the contents of the specified block to standard output. % perl big.pl -server sqa.invisible.net fetch doc.rfc.2629 Writing I-Ds and RFCs using XML Invisible Worlds, Inc.
660 York Street San Francisco CA 94110 US +1 415 695 3975 mrose@not.invisible.net http://invisible.net/
 General RFC Request for Comments I-D Internet-Draft XML Extensible Markup Language Burdick [Page 4] Technical Memo Blocks SpaceKit for Perl April 2000 2.1.3 Store Operation Store the specified block using content from standard input. Four modes of store operation are available: create, delete, update, and write. This implementation of store expects to get its block content from standard input. 2.1.3.1 Store create Create a new block, returning an error if the block already exists. % perl big.pl -server sqa.invisible.net store test.yoursubtree test.yoursubtree.2629 create < 2629.xml 2.1.3.2 Store delete Delete the specified block, returning an error if the block does not exist. This operation only requires the block name, so a simplified XML input can be provided (e.g., ). % perl big.pl -server sqa.invisible.net store test.yoursubtree test.yoursubtree.2629 delete < 2629.xml 2.1.3.3 Store update Update the specified block, returning an error if the block does not exist. % perl big.pl -server sqa.invisible.net store test.yoursubtree test.yoursubtree.2629 update < 2629.xml 2.1.3.4 Store write Create or update the specified block, as appropriate. % perl big.pl -server sqa.invisible.net store test.yoursubtree test.yoursubtree.2629 write < 2629.xml NOTE: It is probably not a good idea to allow non-authenticated store operations against your blocks server, which is what the above examples demonstrate. The following is a more likely example in normal use, using SASL/OTP for authentication. % perl big.pl -server sqa.invisible.net -mechanism otp -username yourusername -passphrase yourpassphrase store test.yoursubtree test.yoursubtree.2629 write < 2629.xml 2.2 BXXP Ping (bxxpng.pl) Opens a channel with the specified server and passes arbitrary text, which is then either echoed back to the client and verified to match what was sent (NULL/ECHO profile) or is simply ignored by the server (NULL/SINK profile). Burdick [Page 5] Technical Memo Blocks SpaceKit for Perl April 2000 2.2.1 BXXPng echo % perl bxxpng.pl -server sqa.invisible.net echo initializing buffer... done. ..... 5 round-trips: min/avg/max = 312.743 334.746 360.107 (ms) 3 2 2 (KB/s) 2.2.2 BXXPng sink % perl bxxpng.pl -server sqa.invisible.net sink initializing buffer... done. ..... 5 round-trips: min/avg/max = 306.301 329.171 376.339 (ms) 3 2 2 (KB/s) 3. Example Server Implementation (bxxd.pl) The example server implementation is a simple Blocks server that can be used for testing basic connectivity with Blocks client applications. It does not provide datastore support, so it is not possible to perform any of the more advanced client operations, such as: fetch, store, search, etc. The sample server does provide support for authentication for testing. The example server application is located in the top-level examples/server directory. 3.1 Configuration 3.1.1 Configuration File Format bxxd.pl requires a configuration file in order to start. The configuration file defines general server parameters as well as the available profiles and their associated parameters. The formal definition of the BXXD configuration file is available in the BXXD configuration DTD (Appendix A) Global configuration parameters: homeDirectory: all relative pathnames are relative to this directory moduleDirectory: all relative module files are relative to this directory Burdick [Page 6] Technical Memo Blocks SpaceKit for Perl April 2000 logFile: file to log events debugLevel: debug events, any of: "all", "trace", "timing", and "info" (seperated by spaces) or just "none" Per profile configuration parameters: acl: access control list for the profile authDirectory: all authentication files are relative to this directory mode: mode requested if the profile supports multiple modes of operation A typical configuration file contains the following parameters and profiles: This is a configuration file for the default port 10288. Burdick [Page 7] Technical Memo Blocks SpaceKit for Perl April 2000 3.1.2 Running bxxd.pl from INETD To run the server under the supervision of inetd, first add the following to /etc/services: bxxp 10288/tcp # Blocks eXtensible eXchange Protocol Secondly, add the following to /etc/inetd.conf (Note: this should actually be one line, but was split for readability): bxxp stream tcp nowait bxxpuser /path/to/bxxd/bin/bxxd.pl /path/to/bxxd/bin/bxxd.pl -config /path/to/bxxd/etc/bxxd-config.xml Where: 1. bxxpuser is the supervisory username of the server. 2. /path/to/bxxd/bin is the full pathname to the Blocks SpaceKit server bin directory. 3. /path/to/bxxd/etc/bxxd-config.xml is the full pathname to the server configuration file. You will need to reload inetd as super-user for the change to take effect. 3.1.3 Running bxxd.pl from the Command Line bxxd.pl can run from the command line in "stand-alone daemon" mode. Once started, it continues to run indefinitely. This mode of running is typically used for testing purposes. This example starts the server on port 12345 using the configuration file in the current directory named bxxd-config.xml: bxxd.pl -daemon -port 12345 -config bxxd-config.xml Without "-port" the server uses the default port, 10288. 3.1.4 Simple Authentication and Authorization Layer (SASL) Authentication and authorization for the Blocks server is provided via either anonymous[5] or One-Time-Password[4] (OTP) SASL[3] user profiles. The location of this user data is in the configuration file as the "authDirectory" profile parameter. It is a combination of the server "homeDirectory" and the "authDirectory" parameters if authDirectory is a relative path name. To create an anonymous or OTP user profile, see the SASL Administration utility (Section 3.3.1). Burdick [Page 8] Technical Memo Blocks SpaceKit for Perl April 2000 3.2 A Complete Module Example For The Impatient You can create your own modules by defining a new profile and implementing a new server module as well as the client using the new profile. In the example, we create a module named "reverse" that receives a server request, reverses the order of the octets in the request, and responds back to the client with the reversed results. 3.2.1 Profile Definition To access your new module, first define the new profile and its corresponding module in the configuration file for the port using the new profile: If you are using the server in stand-alone mode, you will need to restart since the configuration file loads at start time 3.2.2 Module Structure Profile modules provide a fairly simple API consisting of 6 public subroutines: boot, info, init, exch, fin, and version. 3.2.2.1 Module boot Determine if the module is run-time bootable/loadable. Returns 0 if bootable and non-zero for all other conditions. # # reverse profile boot protocol (run-time bootable?) # sub boot { my $log = shift; # clear global error indicator $! = 0; # always bootable 0; } Burdick [Page 9] Technical Memo Blocks SpaceKit for Perl April 2000 3.2.2.2 Module info Returns a list containing information about the profile, including: whether the profile provides transport security (0 or 1), a list of supported profile identities (URIs), and a list of the public methods (callbacks) for using the module. # # reverse profile info # sub info { my $log = shift; return [ 0, # profile provides transport security? (0 or 1) [ # supported profile identities (an XML DTD or URI) "http://xml.resource.org/profiles/REVERSE", ], { # public methods of this profile bootV => \&Profile::reverse::boot, initV => \&Profile::reverse::init, exchV => \&Profile::reverse::exch, finV => \&Profile::reverse::fin } ]; } 3.2.2.3 Module init Initialize the module, returning a token (hash reference) to be used by the exch and fin subroutines. Burdick [Page 10] Technical Memo Blocks SpaceKit for Perl April 2000 # # reverse profile initialisation # sub init { my $log = shift; # server's log object (reference) my $serverD = shift; # fully-qualified domain name of server my $clientA = shift; # list of client ip address, hostname, and port my $upcallV = shift; # callback for profile to upcall the server my $uri = shift; # profile URI return { log => $log }; } Although interactions between the server and the profile are synchronous, it's possible that the profile may need to originate traffic. An upcall is provided for this purpose. 3.2.2.4 Module exch Module data/message exchange subroutine. # # reverse profile data/message exchange # sub exch { my $token = shift; my $data = shift; $token->{log}->entry("DEBUG", "reverse::exch", data: ($data)") if ($debug > 1); return reverse($data); } 3.2.2.5 Module fin Perform module specific clean up operations and dissolve the token created by the module init routine. Parameters are the init token and a status indicator. The "status" parameter indicates whether the finalization is graceful ("+") or extremely prejudicial ("-"). Burdick [Page 11] Technical Memo Blocks SpaceKit for Perl April 2000 # # reverse profile finalisation # sub fin { my $token = shift; my $status = shift; 0; } 3.2.2.6 Module version Return the current module version information as module name, version and release number. E.g., Profile::reverse 1.00r1. # # library version info # sub version { return __PACKAGE__ . " " . $VERSION . "r" . $RELEASE; } 3.3 Utilities 3.3.1 SASL Administration Tool The SASL administration utility is found under the example server directory as etc/sasl-adm.pl. This utility will allow you to create, delete, list, and update the SASL anonymous and SASL OTP user accounts. Burdick [Page 12] Technical Memo Blocks SpaceKit for Perl April 2000 Usage: % etc/sasl-adm.pl [-action create|delete|list|update] [-authdir path/to/authdirectory] [-logfile path/to/logfile] [-mechanism anonymous|otp] [-version] [username] [subtree ...] where -action action to perform, defaults to create -authdir path to authentication database directory, defaults to ./auth, and will be created as needed -logfile path to log file, defaults to logs/sasl-adm.log -mechanism SASL mechanism, defaults to otp -version display application version and exit username user account to access, defaults to anonymous subtree list of subtrees user account will be given full access to, default subtree is empty and allows fetch operations on any subtree References [1] Rose, M.T., "The Blocks eXtensible eXchange Protocol", draft-mrose-blocks-protocol-02 (work in progress), April 2000. [2] Rose, M.T., "The Blocks Simple Exchange Profile", draft-mrose-blocks-exchange-01 (work in progress), April 2000. [3] Myers, J.G., "Simple Authentication and Security Layer (SASL)", RFC 2222, October 1997. [4] Newman, C. and J. G. Myers, "ACAP -- Application Configuration Access Protocol", RFC 2244, November 1997. [5] Newman, C., "Anonymous SASL Mechanism", RFC 2245, November 1997. [6] mailto:blocks-request@invisible.net [7] http://mappa.mundi.net/ [8] http://www.perl.com/CPAN/ Burdick [Page 13] Technical Memo Blocks SpaceKit for Perl April 2000 Author's Address Brad Burdick Invisible Worlds, Inc. 1179 N. McDowell Blvd Suite A Petaluma, CA 94954-6559 US EMail: bburdick@invisible.net URI: http://invisible.net/ Appendix A. BXXD Configuration DTD Appendix B. Blocks Public License Blocks Public License Copyright (c) 2000, Invisible Worlds, Inc. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: o Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. o Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. o Neither the name, trademarks, or tradenames of Invisible Worlds, Inc., nor the names, trademarks, or tradenames of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INVISIBLE WORLDS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. Burdick [Page 16]