Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy
	http://www.oracle.com/technology/documentation/index.html   |   Site Map   |   Search   |   PDF Files   |   Contact   |   Glossary
Tuxedo Doc Home   |   Reference   |   Topic List   |   Previous   |   Next   |   Contents

   BEA Tuxedo File Formats and Data Descriptions Reference

ACL_MIB - Management Information Base for ACLs

#include <fml32.h>
#include <tpadm.h>

The BEA Tuxedo MIB defines the set of classes through which Access Control Lists (ACLs) may be managed. A BEA Tuxedo configuration with SECURITY set to USER_AUTH, ACL, or MANDATORY_ACL must be created before accessing or updating these classes. ACL_MIB(5) should be used in combination with the generic MIB reference page MIB(5) to format administrative requests and interpret administrative replies. Requests formatted as described in MIB(5) using classes and attributes described in this reference page may be used to request an administrative service using any one of a number of existing ATMI interfaces in an active application. ACL_MIB(5) consists of the following classes.

ACL_MIB Classes

Class Name	Attribute
T_ACLGROUP	ACL group
T_ACLPERM	ACL permissions
T_ACLPRINCIPAL	ACL principal (users or domains)

Each class description section has four subsections:

Overview

High level description of the attributes associated with the class.

Attribute Table

A table that lists the name, type, permissions, values and default for each attribute in the class. The format of the attribute table is described below.

Attribute Semantics

Tells how each attribute should be interpreted.

Limitations

Limitations in the access to and interpretation of this class.

As described above, each class that is a part of this MIB is defined below in four parts. One of these parts is the attribute table. The attribute table is a reference guide to the attributes within a class and how they may used by administrators, operators and general users to interface with an application. There are five components to each attribute description in the attribute tables: name, type, permissions, values and default. Each of these components is discussed in MIB(5).

MIB(5) defines the generic TA_FLAGS attribute which is a long containing both generic and component MIB specific flag values. At this time, there are no ACL_MIB(5) specific flag values defined.

The field tables for the attributes described in this reference page are found in the file udataobj/tpadm relative to the root directory of the BEA Tuxedo system software installed on the system. The directory ${TUXDIR}/udataobj should be included by the application in the colon separated list specified by the FLDTBLDIR environment variable and the field table name tpadm() should be included in the comma separated list specified by the FIELDTBLS environment variable.

Access to the header files and field tables for this MIB is provided only at sites running BEA Tuxedo Release 6.0 and later, both native and Workstation.

The T_ACLGROUP class represents groups of BEA Tuxedo application users and domains.

ACL_MIB(5): T_ACLGROUP Class Definition Attribute Table

Attribute	Type	Permissions	Values	Default
TA_GROUPNAME( r )( * )	string	rU-------	string[1..30]	N/A
TA_GROUPID( k )	long	rw-------	0 <= num <16,384	lowest id
TA_STATE	string	rw-------	GET: "INA" SET: "{NEW | INV}"	N/A N/A

( k ) - GET key field
( r ) - Required field for object creation (SET TA_STATE NEW)
( * ) - GET/SET key, one or more required for SET operations

TA_GROUPNAME: string[1..30]

Logical name of the group. A group name is a string of printable characters and cannot contain a pound sign, comma, colon, or newline.

TA_GROUPID: 0 <= num < 16,384

Group identifier associated with this user. A value of 0 indicates the default group "other." If not specified at creation time, it defaults to the next available (unique) identifier greater than 0.

TA_STATE:

GET: {VALid}

A GET operation will retrieve configuration information for the selected T_ACLGROUP object(s). The following states indicate the meaning of a TA_STATE returned in response to a GET request.

VALid

T_ACLGROUP object is defined and inactive. Note that this is the only valid state for this class. ACL groups are never active.

SET: {NEW | INValid}

A SET operation will update configuration information for the selected T_ACLGROUP object. The following states indicate the meaning of a TA_STATE set in a SET request. States not listed may not be set.

NEW	Create T_ACLGROUP object for application. State change allowed only when in the INValid state. Successful return leaves the object in the VALid state.
unset	Modify an existing T_ACLGROUP object. This combination is not allowed in the INValid state. Successful return leaves the object state unchanged.
INValid	Delete T_ACLGROUP object for application. State change allowed only when in the VALid state. Successful return leaves the object in the INValid state.

A user can be associated with exactly one ACL group. For someone to take on more than one role or be associated with more than one group, multiple user entries must be defined.

The T_ACLPERM class indicates what groups are allowed to access BEA Tuxedo System entities. These entities are named via a string. The names currently represent service names, event names, and application queue names.

ACL_MIB(5): T_ACLPERM Class Definition: Attribute Table

