|
I am working with a team at IBM Almaden Research, and we are currently
developing an adminstrative API for AFS. We would like feedback from the
community concerning this endeavor. If you have some time, please look it
over and let us know what you think about it, what else you might like to see
included, and/or what doesn't make sense about it to you. Below is a
link to the header file that describes the API, as well as a few paragraphs
describing this effort and laying out exactly what we're trying to do (which are
also included in the header file linked below). Thanks for any help
anyone can give.
Jeremy Stribling
Header file:
This is a rough draft of an API I am designing for an AFS
administration library. The goal of this
library is to provide a simple but powerful interface for programmers
to the administrative
functionality of AFS. I have designed it to build on top of the
existing AFS administrative library,
libadmin. libadmin is powerful, but a little too low-level than
necessary, and is also missing some
potentially useful functionality. It is the intention of this API to
provide a higher-level ability to
administer AFS. It very closely follows the design of the libadmin
API, but most of the ideas for method
functionality were inspired by the AFS Control Center, an NT AFS
administration application. Essentially,
I hope that this API can be used by programmers to build other such
administration applications more easily
than with the tools that already exist.
The seed for this API was planted when we here in the Ufiler Group at
IBM decided to look into creating
an AFS administration tool for the web in Java. We decided that we'd
start by building an interface to
the AFS administrative capabilities in C, and then later porting it
to Java using JNI. From this came the
idea of standardizing the administrative interface to AFS, and
possibly even creating a standard admin
interface for all file systems. We realized that this is the kind of
thing that might be very beneficial
to OpenAFS developers, and would like to gather comments from the
open source community while we continue
with our development of our own adminstrative tool. Later down the
line we are planning to release a
Java version of this interface as well, since many of its strengths
seem to lie in it's organizational
and object-oriented type design. libadmin, as mentioned previosuly,
is very useful for low-level experienced
programmers with a C mindset, but may require too much knowledge and
effort for newbie programmers or those
with a Java/OO mindset.
One example of how this API is at a higher level and easier to use
than the libadmin API is the get and
set accessor functions. In libadmin, the user must use structs to
view and set most properties, which
necessitates studying the structure of the data closely, dealing with
extra data that the user's not
interested in, etc. This administration API has simple accessor
functions that serve this purpose, providing
a much cleaner interface. Another example is the refresh capabilities
of this API. Simply by calling one
refresh function, the user can update all of the information about a
certain cell, server, etc, instead
of going through all the many calls that would be necessary for a
user who used libadmin to maintain
a personal cache of information. This simplifies the responsibilities
of the user greatly and speeds
things up on the programming end. A third is functions such as
assadm_Cell_UnlockAllVolumes, which of
course unlocks all volumes in a cell. To use libadmin to do this
requires making a loop and calling
a function for all the objects individually. I imagine the underlying
implementation of this API will
do something similar, but I believe it is much easier at a higher
level to have a single function
to do this for you.
A good number of the functions correspond directly with a function in
the libadmin library.
The reason for having these functions at all is mainly to create a
consistent naming convention for all
the functions in the API, to make it easier to use and understand. I
feel that the grouping and naming
conventions in libadmin tend to be confusing and finding a function
with a specific functionality may
require a great deal of research. Later, I plan to turn a lot of
these functions into macros to address
any efficiency problems, but for now I view this header file as
documentation, not necessarily a final
implementation, mainly used to solicit comments about the
organization and functionality of the API.
There is probably a great deal of functionality missing here that is
possible to obtain (there are
definitely a lot of libadmin functions I have not written
corresponding functions for here), so
I would like feedback on what people would like to see
included.
Brief Overview of using this API:
Using this API is fairly simple. The basic steps are outlined
below.
1) Call the afsadm_General_Init function, which performs basic
initialization routines
necessary before any other calls to this API.
2) Call the afsadm_Cell_KlogToCell function. This will log the given
user into the given cell,
obtaining a token. This token will be stored internally in the API.
You can obtain its
expiration time by using the afsadm_Cell_TokenExpires()
function.
3) Now you can call any of the other API functions to perform
administrative tasks in this cell,
granted that the user you logged in as has those administrative
privileges. These API
functions are broken up into several types:
- afsadm_General*():
These functions perform administrative tasks and obtain information
at a general level.
For example, you can create a afsadm_nameArray for server names using
afsadm_General_CreateNameArray.
- afsadm_Cell*():
These functions perform administrative tasks and obtain information
at a cell level.
For example, you can obtain a list of a volumes in a Cell through the
afsadm_Cell_GetVolumeNames
function.
- afsadm_Volume*():
These functions perform administrative tasks and obtain information
at a volume level.
For example, you can lock a volume with the afsadm_Volume_Lock
function.
- afsadm_Partition*():
These functions perform administrative tasks and obtain information
at a partition level.
For example, you can salvage all the volumes on a particular
partition with the
afsadm_Partition_SalvageVolumes function.
- afsadm_Process*():
These functions perform administrative tasks and obtain information
at a process level.
For example, you can start a process with the afsadm_Process_Start
function.
- afsadm_Server*():
These functions perform administrative tasks and obtain information
at a server level.
For example, you can backup the volumes on a particular server with
the afsadm_Server_BackupAllVolumes
function.
- afsadm_User*():
These functions perform administrative tasks and obtain information
at a user level.
For example, you can create a new user with the afsadm_User_Create
function.
- afsadm_Group*():
These functions perform administrative tasks and obtain information
at a group level.
For example, you can obtain a list of all the members of a group with
the afsadm_Group_GetGroupMemberNames
function.
The first time you access information about a particular object (such
as a volume or a cell), the API will
cache all the information about that object in an internal data
structure. If, at a later time, you wish
to view the updated information for this object, you can use a
Refresh function (there is a Refresh function
for each of the above types). This will refresh the API's internal
data structure. Also, be sure to
check the afs_status_p after returning from a function if the
function's return code indicates it
was not successful. This will give you information as to why the
operation failed (NOTE: the
values of the afs_status_p have not yet been designed. They will be
at some point in the future.)
4) Once you're all done with a cell, be sure to call the
afsadm_Cell_UnlogFromCell function, to
help avoid any unpleasant side effects.
That's all there is to it. Enjoy!
A few notes about this API so far:
OBTAINING LISTS:
- Whenever there is a list of names to be obtained, for example the
names of all volumes in a cell,
I chose to pass the names of the volumes back in an array, instead of
using an iterator to scroll
through them. I feel this gives the user more control over them, and
creates a cleaner interface
for the programmer. The user can allocate what's called a "name
array" using afsadm_General methods,
specifying how many names to allocate for the array, and then pass
this array as an argument into
the appropriate listing method. The array, now containing a list of
all the names, will be returned, as
will the number of names contained in that array (i.e. the size of
the array). If the space allocated
for the array is not enough to contain the entire number of names,
the status variable will indicate this,
and the return code of the function will contain a non-zero number
indicating how much of the information
was actually returned. The same listing method may then be called
again, this time using the return code from
the previous call as one of the arguments (the num* argument, for
example numServers for the
afsadm_Cell_GetServerNames method), and then the remaining names that
were not listed during the last call
will be returned in the name array. This process can be repeated as
many times as necessary until all the
names have been returned, or at least as many as the user desired.
The implementation of these listing
methods should make efficient use of caching techniques to make this
a reasonable solution.
ACCESSOR FUNCTIONS:
- For accessing properties of certain entities, for example the
number of consecutive failed password
attempts before locking out a certain user, I wrote get and set
accessor functions rather than having
information contained in a struct. This way the user once again has a
clean interface to the information,
and the implementor of the API can freely change the way this
information is stored without disturbing
the user.
LIMITED OPTIONS:
- In a few instances, such as in the salvager function, there were a
great deal more options available
than I included in the API. I did this for ease of use, but it may
limit the functionality of the API
more than desired. If, at a later date, it is decided that more
options should be included, we can easily
edit these signatures, or add signatures with more advanced
options.
VOLUME IDS:
- Similarly, at the moment all functions dealing with volumes are
accessed using the string of the volume
name. We might want to add signatures for the same functions, except
using the volume id to identify
the volumes instead.
VLDB:
I did not include any functions to access directly the VLDB, mostly
because this was not a part of the
Control Center and I wasn't sure whether or not it was desired.
FILE LEVEL ADMINISTRATION:
- I also didn't really add any functionality for file-level
administration yet. The libadmin library
does not really include functions for doing this, and I am at this
time unclear how to go about
writing those functions, so for the time being I left out the
signatures.
ERROR CODES:
- I have not written any sort of error codes as of
yet, but I imagine they will mimic the
libadmin error codes very closely.
That's all for now. Much thanks to Shyh-Wei Luan and Jeff Riegel for their
collaborative assistance
in the development of this project. If you have any
questions/comments/feedback, feel free to
contact me by email: [EMAIL PROTECTED].
|
- Re: [OpenAFS-devel] Administrative API for AFS Jeremy Stribling
- Re: [OpenAFS-devel] Administrative API for AFS Nathan Neulinger
