The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

AFS - Perl interface to AFS programming APIs

VERSION

This document describes the AFS module bundle (Version 2.6.4)

COMPATIBILITY

This release does NOT support any features and interfaces from version 1.

DESCRIPTION

The AFS module bundle is a dynamically loadable (where available) extension to Perl. It gives the AFS user and administrator access to most of the AFS programming APIs, allowing you to make these calls directly from Perl, rather than processing the output of a command.

The AFS module bundle is a thin layer above the low-level AFS APIs. When possible, function names are similar to the actual API names, or to the AFS command suite names. The ordering of function parameters is not always the same though.

The AFS module bundle includes the following features:

  • Access to Basic Overseer Server routines

    Methods that deal with the Basic Overseer Server (i.e, the bos command suite). See AFS::BOS.

  • Access to Volume Server routines

    Methods that deal with the Volume Server (i.e, part of the vos command suite). See AFS::VOS.

  • Access to Volume Location Server routines

    Methods that deal with the Volume Location Server (i.e, part of the vos command suite). See AFS::VLDB.

  • Access to File Server routines

    Functions that deal with the File Server (i.e, part of the fs command suite). See AFS::FS.

  • Access to Cache Manager routines

    Functions that deal with the Cache Manager (i.e, part of the fs command suite). See AFS::CM.

  • Managing Access Control Lists

    Methods to control access to directories and all of their files. (i.e, part of the fs command suite). See AFS::ACL.

  • Manipulations of the Cell Configuration

    Functions that deal with Cell Configurations (i.e, part of the fs command suite). See AFS::CELL.

  • Access to Protection Server routines

    Methods that deal with the Protection Server (i.e, the pts command suite). See AFS::PTS.

  • Access to the Authentication Server routines

    Methods that deal with the Authentication Server (i.e, the kas command suite). See AFS::KAS.

  • Access to the AFS structure ktc_token

    Methods that deal with token management in the Kernel Token Cache (KTC) (i.e, the tokens command). See AFS::KTC_TOKEN.

  • Access to the AFS structure ktc_principal

    Methods that deal with principals related to tokens. See AFS::KTC_PRINCIPAL.

  • Access to the AFS structure ktc_encryptionkey

    Methods that deal with encryption keys related to tokens. See AFS::KTC_EKEY.

  • Access to shared utility routines

    Utility functions for the AFS module bundle which are not part of any AFS command suite (i.e, the setpag command). See AFS::Utils.

  • Access to basic AFS functions and to AFS error codes

    Basic functions like raising a Perl exception when any AFS function call fails (useful for debugging) or retrieving the status value of the last AFS function call. See AFS::Base.

PREREQUISITES

Perl v5.10.0 or newer
OpenAFS system libraries
OpenAFS header files

SEE ALSO

OpenAFS documentations
OpenAFS source tree
AFS command suites (fs, pts, kas, bos, and vos)

CAVEATS

These modules and their POD documentations have been written with the help of the AFS source code, the AFS manuals, and the 'ancient' AFS Programmer's Reference documentation. Unfortunately nearly no documentation was available for the interfaces to the AFS structures ktc_token, ktc_principal, and ktc_encryptionkey. Therefore these modules are not very well documented.

CURRENT AUTHOR

Norbert E. Gruener <nog@MPA-Garching.MPG.de>

AUTHOR EMERITUS

Roland Schemers <schemers@slapshot.stanford.edu>

CREDITS

Thank you to (in chronological order):

Lawrence Greenfield - for his update in the AFS.xs file

Alf Wachsmann - for his bug report on the function "setquota"

Gerhard Gonter - for his configuration report for rs_aix32

Peter Scott - for his improvement on ACL->keys and ACL->nkeys

Thomas M. Payerle - for his configuration report for alpha_dux40

Wolfgang Friebel - for his bug report on the functions "lsmount" and "rmmount"

Alf Wachsmann - for his patches for the XS code and his excellent ideas about the Makefile.PL

Wolfgang Friebel - for his bug reports on version 2.0

