1nis_objects(3NSL) Networking Services Library Functions nis_objects(3NSL)
2
6 nis_objects - NIS+ object formats
7
9 cc [ flag ... ] file ... -lnsl [ library ... ]
10 /usr/include/rpcsvc/nis_objects.x
11
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 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 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 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 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 sprintf(buf,"%s.%s", obj->zo_name, obj->zo_domain);
57 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 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 [cname=principal],cred.org_dir.domain.
73 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 unix.UID@domain
86 The NIS+ server will then construct a query on the credential database
90 of the form
91 [auth_name=netname,auth_type=AUTH_DES],cred.org_dir.domain.
93 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 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 group.domain.
106 which the server then maps into a name of the form
110 group.groups_dir.domain.
112 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 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 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 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 The zo_data member is a discriminated union with the following members:
159 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 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 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 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 Directory Objects
202 The first type of object is the directory object. This object's variant
203 part is defined as follows:
204 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 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 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 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 Note that the first server in the do_servers list is always the master
286 server for the directory.
287 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 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 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 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+[22m(1) for more details.
319 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 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 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 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 Group Objects
350 Group objects contain a membership list of NIS+ principals. The group
351 objects' variant part is defined as follows.
352 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 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 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 #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 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 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 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 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 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 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 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 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 Entry Objects
459 Entry objects are stored in tables. The structure used to define the
460 entry data is as follows.
461 #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 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 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 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 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
517 NIS+[22m(1), nis_groups(3NSL), nis_names(3NSL), nis_server(3NSL),
518 nis_subr(3NSL), nis_tables(3NSL)
519
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.
525SunOS 5.11 10 Nov 2005 nis_objects(3NSL)