Attribute	Type	Permissions	Values	Default
TA_ACLNAME(r)(*)	string	rw-------	string[1. .30]	N/A
TA_ACLTYPE(r)(*)	string	rw-------	"ENQ | DEQ | SERVICE | POSTEVENT"	N/A
TA_ACLGROUPIDS	string	rw-------	string	N/A
TA_STATE	string	rw-------	GET: "INA" SET: "{NEW | INV}"	N/A N/A

( r ) - Required field for object creation (SET TA_STATE NEW)

( * ) - GET/SET key, one or more required for SET operations

TA_ACLNAME: string

The name of the entity for which permissions are being granted. The name can represent a service name, an event name, and/or a queue name. An ACL name is a string of printable characters and cannot contain a colon, pound sign, or newline.

TA_ACLTYPE: ENQ | DEQ | SERVICE | POSTEVENT

The type of the entity for which permissions are being granted.

TA_ACLGROUPIDS: string

A comma separated list of group identifiers (numbers) that are permitted access to the associated entity. The length of string is limited only by the amount of disk space on the machine.

TA_STATE:

GET: {VALid}

A GET operation will retrieve configuration information for the selected T_ACLPERM object(s). The following states indicate the meaning of a TA_STATE returned in response to a GET request.

VALid

T_ACLPERM object is defined and inactive. Note that this is the only valid state for this class. ACL permissions are never active.

SET: {NEW | INValid}

A SET operation will update configuration information for the selected T_ACLPERM object. The following states indicate the meaning of a TA_STATE set in a SET request. States not listed may not be set.

NEW	Create T_ACLPERM object for application. State change allowed only when in the INValid state. Successful return leaves the object in the VALid state.
unset	Modify an existing T_ACLPERM object. This combination is not allowed in the INValid state. Successful return leaves the object state unchanged.
INValid	Delete T_ACLPERM object for application. State change allowed only when in the VALid state. Successful return leaves the object in the INValid state.

Permissions are defined at the group level, not on individual user identifiers.

The T_ACLPRINCIPAL class represents users or domains that can access a BEA Tuxedo application and the group with which they are associated. To join the application as a specific user, it is necessary to present a user-specific password.

ACL_MIB(5): T_ACLPRINCIPAL Class Definition Attribute Table

Attribute	Type	Permissions	Values	Default
TA_PRINNAME( r )( * )	string	rU-------	string[1. .30]	N/A
TA_PRINCLTNAME( k )	string	rw-------	string[1. .30]	"*"
TA_PRINID( k )	long	rU-------	1 <= num < 131,072	lowest id
TA_PRINGRP( k )	long	rw-------	0 <= num < 16,384	0
TA_PRINPASSWD	string	rwx------	string	N/A
TA_STATE	string	rw-------	GET: "INA" SET: "{NEW | INV}"	N/A N/A

( k ) - GET key field
( r ) - Required field for object creation (SET TA_STATE NEW)
( * ) - GET/SET key, one or more required for SET operations

TA_PRINNAME: string

Logical name of the user or domain (a principal). A principal name is a string of printable characters and cannot contain a pound sign, colon, or newline.

TA_PRINCLTNAME: string

The client name associated with the user. It generally describes the role of the associated user, and provides a further qualifier on the user entry. If not specified at creation time, the default is the wildcard asterisk (*). A client name is a string of printable characters and cannot contain a colon, or newline.

TA_PRINID: 1 <= num < 131,072

Unique user identification number. If not specified at creation time, it defaults to the next available (unique) identifier greater than 0.

TA_PRINGRP: 0 <= num < 16,384

Group identifier associated with this user. A value of 0 indicates the default group "other." If not specified at creation time, the default 0 is assigned.

TA_PRINPASSWD: string

TA_STATE :

GET: {VALid}

A GET operation will retrieve configuration information for the selected T_ACLPRINCIPAL object(s). The following states indicate the meaning of a TA_STATE returned in response to a GET request.

VALid

T_ACLPRINCIPAL object is defined and inactive. Note that this is the only valid state for this class. ACL principals are never active.

SET: {NEW | INValid}

A SET operation will update configuration information for the selected T_ACLPRINCIPAL object. The following states indicate the meaning of a TA_STATE set in a SET request. States not listed may not be set.

NEW	Create T_ACLPRINCIPAL object for application. State change allowed only when in the INValid state. Successful return leaves the object in the VALid state.
unset	Modify an existing T_ACLPRINCIPAL object. This combination is not allowed in the INValid state. Successful return leaves the object state unchanged.
INValid	Delete T_ACLPRINCIPAL object for application. State change allowed only when in the VALid state. Successful return leaves the object in the INValid state.