James E. Flemer - for his new method AFS::KTC_TOKEN->FromString

Phil Moore - for his improvements of the Makefile.PL

Peter Scott - for his bug report on the method "pts->id" and for his "Sun" patches for the Makefile.PL

Nathan Neulinger - for his improvements of the Makefile.PL

Bernard Antoine - for his bug report on a memory leak in the method "AFS::ACL->retrieve".

Peter Scott - for his bug report on a memory leak in the function "getvolstats"

Peter Scott - for his bug report on the function AFS::constant

Venkata Phani Achanta - for his improved test drivers for several modules

David R. Boldt - for his bug report on an undefined "typemap" entry

Alf Wachsmann and Venkata Phani Achanta - for their implementation of the BOS, VOS, and VLDB modules

Phil Moore - for his bug report on Itanium ia64 platform

Frank Burkhardt and David Miller - for their problem reports on Perl "unthreaded" version within the Debian "unstable" distribution

Pierre-Yves Fontaniere - for his configuration report for rs_aix51

Chaskiel M Grundman and Derrick J Brashear - for their valuable information about threaded OpenAFS libraries

Russ Allbery - for his improvements of the threaded case Makefile.PL

Yannick Bergeron - for his corrections for the AFS::KTC_TOKEN documentation

Mike Polek - for his patch for the AFS::FS::getquota function

Peter Scott - for his problem report on AFS::VOS->listvolume and for his improvements of the AFS::FS POD documentation

Wolfgang Friebel - for his improvements of the AFS POD documentation

Joe Buehler - for his problem report on the installation step and his patch for the AFS::BOS test driver

Craig Huckabee - for his problem report on the compile step with OpenAFS 1.4.2 and for his patch for the internal BOS constructor

Wolfgang Friebel - for his patch for the Makefile.PL

Alessio Rocchi - for his bug reports on AFS::VOS->listvldb, on AFS::VLDB->listaddr, and on AFS::VOS->listvol

Ken Dreyer - for his problem report on the compile step with OpenAFS newer than 1.4.4

Frank Burkhardt - for his problem report on using Perl 5.10.0

Alessio Rocchi - for his bug report on AFS::VLDB->listaddr

Yannick Bergeron - for his problem reports on AFS::KAS->getentry and on the src/Makefile.PL

Sergio Gelato - for his problem report on AFS::VLDB->listvldb

Roman Mainer - for his problem report on AFS::VLDB->listvldbentry

Stephen Quinney - for his patches for several AFS::BOS methods

Rainer Laatsch - for his problem reports on the script SetToken and on the src/Makefile.PL

Michael Meffie - for his problem report on the AFS::VOS->create

Russ Allbery - for his collected patches for the src/Makefile.PL and for several AFS::BOS methods

Christof Hanke - for his collected patches to remove lots of compiler warnings

Bob Harold - for his problem report about finding out the AFS sysname

Michael Meffie - for his problem report on leaks in the AFS::PTS, AFS::VOS, AFS::VLDB, and AFS::BOS modules and for his patches

Andrew Deason - for his problem report and his improvements on AFS::ACL::cleanacl

Hans-Werner Paulsen - for his improvement request on AFS::VOS->listvolume

Wolfgang Friebel - for his improvement request on AFS::VOS->dump

COPYRIGHT AND LICENSE

 Copyright (c) 2001-2012 Norbert E. Gruener <nog@MPA-Garching.MPG.de>.
 All rights reserved.

 Copyright (c) 1994 Board of Trustees, Leland Stanford Jr. University.
 All rights reserved.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

The original module is covered by the following copyright:

Copyright (c) 1994 Board of Trustees, Leland Stanford Jr. University

Redistribution and use in source and binary forms are permitted provided that the above copyright notice and this paragraph are duplicated in all such forms and that any documentation, advertising materials, and other materials related to such distribution and use acknowledge that the software was developed by Stanford University. The name of the University may not be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

DOCUMENT VERSION

Revision $Rev: 1154 $