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