A user or domain can be associated with exactly one ACL group. For someone to take on more than one role or be associated with more than one group, multiple principal entries must be defined.

There are two general types of errors that may be returned to the user when interfacing with ACL_MIB(5). First, any of the three ATMI verbs (tpcall(), tpgetrply() and tpdequeue()) used to retrieve responses to administrative requests may return any error defined for them. These errors should be interpreted as described on the appropriate reference pages.

If, however, the request is successfully routed to a system service capable of satisfying the request and that service determines that there is a problem handling the request, then failure may be returned in the form of an application level service failure. In these cases, tpcall() and tpgetrply() will return an error with tperrno() set to TPESVCFAIL and return a reply message containing the original request along with TA_ERROR, TA_STATUS and TA_BADFLD fields further qualifying the error as described below. When a service failure occurs for a request forwarded to the system through the TMQFORWARD(5) server, the failure reply message will be enqueued to the failure queue identified on the original request (assuming the -d option was specified for TMQFORWARD).

When a service failure occurs during processing of an administrative request, the FML32 field TA_STATUS is set to a textual description of the failure, the FML32 field TA_ERROR is set to indicate the cause of the failure as indicated below. All error codes specified below are guaranteed to be negative.

The following diagnostic codes are returned in TA_ERROR to indicate successful completion of an administrative request. These codes are guaranteed to be non-negative.

[other]

Other return codes generic to any component MIB are specified in the MIB(5) reference page. These return codes are guaranteed to be mutually exclusive with any ACL_MIB(5) specific return codes defined here.

The header files and field tables defined in this reference page are available on BEA Tuxedo Release 6.0 and later. Fields defined in these headers and tables will not be changed from release to release. New fields may be added which are not defined on the older release site. Access to the AdminAPI is available from any site with the header files and field tables necessary to build a request. The T_ACLPRINCIPAL, T_ACLGROUP, and T_ACLPERM classes are new with BEA Tuxedo Release 6.0.

The existing FML32 and ATMI functions necessary to support administrative interaction with BEA Tuxedo system MIBs, as well as the header file and field table defined in this reference page, are available on all supported native and workstation platforms.

Following is a sequence of code fragments that adds a user to a group and adds permissions for that group to a service name.

The field table tpadm must be available in the environment to have access to attribute field identifiers. This can be done at the shell level as follows:

$ FIELDTBLS=tpadm 
$ FLDTBLDIR=${TUXDIR}/udataobj
$ export FIELDTBLS FLDTBLDIR

The following header files are included.

#include <atmi.h> 
#include <fml32.h>
#include <tpadm.h>

The following code fragment adds a user to the default group "other."

/* Allocate input and output buffers */ 

ibuf = tpalloc("FML32", NULL, 1000);

 obuf = tpalloc("FML32", NULL, 1000);
 
 /* Set MIB(5) attributes defining request type * 
 Fchg32(ibuf, TA_OPERATION, 0, "SET", 0);
 Fchg32(ibuf, TA_CLASS, 0, "T_ACLPRINCIPAL", 0);
 
 /* Set ACL_MIB(5) attributes */
 Fchg32(ibuf, TA_PRINNAME, 0, ta_prinname, 0);
 Fchg32(ibuf, TA_PRINID, 0, (char *)ta_prinid, 0);
 Fchg32(ibuf, TA_STATE, 0, (char *)"NEW", 0);
 
 Fchg32(ibuf, TA_PRINPASSWD, 0, (char *)passwd, 0);
 
 
 /* Make the request */
 if (tpcall(".TMIB", (char *)ibuf, 0, (char **)obuf, olen, 0) 0)  {
 fprintf(stderr, "tpcall failed: %s\en", tpstrerror(tperrno));
 if (tperrno == TPESVCFAIL) {
 Fget32(obuf, TA_ERROR, 0,(char *)ta_error, NULL);
 ta_status = Ffind32(obuf, TA_STATUS, 0, NULL);
 fprintf(stderr, "Failure: %ld, %s\en",
 ta_error, ta_status);
 }
 /* Additional error case processing */
 }

${TUXDIR}/include/tpadm.h, ${TUXDIR}/udataobj/tpadm,

tpacall(3c), tpalloc(3c), tpcall(3c), tpdequeue(3c), tpenqueue(3c), tpgetrply(3c), tprealloc(3c), Introduction to FML Functions, Fadd, Fadd32(3fml), Fchg, Fchg32(3fml), Ffind, Ffind32(3fml), MIB(5), TM_MIB(5)

Setting Up a BEA Tuxedo Application

Programming a BEA Tuxedo Application Using C

Programming a BEA Tuxedo Application Using FML