Networking Services Library Functions nisobjects(3NSL)
NAME
nisobjects - NIS] object formats
SYNOPSIS
cc [ flag ... ] file ... -lnsl [ library ... ]
/usr/include/rpcsvc/nisobjects.x
DESCRIPTION
Common Attributes
The NIS] service uses a variant record structure to hold the
contents of the objects that are used by the NIS] service.
These objects all share a common structure that defines a
set of attributes that all objects possess. The nisobject
structure contains the following members:
typedef char *nisname;
struct nisobject {
nisoid zooid;
nisname zoname;
nisname zoowner;
nisname zogroup;
nisname zodomain;
uintt zoaccess;
uint32t zottl;
objdata zodata;
};
In this structure, the first member zooid, is a 64 bit
number that uniquely identifies this instance of the object
on this server. This member is filled in by the server when
the object is created and changed by the server when the
object is modified. When used in conjunction with the
object's name and domain it uniquely identifies the object
in the entire NIS] namespace.
The second member, zoname, contains the leaf name of the
object. This name is never terminated with a `.' (dot).
When an object is created or added to the namespace, the
client library will automatically fill in this field and
the domain name from the name that was passed to the func-
tion.
zodomain contains the name of the NIS] domain to which
this object belongs. This information is useful when track-
ing the parentage of an object from a cache. When used in
conjunction with the members zoname and zooid, it
uniquely identifies an object. This makes it possible to
SunOS 5.11 Last change: 10 Nov 2005 1
Networking Services Library Functions nisobjects(3NSL)
always reconstruct the name of an object by using the code
fragment
sprintf(buf,"%s.%s", obj->zoname, obj->zodomain);
The zoowner and zogroup members contain the NIS] names of
the object's principal owner and group owner, respectively.
Both names must be NIS] fully qualified names. However,
neither name can be used directly to identify the object
they represent. This stems from the condition that NIS]
uses itself to store information that it exports.
The zoowner member contains a fully qualified NIS] name of
the form principal.domain. This name is called a NIS] prin-
cipal name and is used to identify authentication informa-
tion in a credential table. When the server constructs a
search query of the form
[cname=principal],cred.orgdir.domain.
The query will return to the server credential information
about principal for all flavors of RPC authentication that
are in use by that principal. When an RPC request is made to
the server, the authentication flavor is extracted from the
request and is used to find out the NIS] principal name of
the client. For example, if the client is using the
AUTHDES authentication flavor, it will include in the
authentication credentials the network name or netname of
the user making the request. This netname will be of the
form
unix.UID@domain
The NIS] server will then construct a query on the creden-
tial database of the form
[authname=netname,authtype=AUTHDES],cred.orgdir.domain.
This query will return an entry which contains a principal
name in the first column. This NIS] principal name is used
to control access to NIS] objects.
SunOS 5.11 Last change: 10 Nov 2005 2
Networking Services Library Functions nisobjects(3NSL)
The group owner for the object is treated differently. The
group owner member is optional (it should be the null string
if not present) but must be fully qualified if present. A
group name takes the form
group.domain.
which the server then maps into a name of the form
group.groupsdir.domain.
The purpose of this mapping is to prevent NIS] group names
from conflicting with user specified domain or table names.
For example, if a domain was called engineering.foo.com.,
then without the mapping a NIS] group of the same name to
represent members of engineering would not be possible. The
contents of groups are lists of NIS] principal names which
are used exactly like the zoowner name in the object. See
nisgroups(3NSL) for more details.
The zoaccess member contains the bitmask of access rights
assigned to this object. There are four access rights
defined, and four are reserved for future use and must be
zero. This group of 8 access rights can be granted to four
categories of client. These categories are the object's
owner, the object's group owner, all authenticated clients
(world), and all unauthenticated clients (nobody). Note
that access granted to ``nobody'' is really access granted
to everyone, authenticated and unauthenticated clients.
The zottl member contains the number of seconds that the
object can ``live'' in a cache before it is expired. This
value is called the time to live for this object. This
number is particularly important on group and directory
(domain) objects. When an object is cached, the current
time is added to the value in zottl. Then each time the
cached object is used, the time in zottl is compared with
the current time. If the current time is later than the time
in zottl the object is said to have expired and the cached
copy should not be used.
Setting the TL is somewhat of an art. You can think of it
as the ``half life'' of the object, or half the amount of
time you believe will pass before the object changes. The
benefit of setting the ttl to a large number is that the
SunOS 5.11 Last change: 10 Nov 2005 3
Networking Services Library Functions nisobjects(3NSL)
object will stay in a cache for long periods of time. The
problem with setting it to a large value is that when the
object changes it will take a long time for the caches to
flush out old copies of that object. The problems and bene-
fits are reversed for setting the time to a small value.
Generally setting the value to 43200 (12 hrs) is reasonable
for things that change day to day, and 3024000 is good for
things that change week to week. Setting the value to 0
will prevent the object from ever being cached since it
would expire immediately.
The zodata member is a discriminated union with the follow-
ing members:
zotypes zotype;
union {
struct directoryobj didata;
struct groupobj grdata;
struct tableobj tadata;
struct entryobj endata;
struct linkobj lidata;
struct {
uintt podatalen;
char *podataval;
} podata;
} objdatau;
The union is discriminated based on the type value contained
in zotype. There six types of objects currently defined in
the NIS] service. These types are the directory, link,
group, table, entry, and private types.
enum zotypes {
BOGUSOBJ = 0,
NOBJ = 1,
DIRECTORYOBJ = 2,
GROUPOBJ = 3,
TABLEOBJ = 4,
ENTRYOBJ = 5,
LINKOBJ = 6,
PRIVATEOBJ = 7
};
typedef enum zotypes zotypes;
All object types define a structure that contains data
specific to that type of object. The simplest are private
objects which are defined to contain a variable length array
SunOS 5.11 Last change: 10 Nov 2005 4
Networking Services Library Functions nisobjects(3NSL)
of octets. Only the owner of the object is expected to
understand the contents of a private object. The following
section describe the other five object types in more signi-
ficant detail.
Directory Objects
The first type of object is the directory object. This
object's variant part is defined as follows:
enum nstype {
UNKNOWN = 0,
NIS = 1,
SUNYP = 2,
DNS = 4,
X500 = 5,
DNANS = 6,
XCHS = 7,
}
typedef enum nstype nstype;
struct oarmask {
uintt oarights;
zotypes oaotype;
}
typedef struct oarmask oarmask;
struct endpoint {
char *uaddr;
char *family;
char *proto;
}
typedef struct endpoint endpoint;
struct nisserver {
nisname name;
struct {
uintt eplen;
endpoint *epval;
} ep;
uintt keytype;
netobj pkey;
}
typedef struct nisserver nisserver;
struct directoryobj {
nisname doname;
nstype dotype;
struct {
uintt doserverslen;
nisserver *doserversval;
} doservers;
uint32t dottl;
struct {
uintt doarmasklen;
oarmask *doarmaskval;
} doarmask;
SunOS 5.11 Last change: 10 Nov 2005 5
Networking Services Library Functions nisobjects(3NSL)
}
typedef struct directoryobj directoryobj;
The main structure contains five primary members: doname,
dotype, doservers, dottl, and doarmask. The information
in the doservers structure is sufficient for the client
library to create a network connection with the named server
for the directory.
The doname member contains the name of the directory or
domain represented in a format that is understandable by
the type of nameservice serving that domain. In the case of
NIS] domains, this is the same as the name that can be com-
posed using the zoname and zodomain members. For other
name services, this name will be a name that they under-
stand. For example, if this were a directory object describ-
ing an X.500 namespace that is ``under'' the NIS] directory
eng.sun.com., this name might contain ``/C=US, /O=Sun
Microsystems, /OU=Engineering/''. The type of nameservice
that is being described is determined by the value of the
member dotype.
The doservers structure contains two members.
doserversval is an array of nisserver structures;
doserverslen is the number of cells in the array. The
nisserver structure is designed to contain enough informa-
tion such that machines on the network providing name ser-
vices can be contacted without having to use a name service.
In the case of NIS] servers, this information is the name of
the machine in name, its public key for authentication in
pkey, and a variable length array of endpoints, each of
which describes the network endpoint for the rpcbind daemon
on the named machine. The client library uses the addresses
to contact the server using a transport that both the client
and server can communicate on and then queries the rpcbind
daemon to get the actual transport address that the server
is using.
Note that the first server in the doservers list is always
the master server for the directory.
The keytype field describes the type of key stored in the
pkey netobj (see /usr/include/rpc/xdr.h for a definition of
the network object structure). Currently supported types are
NISPKNONE for no public key, NISPKDH for a Diffie-
Hellman type public key, and NISPKDHEXT for an extended
SunOS 5.11 Last change: 10 Nov 2005 6
Networking Services Library Functions nisobjects(3NSL)
Diffie-Hellman public key.
The dottl member contains a copy of the zottl member from
the common attributes. This is the duplicated because the
cache manager only caches the variant part of the directory
object.
The doarmask structure contains two members. doarmaskval
is an array of oarmask structures; doarmasklen is the
number of cells in the array. The oarmask structure con-
tains two members: oarights specifies the access rights
allowed for objects of type oaotype. These access rights
are used for objects of the given type in the directory when
they are present in this array.
The granting of access rights for objects contained within a
directory is actually two-tiered. If the directory object
itself grants a given access right (using the zoaccess
member in the nisobject structure representing the direc-
tory), then all objects within the directory are allowed
that access. Otherwise, the doarmask structure is examined
to see if the access is allowed specifically for that type
of structure. This allows the administrator of a namespace
to set separate policies for different object types, for
example, one policy for the creation of tables and another
policy for the creation of other directories. See NIS](1)
for more details.
Link Objects
Link objects provide a means of providing aliases or sym-
bolic links within the namespace. Their variant part is
defined as follows.
struct linkobj {
zotypes lirtype;
struct {
uintt liattrslen;
nisattr *liattrsval;
} liattrs;
nisname liname;
}
The lirtype member contains the object type of the object
pointed to by the link. This is only a hint, since the
object which the link points to may have changed or been
removed. The fully qualified name of the object (table or
otherwise) is specified in the member liname.
SunOS 5.11 Last change: 10 Nov 2005 7
Networking Services Library Functions nisobjects(3NSL)
NIS] links can point to either other objects within the NIS]
namespace, or to entries within a NIS] table. If the object
pointed to by the link is a table and the member liattrs
has a nonzero number of attributes (index name/value pairs)
specified, the table is searched when this link is followed.
All entries which match the specified search pattern are
returned. Note, that unless the flag FOLOWLINKS is speci-
fied, the nislookup(3NSL) function will always return
non-entry objects.
Group Objects
Group objects contain a membership list of NIS] principals.
The group objects' variant part is defined as follows.
struct groupobj {
uintt grflags;
struct {
uintt grmemberslen;
nisname *grmembersval;
} grmembers;
}
The grflags member contains flags that are currently
unused. The grmembers structure contains the list of prin-
cipals. For a complete description of how group objects are
manipulated see nisgroups(3NSL).
Table Objects
The NIS] table object is analogous to a YP map. The differ-
ences stem from the access controls, and the variable sche-
mas that NIS] allows. The table objects data structure is
defined as follows:
#define TABINARY 1
#define TACRYPT 2
#define TAXDR 4
#define TASEARCHABLE 8
#define TACASE 16
#define TAMODIFIED 32
struct tablecol {
char *tcname;
uintt tcflags;
uintt tcrights;
}
typedef struct tablecol tablecol;
struct tableobj {
char *tatype;
uintt tamaxcol;
uchart tasep;
struct {
SunOS 5.11 Last change: 10 Nov 2005 8
Networking Services Library Functions nisobjects(3NSL)
uintt tacolslen;
tablecol *tacolsval;
} tacols;
char *tapath;
}
The tatype member contains a string that identifies the
type of entries in this table. NIS] does not enforce any
policies as to the contents of this string. However, when
entries are added to the table, the NIS] service will check
to see that they have the same ``type'' as the table as
specified by this member.
The structure tacols contains two members. tacolsval is
an array of tablecol structures. The length of the array
depends on the number of columns in the table; it is defined
when the table is created and is stored in tacolslen.
tamaxcol also contains the number of columns in the table
and always has the same value as tacolslen. Once the table
is created, this length field cannot be changed.
The tasep character is used by client applications that
wish to print out an entry from the table. Typically this is
either space (`` '') or colon (``:'').
The tapath string defines a concatenation path for tables.
This string contains an ordered list of fully qualified
table names, separated by colons, that are to be searched if
a search on this table fails to match any entries. This path
is only used with the flag FOLOWPATH with a nislist()
call. See nistables(3NSL) for information on these flags.
In addition to checking the type, the service will check
that the number of columns in an entry is the same as those
in the table before allowing that entry to be added.
Each column has associated with it a name in tcname, a set
of flags in tcflags, and a set of access rights in
tcrights. The name should be indicative of the contents of
that column.
The TABINARY flag indicates that data in the column is
binary (rather than text). Columns that are searchable can-
not contain binary data. The TACRYPT flag specifies that
SunOS 5.11 Last change: 10 Nov 2005 9
Networking Services Library Functions nisobjects(3NSL)
the information in this column should be encrypted prior to
sending it over the network. This flag has no effect in the
export version of NIS]. The TAXDR flag is used to tell the
client application that the data in this column is encoded
using the XDR protocol. The TABINARY flag must be specified
with the XDR flag. Further, by convention, the name of a
column that has the TAXDR flag set is the name of the XDR
function that will decode the data in that column.
The TASEARCHABLE flag specifies that values in this column
can be searched. Searchable columns must contain textual
data and must have a name associated with them. The flag
TACASE specifies that searches involving this column ignore
the case of the value in the column. At least one of the
columns in the table should be searchable. Also, the combi-
nation of all searchable column values should uniquely
select an entry within the table. The TAMODIFIED flag is
set only when the table column is modified. When
TAMODIFIED is set, and the object is modified again, the
modified access rights for the table column must be copied,
not the default access rights.
Entry Objects
Entry objects are stored in tables. The structure used to
define the entry data is as follows.
#define ENBINARY 1
#define ENCRYPT 2
#define ENXDR 4
#define ENMODIFIED 8
struct entrycol {
uintt ecflags;
struct {
uintt ecvaluelen;
char *ecvalueval;
} ecvalue;
}
typedef struct entrycol entrycol;
struct entryobj {
char *entype;
struct {
uintt encolslen;
entrycol *encolsval;
} encols;
}
The entype member contains a string that specifies the type
of data this entry represents. The NIS] server will compare
this string to the type string specified in the table object
SunOS 5.11 Last change: 10 Nov 2005 10
Networking Services Library Functions nisobjects(3NSL)
and disallow any updates or modifications if they differ.
The encols structure contains two members: encolslen and
encolsval. encolsval is an array of entrycol struc-
tures. encolslen contains a count of the number of cells
in the encolsval array and reflects the number of columns
in the table -- it always contains the same value as the
tableobj.tacols.tacolslen member from the table which
contains the entry.
The entrycol structure contains information about the
entry's per-column values. ecvalue contains information
about a particular value. It has two members: ecvalueval,
which is the value itself, and ecvaluelen, which is the
length (in bytes) of the value. entrycol also contains the
member ecflags, which contains a set of flags for the
entry.
The flags in ecflags are primarily used when adding or
modifying entries in a table. All columns that have the
flag ENCRYPT set will be encrypted prior to sending them
over the network. Columns with ENBINARY set are presumed to
contain binary data. The server will ensure that the column
in the table object specifies binary data prior to allowing
the entry to be added. When modifying entries in a table,
only those columns that have changed need be sent to the
server. Those columns should each have the ENMODIFIED flag
set to indicate this to the server.
SEE ALSO
NIS](1), nisgroups(3NSL), nisnames(3NSL),
nisserver(3NSL), nissubr(3NSL), nistables(3NSL)
NOTES
NIS] might not be supported in future releases of the
Solaris operating system. Tools to aid the migration from
NIS] to LDAP are available in the current Solaris release.
For more information, visit
http:/www.sun.com/directory/nisplus/transition.html.
SunOS 5.11 Last change: 10 Nov 2005 11
|
