1nis_objects(3NSL)    Networking Services Library Functions   nis_objects(3NSL)
2
3
4

NAME

6       nis_objects - NIS+ object formats
7

SYNOPSIS

9       cc [ flag ... ] file ... -lnsl [ library ... ]
10       /usr/include/rpcsvc/nis_objects.x
11
12

DESCRIPTION

14   Common Attributes
15       The  NIS+  service uses a variant record structure to hold the contents
16       of the objects that are used by the NIS+ service.   These  objects  all
17       share  a  common  structure  that  defines a set of attributes that all
18       objects possess.  The nis_object structure contains the following  mem‐
19       bers:
20
21         typedef   char *nis_name;
22              struct    nis_object {
23                   nis_oid        zo_oid;
24                   nis_name  zo_name;
25                   nis_name  zo_owner;
26                   nis_name  zo_group;
27                   nis_name  zo_domain;
28                   uint_t         zo_access;
29                   uint32_t       zo_ttl;
30                   objdata        zo_data;
31                 };
32
33
34
35       In  this  structure,  the  first member zo_oid, is a 64 bit number that
36       uniquely identifies this instance of the object on  this  server.  This
37       member  is  filled  in  by  the  server  when the object is created and
38       changed by the server when the object is modified. When  used  in  con‐
39       junction  with  the object's name and domain it uniquely identifies the
40       object  in the entire NIS+ namespace.
41
42
43       The second member, zo_name, contains the leaf name of the object.  This
44       name  is   never terminated with a `.' (dot). When an object is created
45       or added to the namespace, the client library will  automatically  fill
46       in  this field and the domain name from the name that was passed to the
47       function.
48
49
50       zo_domain contains the name of the  NIS+ domain to  which  this  object
51       belongs.  This  information is useful when tracking the parentage of an
52       object from a cache. When used in conjunction with the members  zo_name
53       and   zo_oid, it uniquely identifies an object.  This makes it possible
54       to always reconstruct the name of an object by using the code fragment
55
56         sprintf(buf,"%s.%s", obj->zo_name, obj->zo_domain);
57
58
59
60       The zo_owner and zo_group  members  contain  the   NIS+  names  of  the
61       object's principal owner and group owner, respectively. Both names must
62       be  NIS+ fully qualified names.  However,  neither  name  can  be  used
63       directly  to  identify  the  object they represent. This stems from the
64       condition that  NIS+ uses itself to store information that it exports.
65
66
67       The zo_owner member contains a fully qualified NIS+ name  of  the  form
68       principal.domain. This name is called a NIS+ principal name and is used
69       to identify authentication information in a credential table. When  the
70       server constructs a search query of the form
71
72         [cname=principal],cred.org_dir.domain.
73
74
75
76       The  query will return to the server credential information about prin‐
77       cipal for all flavors of RPC authentication that are  in  use  by  that
78       principal.  When  an RPC request is made to the server, the authentica‐
79       tion flavor is extracted from the request and is used to find  out  the
80       NIS+  principal name of the client. For example, if the client is using
81       the  AUTH_DES authentication flavor, it will include in the authentica‐
82       tion  credentials  the  network  name or netname of the user making the
83       request. This netname will be of the form
84
85         unix.UID@domain
86
87
88
89       The  NIS+ server will then construct a query on the credential database
90       of the form
91
92         [auth_name=netname,auth_type=AUTH_DES],cred.org_dir.domain.
93
94
95
96       This  query will return an entry which contains a principal name in the
97       first column. This NIS+ principal name is used  to  control  access  to
98       NIS+ objects.
99
100
101       The  group owner for the object is treated differently. The group owner
102       member is optional (it should be the null string if  not  present)  but
103       must be fully qualified if present. A group name takes the form
104
105         group.domain.
106
107
108
109       which the server then maps into a name of the form
110
111         group.groups_dir.domain.
112
113
114
115       The  purpose  of  this mapping is to prevent NIS+ group names from con‐
116       flicting with user specified domain or table names. For example,  if  a
117       domain was called engineering.foo.com., then without the mapping a NIS+
118       group of the same name to represent members of engineering would not be
119       possible.  The  contents  of  groups  are lists of NIS+ principal names
120       which are used exactly like  the  zo_owner  name  in  the  object.  See
121       nis_groups(3NSL) for more details.
122
123
124       The  zo_access member contains the bitmask of access rights assigned to
125       this object. There  are  four  access  rights  defined,  and  four  are
126       reserved for future use and must be zero. This group of 8 access rights
127       can be granted to four categories of client. These categories  are  the
128       object's  owner,  the  object's  group owner, all authenticated clients
129       (world),  and all unauthenticated clients (nobody).  Note  that  access
130       granted  to  ``nobody'' is really access granted to everyone, authenti‐
131       cated  and unauthenticated clients.
132
133
134       The zo_ttl member contains the number of seconds that  the  object  can
135       ``live'' in a cache before it is expired. This value is called the time
136       to live for this object. This number is particularly important on group
137       and  directory (domain) objects. When an object is  cached, the current
138       time is added to the value in zo_ttl. Then each time the cached  object
139       is  used,  the time in zo_ttl is compared with the current time. If the
140       current time is later than the time in zo_ttl the  object  is  said  to
141       have expired and the cached copy should not be used.
142
143
144       Setting  the  TTL  is  somewhat  of  an art. You can think of it as the
145       ``half life'' of the object, or half the amount  of  time  you  believe
146       will  pass before the object changes. The benefit of setting the ttl to
147       a large number is that the object will stay in a cache for long periods
148       of  time. The problem with setting it to a large value is that when the
149       object changes it will take a long time for the caches to flush out old
150       copies  of that object. The problems and benefits are reversed for set‐
151       ting the time to a small value. Generally setting the  value  to  43200
152       (12  hrs)  is reasonable for things that change day to day, and 3024000
153       is good for things that change week to  week. Setting the  value  to  0
154       will  prevent  the  object from ever being cached since it would expire
155       immediately.
156
157
158       The zo_data member is a discriminated union with the following members:
159
160         zotypes zo_type;
161              union {
162                   struct directory_obj     di_data;
163                   struct group_obj    gr_data;
164                   struct table_obj    ta_data;
165                   struct entry_obj    en_data;
166                   struct link_obj     li_data;
167                   struct {
168                              uint_t   po_data_len;
169                              char     *po_data_val;
170                   } po_data;
171                 } objdata_u;
172
173
174
175       The union is  discriminated  based  on  the  type  value  contained  in
176       zo_type.  There six types of objects currently defined in the NIS+ ser‐
177       vice. These types are the directory, link,  group,  table,  entry,  and
178       private types.
179
180         enum zotypes {
181                   BOGUS_OBJ = 0,
182                   NO_OBJ    = 1,
183                   DIRECTORY_OBJ  = 2,
184                   GROUP_OBJ = 3,
185                   TABLE_OBJ = 4,
186                   ENTRY_OBJ = 5,
187                   LINK_OBJ  = 6,
188                   PRIVATE_OBJ    = 7
189              };
190              typedef enum zotypes zotypes;
191
192
193
194       All  object  types  define  a structure that contains data  specific to
195       that type of object. The simplest are private objects which are defined
196       to  contain  a  variable  length array of octets. Only the owner of the
197       object is expected to understand the contents of a private object.  The
198       following section describe the other five object types in more signifi‐
199       cant detail.
200
201   Directory Objects
202       The first type of object is the directory object. This object's variant
203       part is defined as follows:
204
205         enum nstype {
206                   UNKNOWN   = 0,
207                   NIS  = 1,
208                   SUNYP     = 2,
209                   DNS  = 4,
210                   X500 = 5,
211                   DNANS     = 6,
212                   XCHS = 7,
213              }
214              typedef enum nstype nstype;
215              struct oar_mask {
216                   uint_t    oa_rights;
217                   zotypes   oa_otype;
218              }
219              typedef struct oar_mask oar_mask;
220              struct endpoint {
221                   char *uaddr;
222                   char *family;
223                   char *proto;
224              }
225              typedef struct endpoint endpoint;
226              struct nis_server {
227                   nis_name  name;
228                   struct {
229                        uint_t    ep_len;
230                        endpoint  *ep_val;
231                   } ep;
232                   uint_t    key_type;
233                   netobj    pkey;
234              }
235              typedef struct nis_server nis_server;
236              struct directory_obj {
237                   nis_name   do_name;
238                   nstype     do_type;
239                   struct {
240                        uint_t    do_servers_len;
241                        nis_server     *do_servers_val;
242                   } do_servers;
243                   uint32_t  do_ttl;
244                   struct {
245                        uint_t    do_armask_len;
246                        oar_mask  *do_armask_val;
247                   } do_armask;
248              }
249                 typedef struct directory_obj directory_obj;
250
251
252
253       The  main  structure  contains five primary members:  do_name, do_type,
254       do_servers, do_ttl, and do_armask. The information  in  the  do_servers
255       structure is sufficient for the client library to create a network con‐
256       nection with the named server for the directory.
257
258
259       The do_name member contains the name of the directory or domain  repre‐
260       sented  in  a  format that is understandable by the type of nameservice
261       serving that domain. In the case of NIS+ domains, this is the  same  as
262       the  name that can be composed using the zo_name and zo_domain members.
263       For other name services, this name will be a name that they understand.
264       For example, if this were a directory object describing an X.500 names‐
265       pace that is ``under'' the   NIS+  directory  eng.sun.com.,  this  name
266       might  contain   ``/C=US,  /O=Sun Microsystems, /OU=Engineering/''. The
267       type of nameservice that is being described is determined by the  value
268       of the member do_type.
269
270
271       The  do_servers  structure  contains  two members. do_servers_val is an
272       array of nis_server structures; do_servers_len is the number  of  cells
273       in  the  array.  The nis_server structure is designed to contain enough
274       information such that machines on the network providing  name  services
275       can  be  contacted without having to use a name service. In the case of
276       NIS+ servers, this information is the name of the machine in name,  its
277       public  key  for authentication in pkey, and a variable length array of
278       endpoints, each of which describes the network endpoint for the rpcbind
279       daemon  on  the named machine. The client library uses the addresses to
280       contact the server using a transport that both the  client  and  server
281       can  communicate  on  and  then  queries  the rpcbind daemon to get the
282       actual transport address that the server is using.
283
284
285       Note that the first server in the do_servers list is always the  master
286       server for the directory.
287
288
289       The  key_type field describes the type of key stored in the pkey netobj
290       (see /usr/include/rpc/xdr.h for a  definition  of  the  network  object
291       structure).  Currently  supported  types  are NIS_PK_NONE for no public
292       key, NIS_PK_DH for a Diffie-Hellman type public key,  and  NIS_PK_DHEXT
293       for an extended Diffie-Hellman public key.
294
295
296       The do_ttl member contains a copy of the  zo_ttl member from the common
297       attributes. This is the duplicated   because  the  cache  manager  only
298       caches the variant part of the directory object.
299
300
301       The do_armask structure contains two members. do_armask_val is an array
302       of oar_mask structures; do_armask_len is the number  of  cells  in  the
303       array. The oar_mask structure contains two members: oa_rights specifies
304       the access rights allowed for objects of type  oa_otype.  These  access
305       rights  are  used  for  objects of the given type in the directory when
306       they are present in this array.
307
308
309       The granting of access rights for objects contained within a  directory
310       is  actually two-tiered.  If the directory object itself grants a given
311       access right (using the zo_access member in  the  nis_object  structure
312       representing  the directory), then all objects within the directory are
313       allowed that access. Otherwise, the do_armask structure is examined  to
314       see  if  the access is allowed specifically for that type of structure.
315       This allows the administrator of a namespace to set  separate  policies
316       for different object types, for example, one policy for the creation of
317       tables and another policy for the creation of  other  directories.  See
318       NIS+(1) for more details.
319
320   Link Objects
321       Link  objects  provide  a  means of providing aliases or symbolic links
322       within the namespace. Their variant part is defined as follows.
323
324         struct link_obj {
325              zotypes   li_rtype;
326              struct {
327                   uint_t    li_attrs_len;
328                   nis_attr  *li_attrs_val;
329              } li_attrs;
330              nis_name li_name;
331         }
332
333
334
335       The li_rtype member contains the object type of the object  pointed  to
336       by  the  link.  This  is  only  a hint, since the object which the link
337       points to may have changed or been removed. The fully qualified name of
338       the object (table or otherwise) is specified in the member li_name.
339
340
341       NIS+ links can point to either other objects within the NIS+ namespace,
342       or to entries within a NIS+ table. If the object pointed to by the link
343       is  a  table and the member li_attrs has a nonzero number of attributes
344       (index name/value pairs) specified, the table  is  searched  when  this
345       link  is followed. All entries which match the specified search pattern
346       are returned. Note, that unless the flag   FOLLOW_LINKS  is  specified,
347       the  nis_lookup(3NSL) function will always return non-entry objects.
348
349   Group Objects
350       Group  objects contain a membership list of  NIS+ principals. The group
351       objects' variant part is defined as follows.
352
353         struct group_obj {
354              uint_t    gr_flags;
355              struct {
356                   uint_t    gr_members_len;
357                   nis_name  *gr_members_val;
358              } gr_members;
359         }
360
361
362
363       The gr_flags member contains  flags  that  are  currently  unused.  The
364       gr_members  structure  contains  the list of principals. For a complete
365       description of how group objects are manipulated see  nis_groups(3NSL).
366
367   Table Objects
368       The NIS+ table object is analogous to a YP map.  The  differences  stem
369       from  the  access  controls, and the variable schemas that NIS+ allows.
370       The table objects data structure is defined as follows:
371
372         #define TA_BINARY   1
373         #define TA_CRYPT    2
374         #define TA_XDR 4
375         #define TA_SEARCHABLE    8
376         #define TA_CASE     16
377         #define TA_MODIFIED 32
378         struct table_col {
379              char *tc_name;
380              uint_t    tc_flags;
381              uint_t    tc_rights;
382         }
383         typedef struct table_col table_col;
384         struct table_obj {
385              char *ta_type;
386              uint_t    ta_maxcol;
387              uchar_t   ta_sep;
388              struct {
389                   uint_t    ta_cols_len;
390                   table_col *ta_cols_val;
391              } ta_cols;
392              char *ta_path;
393         }
394
395
396
397       The ta_type member contains  a  string  that  identifies  the  type  of
398       entries  in  this  table.  NIS+ does not enforce any policies as to the
399       contents of this string. However, when entries are added to the  table,
400       the  NIS+ service will check to see that they have the same ``type'' as
401       the table as specified by this member.
402
403
404       The structure ta_cols contains two members. ta_cols_val is an array  of
405       table_col  structures. The length of the array depends on the number of
406       columns in the table; it is defined when the table is  created  and  is
407       stored in ta_cols_len. ta_maxcol also contains the number of columns in
408       the table and always has the same value as ta_cols_len. Once the  table
409       is created, this length field cannot be changed.
410
411
412       The  ta_sep character is used by client applications that wish to print
413       out an entry from the table. Typically this is either space (`` '')  or
414       colon (``:'').
415
416
417       The ta_path string defines a concatenation path for tables. This string
418       contains an ordered list of fully qualified table names,  separated  by
419       colons,  that  are  to  be  searched if a search on this table fails to
420       match any entries. This path is only used  with  the  flag  FOLLOW_PATH
421       with a  nis_list() call. See  nis_tables(3NSL) for information on these
422       flags.
423
424
425       In addition to checking the type, the service  will   check   that  the
426       number  of columns in an entry is the same as those in the table before
427       allowing that entry to be added.
428
429
430       Each column has associated with it a name in tc_name, a set of flags in
431       tc_flags,  and  a set of access rights in tc_rights. The name should be
432       indicative of the contents of that column.
433
434
435       The TA_BINARY flag indicates that data in the column is binary  (rather
436       than text). Columns that are searchable cannot contain binary data. The
437       TA_CRYPT flag specifies that the information in this column  should  be
438       encrypted prior to sending it over the network. This flag has no effect
439       in the export version of NIS+. The  TA_XDR flag is  used  to  tell  the
440       client  application  that  the data in this column is encoded using the
441       XDR protocol. The TA_BINARY flag must be specified with the  XDR  flag.
442       Further,  by  convention, the name of a column that has the TA_XDR flag
443       set is the name of the XDR function that will decode the data  in  that
444       column.
445
446
447       The   TA_SEARCHABLE  flag  specifies  that values in this column can be
448       searched. Searchable columns must contain textual data and must have  a
449       name  associated  with  them.  The flag TA_CASE specifies that searches
450       involving this column ignore the case of the value in  the  column.  At
451       least  one  of the columns in the table should be searchable. Also, the
452       combination of all searchable column values should uniquely  select  an
453       entry within the table. The TA_MODIFIED flag is set only when the table
454       column is modified.  When  TA_MODIFIED is set, and the object is  modi‐
455       fied  again,  the  modified  access rights for the table column must be
456       copied, not the default access rights.
457
458   Entry Objects
459       Entry objects are stored in tables. The structure used  to  define  the
460       entry data is as follows.
461
462         #define EN_BINARY   1
463         #define EN_CRYPT    2
464         #define EN_XDR 4
465         #define EN_MODIFIED 8
466         struct entry_col {
467              uint_t    ec_flags;
468              struct {
469                   uint_t    ec_value_len;
470                   char *ec_value_val;
471              } ec_value;
472         }
473         typedef struct entry_col entry_col;
474         struct entry_obj {
475              char *en_type;
476              struct {
477                   uint_t    en_cols_len;
478                   entry_col *en_cols_val;
479              } en_cols;
480         }
481
482
483
484       The  en_type  member  contains a string that specifies the type of data
485       this entry represents. The NIS+ server will compare this string to  the
486       type  string  specified in the table object and disallow any updates or
487       modifications if they differ.
488
489
490       The  en_cols  structure   contains   two   members:   en_cols_len   and
491       en_cols_val.   en_cols_val   is   an  array  of  entry_col  structures.
492       en_cols_len contains a count of the number of cells in the  en_cols_val
493       array and reflects the number of columns in the table -- it always con‐
494       tains the same value as the table_obj.ta_cols.ta_cols_len  member  from
495       the table which contains the entry.
496
497
498       The entry_col structure contains information about the entry's per-col‐
499       umn values. ec_value contains information about a particular value.  It
500       has   two  members:  ec_value_val,  which  is  the  value  itself,  and
501       ec_value_len, which is the length (in bytes) of  the  value.  entry_col
502       also  contains  the  member ec_flags, which contains a set of flags for
503       the entry.
504
505
506       The flags in ec_flags are  primarily  used  when  adding  or  modifying
507       entries in a table. All columns that have the flag EN_CRYPT set will be
508       encrypted  prior  to  sending  them  over  the  network.  Columns  with
509       EN_BINARY  set  are  presumed  to  contain binary data. The server will
510       ensure that the column in the table object specifies binary data  prior
511       to  allowing  the entry to be added. When modifying entries in a table,
512       only those columns that have changed need be sent to the server.  Those
513       columns  should  each have the EN_MODIFIED flag set to indicate this to
514       the server.
515

SEE ALSO

517       NIS+(1),    nis_groups(3NSL),    nis_names(3NSL),     nis_server(3NSL),
518       nis_subr(3NSL), nis_tables(3NSL)
519

NOTES

521       NIS+ might not be supported in future releases of the Solaris operating
522       system. Tools to aid the migration from NIS+ to LDAP are  available  in
523       the    current   Solaris   release.   For   more   information,   visit
524       http://www.sun.com/directory/nisplus/transition.html.
525
526
527
528SunOS 5.11                        10 Nov 2005                nis_objects(3NSL)
Impressum