test

System Administration Guide: Naming and Directory Services (FNS and NIS+)

Part IV FNS Setup, Configuration and Administration

This part contains information on the setup, configuration and administration of the Federated Naming Service (FNS).

Chapter 25 Federated Naming Service (FNS)

This chapter describes how to set up and configure the Federated Naming Service (FNS) in an NIS+, NIS, or files-based naming environment. (Files-based naming refers to name services that obtain their data from /etc files rather than NIS+ or NIS.) Additionally, it described the administration and troubleshooting for the FNS in the Solaris operating environment.

FNS Quickstart

FNS, the Federated Naming Service, supports the use of different autonomous naming systems in a single Solaris operating environment. FNS allows you to use a single, simple naming system interface for all of the different name services on your network. FNS conforms to the X/Open federated naming (XFN) specification.

FNS is not a replacement for NIS+, NIS, DNS, or /etc files. Rather, FNS is implemented on top of these services and allows you to use a set of common names with desktop applications.

X/Open Federated Naming (XFN)

The programming interface and policies that FNS supports are specified by XFN (X/Open Federated Naming).

Why FNS?

FNS is useful for the following reasons:

Composite Names and Contexts

Fundamental to FNS are the notions of composite names and contexts.

Composite Names

A composite name is a name that spans multiple naming systems.

A composite name consists of an ordered list of components. Each component is a name from the namespace of a single naming system. Individual naming systems are responsible for the syntax of each component. FNS defines the syntax for constructing a composite name using names from component naming systems. Composite names are composed left to right using the slash character (/) as the component separator.

For example, the composite name .../doc.com/site/bldg-5.alameda consists of four components: ..., doc.com, site, and bldg-5.alameda.

Contexts

A context provides operations for:

A context contains a set of name-to-reference bindings. Each reference contains a list of communication end-points or addresses. The federated naming system is formed by contexts from one naming system being bound in the contexts of another naming system. Resolution of a composite name proceeds from contexts within one naming system to those in the next until the name is resolved.

Attributes

Attributes may be applied to named objects. Attributes are optional. A named object can have no attributes, one attribute, or multiple attributes.

Each attribute has a unique attribute identifier, an attribute syntax, and a set of zero or more distinct attribute values.

XFN defines the base attribute interface for examining and modifying the values of attributes associated with existing named objects. These objects can be contexts or any other types of objects. Associated with a context are syntax attributes that describe how the context parses compound names.

The extended attribute interface contains operations that search for specific attributes and that create objects and their associated attributes.

FNS and the Name Service Switch

FNS, the Solaris implementation of the XFN API, can also be used to specify which name service a client is to query for naming information. The XFN API is more general in both the X and Y dimensions than the update getXbyY() interfaces that use the switch file. For example, it can be used to look up information on both hosts and users, from both NIS+ and NIS. An application can be a client of either getXbyY(), or XFN, or both.

Maintaining Consistency Between FNS and the Switch File

In order to ensure that changes made to namespace data through FNS are always available to clients obtaining namespace information through the switch file, always configure both the switch and FNS to use the same name service.

Namespace Updates

The support for data updates provided by the XFN API is superior to that of the getXbyY() interfaces. Most namespaces are composed of data from multiple sources. A groups namespace, for example, might contain information from both the /etc/group file and the NIS+ group.org_dir object. But the switch file does not provide enough information for an application update routine to identify the source of some particular piece of group data or the source to update.

Because each FNS subordinate namespace comes entirely from a single name service, updates are simple and straightforward because there is no confusion over which name service the update applies to.

Enterprise Naming Services

Enterprise-level naming services are used to name objects within an enterprise. FNS currently supports three enterprise-level naming services: NIS+, NIS and Files.

NIS+

NIS+ is the preferred enterprise-wide information service in the Solaris operating environment environment. FNS organization units correspond to NIS+ domains and subdomains. There is one orgunit context for each domain and subdomain.

Under NIS+, FNS context and attribute data are stored in NIS+ tables. These tables are stored in NIS+ directory objects named ctx_dir. There is a ctx_dir directory object for each NIS+ domain and subdomain, residing at the same level as the domain's groups_dir and org_dir directory objects. Thus, the directory object ctx_dir.sales.doc.com. contains FNS tables which store FNS context and attribute data for the sales.doc.com. domain.

Under NIS+, you use FNS and NIS+ commands to work with the information in FNS tables. Do not edit these tables directly or manipulate them with UNIX commands.

NIS

NIS is an enterprise-wide information service in the Solaris operating environment. Each enterprise is a single NIS domain. There is one FNS organizational unit which corresponds to the single NIS domain.

Under NIS, FNS context and attribute data are stored in NIS maps. These maps are stored in a /var/yp/domainname directory on an NIS server. Under NIS, the super user can use FNS commands to work with the information in FNS maps.

NIS Clients Can Update Contexts With FNS if SKI is Running

If certain conditions are met, any NIS client (machine, process, or user) can use FNS commands such as fncreate_fs or fncreate_printer to update the client's own contexts. This allows NIS clients to use FNS commands to update applications such as Printer Administrator, CDE Calendar Manager, Admin Tool and others.

For non-super-users to update their own contexts with FNS commands, the following conditions must be met:

Note –

SKI does not support 64–bit mode. Thus, NIS clients cannot update contexts in 64–bit mode.

Files-Based naming files

Files refers to the naming files normally found in a machine's /etc directory. These machine-based files contain UNIX user and password information, host information, mail aliases, and so forth. They also support Solaris-specific data such as the automount maps.

Under a files-based naming system, FNS context and attribute data is stored in files. These FNS files are stored in machine's /var/fn directory. (The /var/fn directory does not have to be on each machine, it could be exported from an NFS file server.)

Under a files naming system, you use FNS commands to work with the information in FNS files.

Global Naming Services

FNS also supports federating NIS+ and NIS with DNS and X.500. This means that you can connect enterprise level namespaces with global namespaces to make the enterprise objects accessible in the global scope.

FNS currently supports the following global naming services:

FNS Naming Policies

FNS defines naming policies so that users and applications can depend on and use the shared namespace.

Within an enterprise, there are namespaces for organizational units, sites, hosts, users, files and services, referred to by the names orgunit, site, host, user, fs (for file system), and service. These namespaces can also be named by preceding each name with an underscore (_). For example, host and _host are considered identical.

Table 25–1 summarizes the FNS policies for enterprise-level namespaces.

Table 25–1 FNS Policy Summary

Context Type 

Subordinate Contexts 

Parent Contexts 

orgunit _orgunit

site user host fs service

enterprise root 

site _site

user host fs service

enterprise root 

orgunit

user _user

service fs

enterprise root 

orgunit

host _host

service fs

enterprise root 

orgunit

service _service

Printer and other applications 

enterprise root 

orgunit site user host

fs _fs(file system)

(none) 

enterprise rootorgunit site user host

Organization Names

The binding of an FNS orgunit is determined by the underlying naming service:

The types of objects that may be named relative to an organizational unit name are: user, host, service, fs, and site. For example:

Site Names

Site names are created as needed. The types of objects that may be named relative to a site name are: user, host, service and fs. For example:

User Names

User names correspond to names in the corresponding passwd table in NIS+, the passwd map in NIS, or the /etc/passwd file under files. A user's file context is obtained from his or her passwd entry.

The types of objects that may be named relative to a user name are: service, and fs. For example:

Host Names

Host names correspond to names in the corresponding hosts table in NIS+, the hosts map in NIS, or the /etc/hosts file under files. The host's file context corresponds to the files systems exported by the host.

The types of objects that may be named relative to a host name are: service, and fs. For example:

Service Names

Service names correspond to, and are determined by, service applications. The service context must be named relative to an organization, user, host, or site context. For example:

File Names

File system names correspond to file names. For example:

Getting Started

To begin using FNS with your underlying name service, you run the fncreate command.

The fncreate command recognizes the underlying naming service in which FNS contexts are to be created (such as, NIS+, NIS, or files). To specify a specific naming service, you must run the fnselect command as explained in Designating a Non-Default Naming Service.

Designating a Non-Default Naming Service

By default:

You can also explicitly specify a non-default target naming service by using the fnselect command. For example the following command selects the target naming service to be NIS. 


# fnselect nis

Creating the FNS Namespace

Once the naming service has been selected either using the default policy or explicitly via fnselect, you can execute the following command to create the FNS namespace: 


# fncreate -t org org//

This creates all the necessary contexts for users and hosts in the corresponding naming service.

NIS+ Considerations

When your primary enterprise-level naming service is NIS+, take into account the following points.

NIS+ Domains and Subdomains

The command syntax shown above creates the FNS namespace for the root NIS+ domain. To specify a domain other than the root, add the domain name between the double slashes, as in:


# fncreate -t org org/sales.doc.com./

Note the trailing dot after the fully qualified sales.doc.com. domain name.

Space and Performance Considerations

The fncreate commands creates NIS+ tables and directories in the ctx_dir directory. The ctx_dir directory object resides at the same level as the NIS+ groups_dir and org_dir directory objects of the domain.

NIS+ Security Requirements

The user who runs fncreate and other FNS commands is expected to have the necessary NIS+ credentials.

The environment variable NIS_GROUP specifies the group owner for the NIS+ objects created by fncreate. In order to facilitate administration of the NIS+ objects, NIS_GROUP should be set to the name of the NIS+ group responsible for FNS administration for that domain prior to executing fncreate and other FNS commands.

Changes to NIS+ related properties, including default access control rights, could be effected using NIS+ administration tools and interfaces after the context has been created. The NIS+ object name that corresponds to an FNS composite name can be obtained using fnlookup and fnlist, described later in this document.

NIS Considerations

The fncreate command must be executed by superuser on the NIS system that will serve as the NIS master server for the FNS maps.

The NIS maps used by FNS are stored in /var/yp/domainname.

Any changes to the FNS information can only be done by the superuser on the FNS NIS master server using FNS commands.

Files Considerations

When using fncreate with the -t org option to create your FNS namespace, the command must be executed by superuser on the machine that owns the file system on which /var is located. The files used by FNS are stored in the /var/fn directory.

Once users' contexts are created, users are allowed to modify their own contexts based on their UNIX credentials.

If exported, the file system /var/fn can be mounted by other systems to access the FNS namespace.

Browsing the FNS Namespace

Once the namespace has been set up, you can browse using the following commands:

Listing Context Contents

The fnlist command displays the names and references bound in the context of name. 


fnlist [-lvA] [name]
Table 25–2 fnlist Command Options

Option 

Description 

name

A composite name. Displays the names bound in the context of name

-v

Verbose. Displays the binding in more detail 

-l

Also displays the bindings of the names bound in the named context 

-A

Forces fnlist to obtain its information from the authoritative server. Under NIS and NIS+, that is the domain master server. The -A option has no effect when the primary naming service is files.

For example:

To list names in the initial context:


% fnlist

To list in detail all the users in the current organizational unit:


% fnlist -v user

To list the contents of the service context for the user pug:


% fnlist user/pug/service

To list names and bindings from the authoritative server:


% fnlist -l -A

Displaying the Bindings of a Composite Name

The fnlookup command shows the binding of the given composite name. 


fnlookup [-vAL] [name]
Table 25–3 fnlookup Command Options

Option 

Description 

name

The name of a context. Displays the binding and XFN link of name

-v

Verbose. Displays the binding in more detail 

-L

Also displays the XFN link that the name is bound to 

-A

Forces fnlist to obtain its information from the authoritative server. Under NIS and NIS+, that is the domain master server. The -A option has no effect when the primary naming service is files-based.

For example: to display the binding of user/ana/service/printer:


# fnlookup user/ana/service/printer

Showing the Attributes of a Composite Name

The fnattr command displays (and updates) the attributes of the given composite name.

For example, to search for the attributes associated with a user named ada:


# fnattr user/ada

To search for the attributes associated with a printer named laser-9:


# fnattr thisorgunit/service/printer/laser-9

See Working With Attributes for more details.

Searching for FNS Information

The fnsearch command displays the names and, optionally, the attributes and references of objects bound at or below a composite name whose attributes satisfy the given search criteria.

For example:

To list the users and their attributes who have an attribute called realname:


% fnsearch user realname

To list the users with the attribute realname whose value is Ravi Chattha:


% fnsearch user “realname == 'Ravi Chattha'”

The fnsearch command uses the common Boolean operators. Note the use of double and single quotes and double equals sign in the above example.

Updating the Namespace

Once the namespace has been set up, you can add, delete, and modify elements using the following commands:

FNS Administration Privileges

FNS System administration varies according to the underlying naming service:

The ability of users to make changes to their own user sub-contexts varies according to the underlying naming service:

Binding a Reference to a Composite Name

The fnbind command is used to bind an existing reference (name) to a new composite name.


fnbind -r [-s][-v][-L] name [-O|-U] newname reftype addrtype [-c|-x] address
Table 25–4 fnbind Command Options

Option 

Description 

name

The existing composite name 

newname

The composite name of the new binding 

addrtype

Address type to use. Applications-specific such as onc_cal_str.

address

Address contents to use. For example, tsvi@altair.

reftype

Reference type to use. Applications-specific such as one_calendar.

-s

Bind to newname even if it is already bound. This replaces the previous binding of newname. Without -s, fnbind fails if newname is already bound.

-v

Display the reference that will be bound to newname.

-L

Create an XFN link using oldname and bind it to newname.

-r

Bind newname to the reference constructed by the command line arguments.

-c

Store address contents in the form as entered, do not use XDR-encoding.

-x

Convert address to a hexadecimal string without converting it to XDR-encoding.

-O

The identifier format is FN_ID_ISO_OID_STRING, an ASN.1 dot-separated integer list string. 

-U

The identifier format is FN_ID_DCE_UUID, a DCE UUID in string form. 

For example:

To add a calendar binding for the user jamal:


# fnbind -r user/jamal/service/calendar onc_calendar onc_cal_str
 jamal@cygnus

To replace the existing binding of org//service/Sparc-4 with that of org//service/printer:


# fnbind -s org//service/printer org//service/Sparc-4

To copy the reference site/bldg-5/service/printer to user/ando/service/printer:


# fnbind site/bldg-5/service/printer user/ando/service/printer

To bind the reference site/bldg-5/service/printer to user/ando/service/printer using a symbolic link:


# fnbind -L site/bldg-5/service/printer user/ando/service/printer

To bind the name thisens/service/calendar to the address staff@altair, when staff@altair is a reference of the type onc_cal and an address of the type onc_cal_str:


# fnbind -r thisens/service/calendar onc_calendar onc_cal_str staff@altair

To bind newname to the reference constructed by its command line address 


# fnbind -r [-sv] newname [-O|-U] reftype {[-O|-U] addrtype [-c|-x] address}

Removing Bindings

The fnunbind name command is used to remove bindings.

For example: to remove the binding for user/jsmith/service/calendar:


# fnunbind user/jsmith/service/calendar

Creating New Contexts

The fncreate command is used to create contexts. 


fncreate -t context [-f file] [-o] [-r reference] [-s] [-v] [-D] name
Table 25–5 fncreate Command Options

Option 

Description 

-t context

Create context of type context. Context types can be: org, hostname, host, username, user, service, fs, site, nsid, and generic.

-f file

Use an input file to list users and hosts for whom to create contexts. 

-r reference

Type of reference. The -r reference option can only be used with -t generic.

name

A composite name. 

-o

Create only the context identified by name.

-s

Overwrite (supersede) any existing binding. If -s is not used, fncreate will fail if name is already bound.

-D

Display information about each context and corresponding tables, directories, and files as it is created. 

-v

Verbose. Display information about each context as it is displayed. 

For example:

To create a context and subcontexts for the root organization:


# fncreate -t org org//

To create a context, and subcontexts, for the host deneb:


# fncreate -t host host/deneb

To create a context, service and file subcontexts, and then add a calendar binding for the user sisulu:


# fncreate -t user user/sisulu
# fnbind -r user/sisulu onc_calendar onc_cal_str sisulu@deneb

To create a site context for the sales organization:


# fncreate -t site org/sales/site/

The site context supports a hierarchal namespace, with dot-separated right-to-left names, which allows sites to be partitioned by their geographical coverage relationships. For example, to create a site context alameda and a site subcontext bldg-6.alameda for it:


# fncreate -t site org/sales/site/alameda
# fncreate -t site org/sales/site/bldg-6.alameda

Creating File Contexts

Table 25–6 fncreate_fs Command Options

Option 

Description 

name

The name of the file context. 

options

Mount options. 

mount

Mount location. 

-f file

Input file. 

-v

Verbose. Displays information about the contexts being created. 

-r

Replace the bindings in the context name with those specified in the input.

For example:

To create a file system context named data for the sales organization bound to the /export/data path of an NFS server named server4.


# fncreate_fs org/sales/fs/data server4:/export/data

To create a hierarchy of file system contexts for the sales organization named buyers and buyers/orders mounted on two different servers:


# fncreate_fs org/sales/fs/buyers server2:/export/buyers
# fncreate_fs org/sales/fs/buyers/orders server3:/export/orders

To create a file system context named leads for the sales organization bound to a server and path specified by an input file named input_a:


# fncreate_fs -f input_a org/sales/fs/leads

(See the fncreate_fs man page for information on input file format.)

Creating Printer Contexts

The fncreate_printer command creates printer contexts for organizations, users, hosts and site contexts. The printer context is created under the service context of the respective composite name. 


fncreate_printer [-vs] name printer [prntaddr]
 

fncreate_printer [-vs] [-f [file]] name
Table 25–7 fncreate_printer Command Options

Option 

Description 

name

The name of the org, host, user, or site of the printer. 

printer

The name of the printer. 

prntaddr

The printer address in the form <addresstype>=<address>.

-f file

Use the named file as input for a list of printers to be created. The input file is in the format of the /etc/printers.conf file. If neither a printer name nor a -f file is specified, fncreate_printer uses the /etc/printer.conf file on the machine where fncreate_printer is run as a default input file.

-s

Replace an existing address with the same address-type. 

-v

Verbose. Displays the binding in more detail. 

For example:

To create printers for the sales organization based on the printers listed in the /etc/printers.conf file of the machine on which fncreate_printer is run: 


# fncreate_printer -s org/sales/

Assume that the machine altair is the server for a printer named Sparc-5. To create a printer named invoices for the user nguyen that is actually the Sparc-5 printer:


# fncreate_printer user/nguyen invoices bsdaddr=altair,Sparc-5

It is also possible to organize printers hierarchically. For example, the fncreate_printer command can create printer contexts for the printers, color, color/inkjet and color/Sparc with the resulting contexts:


org/doc.com/service/printer/color
org/doc.com/service/printer/color/inkjet
org/doc.com/service/printer/color/Sparc

To create the above contexts, you would run:


# fncreate_printer org/doc.com color bsdaddr=colorful,color
# fncreate_printer org/doc.com color/inkjet bsdaddr=colorjet,inkjet
# fncreate_printer org/doc.com color/Sparc bsdaddr=colorprt,Sparc

Destroying Contexts

The fndestroy command is used to destroy empty contexts.

For example, to destroy the service context of the user patel:


# fndestroy user/patel/service

Working With Attributes

The fnattr command can be used to add, delete or modify attributes associated with a name. You can make modifications one at a time, or batch several within the same command.

Table 25–8 fnattr Command Options

Option 

Description 

name

The composite name. 

attrib

The identifier of an attribute. 

values

One or more attribute values. 

oldvalue

An attribute value to be replaced by a new value. 

newvalue

The attribute value that replaces an old value. 

-a

Add an attribute. 

-d

Destroy an attribute. 

-l

List attributes. 

-m

Modify an attribute. 

-s

Replace all old attribute values with the new values for the attribute specified. 

-O

The identifier format is FN_ID_ISO_OID_STRING, an ASN.1 dot-separated integer list string. 

-U

The identifier format is FN_ID_DCE_UUID, a DCE UUID in string form. 

For example:

To show all of the attributes associated with the user name rosa:


# fnattr user/rosa

To display the size attribute associated with the user uri:


# fnattr user/uri/ size

For a user named devlin, to add an attribute named shoesize with a value of small, delete the hatsize attribute, and change the dresssize attribute value from 12 to 8:


# fnattr user/devlin -a shoesize small -d hatsize -m dresssize 12 8

Federating a Global Namespace

You can federate NIS+ or NIS to a global naming service like DNS and X.500.

To federate an NIS+ or NIS namespace under DNS or X.500, you first need to obtain the root reference for the NIS+ hierarchy or NIS domain.

From the point of view of the global name service, the root reference is known as the next naming system reference because it refers to the next naming system beneath the DNS domain or X.500 entry. To federate NIS+ or NIS with a global name service, you add the root reference information to that global service.

Once you have added the root reference information to the global service, clients outside of your NIS+ hierarchy or NIS domain can access and perform operations on the contexts in the NIS+ hierarchy or NIS domain. Foreign NIS+ clients access the hierarchy as unauthenticated NIS+ clients.

For example:

If NIS+ is federated underneath the DNS domain doc.com., you can now list the root of the NIS+ enterprise using the command


# fnlist .../doc.com/

If NIS+ is federated underneath the X.500 entry /c=us/o=doc, you can list the root of the NIS+ enterprise using the command:


# fnlist .../c=us/o=doc/

Note the mandatory trailing slash in both examples.

Copying and Converting FNS Contexts

The fncopy command can be used to copy or convert an FNS context and attributes to a new FNS context.

By using the -i and -o options, you can copy FNS contexts based on one underlying enterprise-level name service to a context based on a different underlying name service. For example, if you have an FNS installation running on top of NIS, and you upgrade your NIS service to NIS+, you can use fncopy to create a new context using NIS+.

Note that:

Table 25–9 fncopy Command Options

Option 

Description 

-i oldservice

The old (input) underlying enterprise-level name service. For example, -i nis specifies that the old service is NIS. Allowed values are files, nis, nisplus.

-o newservice

The new (output) underlying enterprise-level name. For example, o nisplus specifies that the new service is NIS+. Allowed values are files, nis, nisplus.

-f filename

A text file listing FNS contexts to be copied. In the absence of the -i and -o options, contexts must be identifies using global names.

oldcontext

The name of the context being copied. 

newcontext

The name of the context being created or copied to. 

For example, to copy the doc.com printer contexts (and sub-contexts) and bindings to orgunit/east/doc.com:


# fncopy .../doc.com/service/printer .../doc.com/orgunit/east/service/printer

To copy the NIS FNS users' contexts specified in the file user_list to an NIS+ FNS users' context of the orgunit west/doc.com:


# fncopy -i nis -o nisplus -f /etc/user_list thisorgunit/user org/doc.com/user

Namespace Browser Programming Examples

The programming examples in this section shows the usage of XFN APIs to perform the following operations:

Listing Names Bound in a Context

The example below shows XFN operations to list a context.


#include <stdio.h>
#include <xfn/xfn.h>
#include <string.h>
#include <stdlib.h>
/*
 This routine returns the list of names
 bound under the given context (ctx_name).
 Examples of ctx_name are "user", "thisorgunit/service",
	host/alto/service, user/jsmit/service/calendar, etc.,
*/
typedef struct fns_listing {
	char *name;
	struct fns_listing *next;
} fns_listing;
fns_listing *
fns_list_names(const char *ctx_name)
{
	FN_status_t *status;
	FN_ctx_t *initial_context;
	FN_composite_name_t *context_name;
	FN_namelist_t *name_list;
	FN_string_t *name;
	unsigned int stat;
	fns_listing *head = 0, *current, *prev;
	int no_names = 0;
	status = fn_status_create();
	/* Obtain the initial context */
	initial_context = fn_ctx_handle_from_initial(0, status);
	if (!fn_status_is_success(status)) {
		fprintf(stderr, "Unable to obtain intial context\n");
		return (0);
	}
	context_name = fn_composite_name_from_str((unsigned char *)
                  ctx_name);
	/* FNS call to list names */
	name_list = fn_ctx_list_names(initial_context, context_name,
               status);
	if (!fn_status_is_success(status)) {
		fprintf(stderr, "Unable to list names\n");
		return (0);
	}
	/* Obtain the names individually */
	while (name = fn_namelist_next(name_list, status)) {
		no_names++;
		current = (fns_listing *) malloc(sizeof(fns_listing));
		current->name = (char *)
		 malloc(strlen((char *) fn_string_str(name, &stat)) + 1);
		strcpy(current->name, (char *) fn_string_str(name, &stat));
		current->next = 0;
		if (head) {
			prev->next = current;
			prev = current;
		} else {
			head = current;
			prev = current;
		}
		fn_string_destroy(name);
	}
	fn_namelist_destroy(name_list);
	fn_status_destroy(status);
	fn_ctx_destroy(initial_context);
	return (head);

Creating a Binding

Example 25–1 shows how to create a binding.

Example 25–1 Creating a Binding


#include <stdio.h>
#include <xfn/xfn.h>
#include <string.h>
/*
 This routine creates a binding with a name provided by "name"
 and having a reference type "reference_type" and address type
 "address_type".
 An example of using the function could be:
	 fns_create_bindings(
	 "user/jsmith/service/calendar",
	 "onc_calendar",
	 "onc_cal_str",
	 "jsmith&calserver");
*/
int fns_create_bindings(
 char *name,
 char *reference_type,
 char *address_type,
 char *data)
{
	int return_status;
	FN_composite_name_t *binding_name;
	FN_identifier_t ref_id, addr_id;
	FN_status_t *status;
	FN_ref_t *reference;
	FN_ref_addr_t *address;
	FN_ctx_t *initial_context;
	/* Obtain the initial context */
	status = fn_status_create();
	initial_context = fn_ctx_handle_from_initial(0, status);
	/* Check status for any error messages */
	if ((return_status = fn_status_code(status)) != FN_SUCCESS) {
		fprintf(stderr, "Unable to obtain the initial context\n");
		return (return_status);
	}
	/* Get the composite name for the printer name */
	binding_name = fn_composite_name_from_str((unsigned char *) name);
	/* Construct the Address */
	addr_id.format = FN_ID_STRING;
	addr_id.length = strlen(address_type);
	addr_id.contents = (void *) address_type;
	address = fn_ref_addr_create(&addr_id,
		strlen(data), (const void *) data);
	/* Construct the Reference */
	ref_id.format = FN_ID_STRING;
	ref_id.length = strlen(reference_type);
	ref_id.contents = (void *) reference_type;
	reference = fn_ref_create(&ref_id);
	/* Add Address to the Reference */
	fn_ref_append_addr(reference, address);
	
	/* Create a binding */
	fn_ctx_bind(initial_context, binding_name, reference, 0, status);
	/* Check the error status and return */
	return_status = fn_status_code(status);
	fn_composite_name_destroy(binding_name);
	fn_ref_addr_destroy(address);
	fn_ref_destroy(reference);
	fn_ctx_destroy(initial_context);
	return (return_status);
}

Listing and Working Wtih Object Attributes

The examples below show techniques to list and work with attributes of an object.

Listing an Object's Attributes

The example below shows how to list the attributes of an object.


#include <stdio.h>
#include <xfn/xfn.h>
/*
 This routine prints all the attributes associated
 with the named object to the standard output.
 Examples of using the function:
 	fns_attr_list("user/jsmith");
	fns_attr_list("thisorgunit/service/printer/color");
*/
void fns_attr_list(const char *name)
{
	FN_composite_name_t *name_comp;
	const FN_identifier_t *identifier;
	FN_attribute_t *attribute;
	const FN_attrvalue_t *values;
	char *id, *val;
	FN_multigetlist_t *attrset;
	void *ip;
	FN_status_t *status;
	FN_ctx_t *initial_context;
	name_comp = fn_composite_name_from_str((unsigned char *) name);
	status = fn_status_create();
	/* Obtain the initial context */
	initial_context = fn_ctx_handle_from_initial(0, status);
	if (!fn_status_is_success(status)) {
		fprintf(stderr, "Unable to obtain intial context\n");
		return;
	}
	/* Obtain all the attributes */
	attrset = fn_attr_multi_get(initial_context, name_comp, 0, 0,
            status);
	if (!fn_status_is_success(status)) {
		fprintf(stderr, "Unable to obtain attributes\n");
		return;
	}
	/* List all attributes */
	while (attribute = fn_multigetlist_next(attrset, status)) {
		identifier = fn_attribute_identifier(attribute);
		switch(identifier->format) {
		case FN_ID_STRING:
			id = (char *) malloc(identifier->length + 1);
			memcpy(id, identifier->contents, identifier->length);
			id[identifier->length] = '\0';
			printf("Attribute Identifier: %s", id);
			free(id);
			break;
		default:
			printf("Attribute of non-string format\n\n");
			continue;
		}
		for (values = fn_attribute_first(attribute, &ip);
		 values != NULL;
		 values = fn_attribute_next(attribute, &ip)) {
			val = (char *) malloc(values->length + 1);
			memcpy(val, values->contents, values->length);
			val[values->length] = '\0';
			printf("Value: %s", val);
			free(val);
		}
		fn_attribute_destroy(attribute);
		printf("\n");
	}
	fn_multigetlist_destroy(attrset);
	fn_ctx_destroy(initial_context);
	fn_status_destroy(status);
	fn_composite_name_destroy(name_comp);
}

Adding, Deleting, and Modifying an Object's Attributes

The example below shows how to add, delete, or modify an object's attributes.


#include <stdio.h>
#include <xfn/xfn.h>
/*
 This routine modifies an attribute associated
 with the named object. The modify operation supported are:
 	FN_ATTR_OP_ADD
 FN_ATTR_OP_ADD_EXCLUSIVE
 FN_ATTR_OP_REMOVE
 FN_ATTR_OP_ADD_VALUES
 FN_ATTR_OP_REMOVE_VALUES
 The function assumes the attribute values to be strings.
 Examples of using the function:
 The following function add an attribute of identifier "realname"
 with value "James Smith" to the user object "user/jsmith".
 	fns_attr_modify(
		"user/jsmith",
		"realname",
		"James Smith",
		FN_ATTR_OP_ADD);
 The following function removes an attribute of identifier 
 "location" from the printer object 
 "thisorgunit/service/printer/color".
 	fns_attr_modify(
		"thisorgunit/service/printer/color",
		"location",
		NULL,
		FN_ATTR_OP_REMOVE);
*/
static const char *attr_id_syntax = "fn_attr_syntax_ascii";
void fns_attr_modify(const char *name,
	const char *attr_id,
	const char *attr_value,
	unsigned int operation)
{
	FN_composite_name_t *name_comp;
	FN_identifier_t identifier, syntax;
	FN_attrvalue_t *values;
	FN_attribute_t *attribute;
	FN_status_t *status;
	FN_ctx_t *initial_context;
	name_comp = fn_composite_name_from_str((unsigned char *) name);
	status = fn_status_create();
	/* Obtain the initial context */
	initial_context = fn_ctx_handle_from_initial(0, status);
	if (!fn_status_is_success(status)) {
		fprintf(stderr, "Unable to obtain intial context\n");
		return;
	}
	/* Create the attribute to be added */
	/* First, the identifier */
	identifier.format = FN_ID_STRING;
	identifier.length = strlen(attr_id);
	identifier.contents = (void *) strdup(attr_id);
	/* Second, the syntax */
	syntax.format = FN_ID_STRING;
	syntax.length = strlen(attr_id_syntax);
	syntax.contents = (void *) strdup(attr_id_syntax);
	/* Third, the attribute value */
	if (attr_value) {
		values = (FN_attrvalue_t *) malloc(sizeof(FN_attrvalue_t));
		values->length = strlen(attr_value);
		values->contents = (void *) strdup(attr_value);
	} else
		values = NULL;
	/* Fourth, create the attribute */
	attribute = fn_attribute_create(&identifier, &syntax);
	/*Fifth, add the attribute value */
	if (values)
		fn_attribute_add(attribute, values, 0);
	
	/* Perform the XFN operation */
	fn_attr_modify(initial_context, name_comp, operation, attribute, 0,
status);
	if (!fn_status_is_success(status))
		fprintf(stderr, "Unable to perform attribute operation\n");
	fn_ctx_destroy(initial_context);
	fn_status_destroy(status);
	fn_composite_name_destroy(name_comp);
	fn_attibute_destroy(attribute);
	free(identifier.contents);
	free(syntax.contents);
	if (values) {
		free(values->contents);
		free(values);
 ]
]

Searching for Objects in a Context

The example below shows how to search for objects in a context with a specific attribute identifier and value.


#include <stdio.h>
#include <xfn/xfn.h>
#include <string.h>
#include <stdlib.h>
/*
 This routine searchs for objects in a context
 which has the specified attribute identifier and value.
*/
typedef struct fns_search_results {
	char *name;
	struct fns_search_results *next;
} fns_search_results;
static const char *attr_id_syntax = "fn_attr_syntax_ascii";
fns_search_results *
fns_attr_search(const char *name,
	const char *attr_id,
	const char *attr_value)
{
	FN_status_t *status;
	FN_ctx_t *initial_context;
	FN_composite_name_t *context_name;
	FN_searchlist_t *search_list;
	FN_string_t *search_name;
	FN_attribute_t *attribute;
	FN_attrset_t *attrset;
	FN_identifier_t identifier, syntax;
	FN_attrvalue_t *values;
	unsigned stat;
	fns_search_results *head = 0, *current, *prev;
	int no_names = 0;
	context_name = fn_composite_name_from_str((unsigned char *) name);
	status = fn_status_create();
	initial_context = fn_ctx_handle_from_initial(0, status);
	if (!fn_status_is_success(status)) {
		fprintf(stderr, "Unable to obtain intial context\n");
		return (0);
	}
	/* Construnct the attrset with attributes to be searched */
	/* First, the identifier */
	identifier.format = FN_ID_STRING;
	identifier.length = strlen(attr_id);
	identifier.contents = (void *) strdup(attr_id);
	/* Second, the syntax */
	syntax.format = FN_ID_STRING;
	syntax.length = strlen(attr_id_syntax);
	syntax.contents = (void *) strdup(attr_id_syntax);
	/* Third, the attribute value */
	values = (FN_attrvalue_t *) malloc(sizeof(FN_attrvalue_t));
	values->length = strlen(attr_value);
	values->contents = (void *) strdup(attr_value);
	/* Fourth, create the attribute */
	attribute = fn_attribute_create(&identifier, &syntax);
	/* Fifth, add the attribute value */
	fn_attribute_add(attribute, values, 0);
	/* Sixth, create attrset, and add the attribute */
	attrset = fn_attrset_create();
	fn_attrset_add(attrset, attribute, 0);
	search_list = prelim_fn_attr_search(initial_context,
	 context_name, attrset, 0, 0, status);
	if (!fn_status_is_success(status)) {
		fprintf(stderr, "Unable to list names\n");
		return (0);
	}
	while (search_name = prelim_fn_searchlist_next(search_list,
	 0, 0, status)) {
		no_names++;
		current = (fns_search_results *) 
    malloc(sizeof(fns_search_results));
		current->name = (char *)
		 malloc(strlen((char *) fn_string_str(search_name, &stat)) + 1);
		strcpy(current->name, (char *) fn_string_str(search_name, &stat));
		current->next = 0;
		if (head) {
			prev->next = current;
			prev = current;
		} else {
			head = current;
			prev = current;
		}
		fn_string_destroy(search_name);
	}
	fn_searchlist_destroy(search_list);
	fn_status_destroy(status);
	fn_ctx_destroy(initial_context);
	fn_attrset_destroy(attrset);
	fn_attribute_destroy(attribute);
	free(identifier.contents);
	free(syntax.contents);
	free(values->contents);
	free(values);
	return (head);
}

Setting Up FNS: An Overview

After your Solaris operating environment software is installed, you must perform the following tasks to set up FNS:

  1. Make sure that your servers can handle FNS. See Determining Resource Requirements.

  2. Prepare your namespace for FNS. See Preparing the Namespace for FNS.

  3. Set up the FNS namespace contexts. There are two ways to do this:

    1. Globally create all contexts in one process. See Creating Global FNS Namespace Contexts.

    2. Individually create your FNS contexts.

  4. Set up FNS replica servers. See Replicating FNS Service.

Depending on the size of the organization, you should allow several hours for the FNS setup to be completed, plus additional time for namespace preparation.

Determining Resource Requirements

Before proceeding with any installation procedure, you must first ensure that the servers supporting FNS have sufficient memory and disk storage. Space for FNS is in addition to the space needed for your enterprise-level name service (NIS+, NIS, or files).

As a general rule-of-thumb, you will need approximately 17 Kbytes of disk storage for each user and host, plus adequate swap space. Where this disk storage space is located and how it is calculated varies according to your underlying enterprise-level naming service:

For example, to support an FNS environment in an NIS+ domain with 1200 users and hosts, you will need:

Preparing the Namespace for FNS

This section describes the preparations you need to make before running fncreate to set up your FNS contexts. The preparations vary according to your enterprise-level naming service.

Preparing the Namespace for FNS — Task Map

Table 25–10 Preparing the Namespace for FNS

Task 

Description 

For Instructions, Go To 

Preparing the Namespace for FNS 

Convert files to NIS maps 

“Working With NIS Maps” in System Administration Guide: Naming and Directory Services (DNS, NIS, and LDAP)

Preparing the Namespace for FNS 

Prepare NIS service 

How to Prepare NIS Service for FNS

Preparing the Namespace for FNS 

Prepare files-based naming 

Preparing Files-Based Naming for FNS

How to Prepare NIS+ Service for FNS

Before setting up the FNS namespace, do the following:

  1. Make sure that the NIS+ domain is properly set up.

    The NIS+ domain and associated subdomains must already be set up before configuring FNS. In other words, NIS+ standard tables, such as hosts and passwd, must already exist and be populated.

  2. Make sure that the domain's hosts.org_dir and passwd.org_dir tables are fully populated with the names of every host and user.

    You can use the niscat or nismatch commands to check the contents of these tables.

  3. Set the NIS_GROUP environment variable to the name of the group that will be administering the FNS objects.

    The fncreate command will not let you complete the FNS setup without setting this variable first. When fncreate creates user and host contexts, they are owned by those hosts and users, and not by the administrator who executed the command. Setting NIS_GROUP allows the administrators who are members of the group to subsequently modify these contexts, even though they do not own the objects.

    Assuming a C-Shell, the example below sets NIS_GROUP to fns_admins.doc.com.


    rootmaster# setenv NIS_GROUP fns_admins.doc.com

  4. [Optional] Specify that FNS run on a machine other than the NIS+ master server.

    All NIS+ objects used by FNS are kept under the ctx_dir directory of an NIS+ domain, at the same level as the domain's org_dir directory. For large domains, such as those with more than 5000 users and hosts, it is recommended (though not required) that the ctx_dir used by FNS be supported by a server different from the one supporting the standard NIS+ directories, such as groups_dir. Using separate servers avoids placing too much load on one server. It also allows you to keep separate the administration of FNS's use of NIS+ and the administration of NIS+ itself.

    To specify that FNS be hosted by a machine that is not the NIS+ master server for the domain, you must manually create a ctx_dir directory object on the machine that will serve as the FNS host for the domain. (If you omit this step, FNS will be installed on the domain's NIS+ root master server.)

    To specify the machine that will become the FNS master server:

    1. Create the ctx_dir directory for the NIS+ domain.

      For example, to create a ctx_dir directory on a machine named fns_server in the doc.com domain, run the following command on the domain's master server (note the trailing dot at the end of the domain name, as shown):


      nismaster# nismkdir -m fns_server ctx_dir.doc.com.

      (See The nismkdir Command for more information on creating NIS+ directory objects with the nismkdir command.)

      Note –

      If you are creating an FNS ctx_dir directory for a subdomain, the machine you specify as the FNS server hosting ctx_dir must reside in the subdomain, it cannot be a machine in the parent domain. (By contrast, a subdomain's NIS+ master server always resides in the domain above the one it serves.) In other words, when configuring FNS for an NIS+ subdomain, if you use the same server for both NIS+ and FNS, that server resides in the domain above the subdomain; but if you use different servers for NIS+ and FNS, the NIS+ master server resides in the domain above and the FNS server resides in the subdomain that it serves.

    2. Use the nisls command to verify that the ctx_dir directory has been created. 


      rootmaster # nisls doc.com.ctx_dir

    3. Run nisping to checkpoint the directory 


      # /usr/lib/nis/nisping -C ctx_dir.doc.com.

How to Prepare NIS Service for FNS

Before setting up the FNS namespace, do the following:

    Make sure that the hosts.byname, user.byname, and printer.conf.byname maps are complete, correct, and up to date.

Note –

You can assign a different master server for FNS maps, using the same procedure that you would to assign a different master for any other NIS map.

Preparing Files-Based Naming for FNS

Files-based naming refers to name services that obtain their data from /etc files rather than NIS+ or NIS.

If you are going to install a /var/fn directory on each machine, as is normally the case, the steps below must be performed on each machine. If you decide to mount and export the /var/fn directory from one machine, the steps below need to be performed on the machine that exports /var/fn.

    Make sure that the /etc/hosts and /etc/passwd files are complete and contain the names of all users and hosts.

Creating Global FNS Namespace Contexts

This section describes how to create your namespace globally for a given enterprise or NIS+ domain.

The FNS namespace is created by the fncreate command.


# fncreate -t org org//

Or, alternatively:


# fncreate -t org org/domain/

Where domain is the name of an NIS+ domain or subdomain.

The fncreate command creates the default contexts for the specified organization and all its subcontexts, including contexts and subcontexts for users and hosts in the organization.

Creating Global FNS Namespace Contexts — Task Map

Table 25–11 Globally Creating FNS Namespace Contexts

Task 

Description 

For Instructions, Go To 

Globally Creating FNS Namespace Contexts 

Create FNS namespace under NIS+ 

How to Create Namespace Contexts Under NIS+

Globally Creating FNS Namespace Contexts 

Create FNS namespace under NIS 

How to Create Namespace Contexts Under NIS

Globally Creating FNS Namespace Contexts 

Create FNS namespace under files 

How to Create Namespace Contexts Under Local Files

How to Create Namespace Contexts Under NIS+

When your primary enterprise-level name service is NIS+, namespace contexts must be created separately for each NIS+ domain or subdomain in your enterprise.

For example, to create the contexts for the manf.doc.com subdomain on the submaster machine that is the NIS+ master server for that domain:

  1. On the subdomain master, run fncreate as shown below:


submaster# fncreate -t org org/manf.doc.com./

This creates the organization context for the NIS+ manf.doc.com. subdomain, and contexts and associated subcontexts for all users found in that subdomain's passwd.org_dir table and all hosts found in the subdomain's hosts.org_dir table.

(If you want to use different machines for NIS+ and FNS servers, run the above command on the machine you want to use as the FNS server. See Step 4 for information on how to prepare a non-NIS+ server to be an FNS server.)

  1. Use nisping to checkpoint the ctx_dir directory: 


    # /usr/lib/nis/nisping -C ctx_dir.manf.doc.com.

    Note –

    For a large organization with several thousand users and hosts, the initial fncreate operation can take several hours; the subsequent checkpoint can also take several hours.

How to Create Namespace Contexts Under NIS

When your primary enterprise-level name service is NIS, there is only one domain for the enterprise. Namespace contexts are created for that enterprise-wide domain.

For example, create the contexts for the doc.com domain, on the machine named fns_master, which is also the NIS master server:

    On the domain master, run fncreate as shown below:


    fns_master# fncreate -t org org//

    This creates the organization context for the NIS domain doc.com, and contexts and associated subcontexts for all users found in NIS servers's passwd map and all hosts found in the server's hosts map.

    Note –

    After you have created your context maps, you can assign the same machine to be the master server, using the same procedure that you would to assign a different master for any other NIS map. The FNS maps all have names starting with fns_ and ending with either .ctx or .attr.

How to Create Namespace Contexts Under Local Files

When your primary enterprise-level name service is files-based, namespace contexts are created for the system.

For example, to create the contexts for the system:

    On the machine hosting the /var/fn directory, run fncreate, as shown below: 


    server1# fncreate -t org org//

This creates the organization context for the system and contexts and associated subcontexts for all users found in machine's /etc/passwd file, and all hosts found in the machine's /etc/hosts file.

Replicating FNS Service

On large or mission-critical networks where performance and reliability of FNS naming is of vital importance, FNS service should be replicated.

Replicating FNS Service — Task Map

Table 25–12 Replicating FNS Service

Task 

Description 

For Instructions, Go To 

Replicating FNS Service 

Replicate FNS service under NIS+ 

How to Replicate FNS Under NIS+

Replicating FNS Service 

Replicate FNS service under NIS 

How to Replicate FNS Under NIS

Replicating FNS Service 

Replicate FNS service under files 

How to Replicate FNS Under Files-Based Naming

How to Replicate FNS Under NIS+

After the FNS namespace has been set up on the master server, additional replicas can be added in each domain to serve the domain's ctx_dir directory. Replicas enhance availability and performance of the servers.

  1. Run the nismkdir command on the FNS master server to add a replica for the ctx_dir directory.

    For example, establish the machine fnsrserver as an FNS replica for the doc.com. domain:


    # nismkdir -s fnsrserver ctx_dir.doc.com.

  2. Checkpoint the ctx_dir directory with the nisping command. 


    # /usr/lib/nis/nisping -C ctx_dir.doc.com.

    FNS replicas should be checkpointed at regular intervals. The recommended period is every few days. The period you choose depends on how frequently changes are made to the FNS namespace.

How to Replicate FNS Under NIS

After the FNS namespace has been set up on the domain master server, additional slave servers can be added to enhance availability and performance of the servers.

  1. As root, edit the /etc/hosts file on the slave server to add the name and IP addresses of all the other NIS servers.

  2. Change directory to /var/yp on the slave server.

  3. To initialize the slave server as a client, type the following:


    # /usr/sbin/ypinit -c

    The ypinit command prompts you for a list of NIS servers. Enter the name of the local slave you are working on first, then the master server, followed by the other NIS slave servers in your domain in order, from the physically closest to the furthest (in network terms).

    Note –

    You must first configure the new slave server as an NIS client so that it can get the NIS maps from the master for the first time. (See “Setting Up and Configuring NIS Service” in System Administration Guide: Naming and Directory Services (DNS, NIS, and LDAP) for details.)

  4. To determine if ypbind is running, type: 


    # ps -ef | grep ypbind

    If a listing is displayed, ypbind is running.

  5. If ypbind is running, stop it by typing: 


    # /usr/lib/netsvc/yp/ypstop

  6. Type the following to restart ypbind:


    # /usr/lib/netsvc/yp/ypstart

  7. To initialize this machine as a slave, type the following:


    # /usr/sbin/ypinit -s master

    Where master is the machine name of the existing NIS master server.

  8. Stop yp processes on the Slave Server:


    # /usr/lib/netsvc/yp/ypstop

  9. Restart yp service:


    # /usr/lib/netsvc/yp/ypstart

    Alternatively, you can reboot the slave server and allow daemons to start automatically.

How to Replicate FNS Under Files-Based Naming

There is no server replication when your primary naming service is files-based.

FNS Administration, Problem Solving, and Error Messages

FNS Error Messages

FNS messages are encapsulated in the FN_status_t object as status codes. See the FN_status_t man page for the corresponding status codes.

When an error occurs, FNS commands print out the remaining part of the name on which the operation failed. The part of the name that has not been printed has been processed successfully.

For example, a user attempted to create a context for org//service/trading/bb. The name org//service/ was resolved successfully, but trading was not found in the context named by org//service/. Thus, trading/bb is displayed as the part of the name that remains when the operation failed:


Error in creating 'org//service/trading/bb': Name Not Found: 'trading/bb'

In another example, a user attempted to destroy the context org//service/dictionary/english, but could not carry out the operation because the context named was not empty. The pair of single quotes ('') indicates that FNS was able to resolve the complete name given, but could not complete the operation as requested:


Error in destroying 'org//service/dictionary/english': Context Not Empty: ''

DNS Text Record Format for XFN References

The Solaris environment conforms to the XFN specification for federating global naming systems within DNS. In order to federate a naming system under DNS, you need to enter information into DNS TXT resource records. This information is then used to construct an XFN reference for that subordinate naming system. This chapter describes the format of these DNS TXT records.

The reference type of an XFN reference is constructed from a TXT record that begins with the XFNREF tag. It has the following format: 


TXT "XFNREF rformat reftype"

If spaces occur within the string appearing after TXT, such spaces must be escaped, or the entire string must be enclosed within double quotation marks. The three fields, XFNREF, rformat and reftype, are separated using space (spaces and tabs). rformat specifies format of the reference type identifier. It can be one of the following:

reftype specifies the contents of the reference type identifier.

If no XFNREF TXT record exists, the reference type defaults to an identifier XFN_SERVICE, with an FN_ID_STRING format. If more than one XFNREF TXT record exists, the handling of the record is undefined. The following TXT record is equivalent to the default XFNREF: 


TXT "XFNREF STRING XFN_SERVICE"

The address information for an XFN reference is constructed using TXT records with tags prefixed with the XFN string. Multiple addresses may be specified for a single reference. Records with the same tag are grouped and passed to the handler for each group. Each handler generates zero or more addresses from its group of TXT records and appends the addresses to the reference. The XFNREF tag is special in that it is used only to construct the reference type and thus, it is excluded from the address-construction process.

The syntax of address TXT records is as follows:


XFNaddress_type_tag   address_specific_data

The two fields, XFN_address_type_tag and address_specific_data, are separated using space (spaces and tabs). The address_type_tag specifies the handler to be used for address_specific_data.

TXT records have a limitation of 2K bytes of characters per record. If the address-specific data is too long to be stored in a single TXT record, multiple TXT records may be used, as shown:


TXT "XFNaddress_type_tag address_specific_data1"
TXT "XFNaddress_type_tag address_specific_data2"

When the tag-specific handler is called, both records are passed to it. The handler is responsible for determining the order in which these two lines need to be interpreted.

The order in which TXT records appear is not significant. If lines with different tags are present, lines with the same tag are grouped together before the tag-specific handler is called. In the following example, the handler for tag1 will be called with two text lines, and the handler for tag2 will be called with three text lines.


TXT "XFNtag1 address_specific_data1"
TXT "XFNtag2 address_specific_data2"
TXT "XFNtag1 address_specific_data3"
TXT "XFNtag2 address_specific_data4"
TXT "XFNtag2 address_specific_data5"

Here are some examples of TXT records that can be used for XFN references.

Example 1 


TXT		"XFNREF STRING XFN_SERVICE"
TXT		"XFNNISPLUS doc.com. nismaster 129.144.40.23"

Example 2 


TXT		"XFNREF OID 1.3.22.1.6.1.3"
TXT		"XFNDCE (1 fd33328c4-2a4b-11ca-af85-09002b1c89bb...)"

The following is an example of a DNS table with a subordinate naming system bound in it. 


$ORIGIN test.doc.com
@      IN SOA foo root.eng.doc.com          (
             100    ;; Serial
             3600   ;; Refresh
             3600   ;; Retry
             3600   ;; Expire
             3600   ;; Minimum
          )
       NS    nshost
       TXT   "XFNREF STRING XFN_SERVICE"
       TXT   "XFNNISPLUS doc.com. nismaster 129.144.40.23"
nshost IN  A 129.144.40.21

X.500 Attribute Syntax for XFN References

This section contains supplemental information about the use of X.500 attributes for XFN references. In order to permit an XFN reference to be stored as an attribute in X.500, the directory schema must be modified to support the object classes and attributes defined in this chapter.

Object Classes

Two new object classes, XFN and XFN-supplement, are introduced to support XFN references. The XFN object class is not relevant in FNS since the Sun Microsystems X.500 directory product cannot support the introduction of new compound ASN.1 syntaxes. Instead, FNS uses the XFN-supplement object class.

The two new object classes are defined in ASN.1 as follows:


   xFN OBJECT-CLASS ::= {
            SUBCLASS OF         { top }
            KIND                auxiliary
            MAY CONTAIN         { objectReferenceId |
                                  objectReference |
                                  nNSReferenceId |
                                  nNSReference }
            ID                  id-oc-xFN
        }
        id-oc-xFN OBJECT IDENTIFIER ::= {
            iso(1) member-body(2) ansi(840) sun(113536)
            ds-oc-xFN(24)
        }
   xFNSupplement OBJECT-CLASS ::= {
            SUBCLASS OF         { top }
            KIND                auxiliary
            MAY CONTAIN         { objectReferenceString |
                                  nNSReferenceString }
            ID                  id-oc-xFNSupplement
        }   
        id-oc-xFNSupplement OBJECT IDENTIFIER ::= {
            iso(1) member-body(2) ansi(840) sun(113536)
            ds-oc-xFNSupplement(25)
        }

The XFN-supplement object class is defined as an auxiliary object class so that it may be inherited by all X.500 object classes. It is defined with two optional attributes:

Both attributes are defined in ASN.1 as follows: 


        objectReferenceString ATTRIBUTE ::= {
            WITH SYNTAX             OCTET STRING
            EQUALITY MATCHING RULE  octetStringMatch
            SINGLE VALUE            TRUE
            ID                      { id-at-objectReferenceString }
        }
        id-at-objectReferenceString OBJECT IDENTIFIER ::= {
            iso(1) member-body(2) ansi(840) sun(113536)
            ds-at-objectReferenceString(30)
        }
        nNSReferenceString ATTRIBUTE ::= {
            WITH SYNTAX             OCTET STRING
            EQUALITY MATCHING RULE  octetStringMatch
            SINGLE VALUE            TRUE
            ID                      { id-at-nNSReferenceString }
        }
        id-at-nNSReferenceString OBJECT IDENTIFIER ::= {
            iso(1) member-body(2) ansi(840) sun(113536)
            ds-at-nNSReferenceString(31)
        }

Both objectReferenceString and nNSReferenceString store XFN references in a string form. Their octet string syntax is further constrained to conform to the following BNF definition:


     <ref>          ::= <id> '$' <ref-addr-set>
     <ref-addr-set> ::= <ref-addr> | <ref-addr> '$' <ref-addr-set>
     <ref-addr>     ::= <id> '$' <addr-set>
     <addr>         ::= <hex-string>
     <id>           ::= 'id'   '$' <string> |
                        'uuid' '$' <uuid-string> |
                        'oid'  '$' <oid-string>
     <string>       ::= <char> | <char> <string>
     <char>         ::= <PCS> | '\' <PCS>
     <PCS>          ::= // Portable Character Set:
                        // !"#$%&'()*+,-./0123456789:;<=>?
                        // @ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_
                        // `abcdefghijklmnopqrstuvwxyz{|}~
     <uuid-string>  ::= <uuid-char>  | <uuid-char> <uuid-string>
     <uuid-char>    ::= <hex-digit> | '-'
     <oid-string>   ::= <oid-char>  | <oid-char> <oid-string>
     <oid-char>     ::= <digit> | '.'
     <hex-string>   ::= <hex-octet> | <hex-octet> <hex-string>
     <hex-octet>    ::= <hex-digit> <hex-digit>
     <hex-digit>    ::= <digit> |
                        'a' | 'b' | 'c' | 'd' | 'e' | 'f' |
                        'A' | 'B' | 'C' | 'D' | 'E' | 'F'
     <digit>        ::= '0' | '1' | '2' | '3' | '4' | '5' |
                        '6' | '7' | '8' | '9'

The following example is a string form XFN reference:


id$onc_fn_enterprise$id$onc_fn_nisplus_root$0000000f77697a2e636fd2e2062696762696700

The example uses an XFN reference of type onc_fn_enterprise. It contains the address type onc_fn_nisplus_root and a single address value. The address value is an XDR-encoded string, comprising the domain name, doc.com, followed by the host name, cygnus.

An XFN reference may be added to an X.500 entry by using the FNS command fnattr, as in this example: 


# fnattr -a .../c=us/o=doc object-class top organization xfn-supplement

creates a new entry called c=us/o=doc and adds an object class attribute with the values top, organization , and XFN-supplement.

The FNS command fnbind binds the NIS+ reference to the named entry and links X.500 to the root of the NIS+ namespace. (Note the use of a trailing slash in the name argument to fnbind.) 


# fnbind -r .../c=us/o=doc/ onc_fn_enterprise onc_fn_nisplus_root
 "doc.com. cygnus"

Creating Enterprise Level Contexts

FNS contexts are created using the fncreate command. This section describes how to create FNS contexts individually rather than for the entire organization.. The fncreate command creates a context of the specified type and binds it to the given composite name. It also creates subcontexts for the context.

The fncreate command has the following syntax. 


fncreate -t context_type [-f input_file] [-o][-r reference_type][-s][-v] [-D] composite_name
Table 25–13 fncreate Command Options

Option 

Description 

--t context

Specifies the type of context to create. The context operator can be one of org, hostname, username, host, user, service, site, nsid, generic, or fs.

-f

Creates a context for every host or user listed in input_file. This option can only be used with the -t username or -t hostname option and is useful for creating contexts for a subset of users and hosts found in the corresponding NIS+ passwd and hosts tables, respectively.

-o

Creates only the context specified. Without the -o option, subcontexts are created according to the FNS policies.

-r

Specifies the reference_type of the generic context being created. It can only be used with the -t generic option.

-s

Creates new contexts for composite names already in use. Otherwise, no new contexts are created for names already bound. 

-D

Displays information about the NIS+ object associated with a context each time a context is created. This option is useful for debugging. 

-v

Displays information about the creation as each context is created. 

Note –

If you specify the -o option when creating an organization context, the associated host, user, and service contexts are still created but they are not populated.

When creating contexts bound to namespace identifiers, the name without the underscore (for example, user) is used to create the context and the name with the underscore (for example, _user) is then bound to the reference of the newly created context. This is done regardless of whether the name with or without the underscore is specified in the command line.

For example, the command


fncreate -t username org/sales/_user

creates a context for org/sales/user and adds a binding for org/sales/_user to the context of org/sales/user.

Creating an Organization Context

Use the org type to create an organization context. The composite name must be one of the following, depending on the primary naming service:

Organization Context NIS+ Example

Assume the root NIS+ domain is doc.com and the subdomain is sales.doc.com. To create a sales organization context to correspond to the sales subdomain, you would enter the following command: 


fncreate -t org org/sales/

When the new context is created, a ctx_dir directory, if it does not already exist, is created under the directory of the domain, sales.doc.com.

Because this example used only the -t option without the -o option, it created an organization context for the composite name org/sales/ and, in addition, created hostname, username, and service subcontexts for it, which in turn, created host and user contexts, and service subcontexts for hosts and users. In effect, that is the same as running the following commands:


fncreate -t hostname org/sales/host/
fncreate -t username org/sales/user/
fncreate -t service org/sales/service/

If, instead, you ran fncreate -o -t org, the org context is created and the hostname, username, and service contexts are also created, but not populated with host and user contexts.

The org context is owned by the administrator who executed the fncreate command, as are the hostname, username, and service subcontexts. The host and user contexts, however, and their subcontexts are owned by the hosts or users for which the contexts were created. In order for the administrator to subsequently manipulate host and user contexts, the NIS_GROUP environment variable must have been set accordingly at the time fncreate is executed. For example, assuming a C-Shell, to set NIS_GROUP to fns_admins.doc.com: 


rootmaster# setenv NIS_GROUP fns_admins.doc.com

All Hosts Context

The hostname type creates a hostname context in which host contexts can be created and bound. Host contexts and their subcontexts are created for each machine name found in the NIS+ hosts.org_dir table unless the -o option is used. When the -o option is used, only the hostname context is created.

For example, running the command 


fncreate -t hostname org/sales/host/

creates the hostname context and effectively runs the command:


fncreate -t host org/sales/host/hname

Where hname is the name of each machine found in the hosts.org_dir table. It also adds a binding for org/sales/_host/ that is bound to the reference of org/sales/host/.

The hostname context is owned by the administrator who executed the fncreate command. A host context and its subcontexts are owned by the machine for which the contexts were created. That is, each host owns its own host context and subcontexts.

The -f option can be used to create contexts for a subset of the hosts found in the NIS+ table hosts.org_dir. It creates contexts for those hosts listed in the given input file.

Single Host Context

The host type creates the context and subcontexts for a single host. The command automatically creates a service context for the host and a binding for fs unless the -o option is used. When the -o option is used, only the host context is created.

For example, the command 


# fncreate -t host org/sales/host/antares/

creates a context for the host named antares and effectively runs the commands


fncreate -t service org/sales/host/antares/service/
fncreate -t fs org/sales/host/antares/fs/

The host context and its subcontexts are owned by the machine. In the above example, the machine antares, with NIS+ principal name antares.sales.doc.com, owns the contexts:

The hostname context (org/sales/host in the above example) to which the machine belongs must already exist. The machine name supplied should already exist in the NIS+ hosts.org_dir table.

Host Aliases

Alias host names may exist in an NIS+ hosts.org_dir table. These appear in the table as a set of hosts with the same canonical name but different alias names.

In FNS, a single host with multiple alias names has a single host context. Alias names for that host in the hostname context are bound to the reference of that host context.

All–Users Context

The username type creates a username context in which individual user contexts can be created and bound. User contexts and their subcontexts are created for each user name found in the NIS+ passwd.org_dir table unless the -o option is used. When the -o option is used, only the username context is created.

For example, running the command


# fncreate -t username org/sales/user/

creates the username context and effectively runs the command:


fncreate -t user org/sales/user/uname

Where uname represents the various user names that appear in the passwd.org_dir table. It also adds a binding for org/sales/_user/ that is bound to the reference of org/sales/user/.

The username context is owned by the administrator who executed the fncreate command. Individual user contexts and their subcontexts are owned by the users for which the contexts were created. Each user owns his or her own user context and subcontexts.

The -f option can be used to create contexts for a subset of the users found in the NIS+ table passwd.org_dir. It creates contexts for those users listed in the given input file.

Single User Context

The user type creates the user context and subcontexts for a user. A service subcontext and a binding for fs are created under the user context unless the -o option is used. When the -o option is used, only the user context is created.

For example, the command


# fncreate -t user org/sales/user/jjones/

creates the user context for the user named jjones and effectively runs the commands 


fncreate -t service org/sales/user/jjones/service/
fncreate -t fs org/sales/user/jjones/fs/

The user context and its subcontexts are owned by the user for whom the contexts were created. In the above example, the contexts created are owned by the user jjones with NIS+ principal name jjones.sales.doc.com.

The username context (org/sales/user in the above example) to which the user belongs must already exist. The user name supplied should already exist in the NIS+ passwd.org_dir table.

Service Context

The service type creates the service context in which service names can be bound. There is no restriction on what type of references may be bound in a service context. The policies depend on the applications that use the service context. For example, a group of desktop applications may bind references for a calendar, a telephone directory, a fax service, and a printer in a service context.

For example, the command 


# fncreate -t service org/sales/service/

creates a service context for the organization sales. Because the terminal atomic name is a namespace identifier, fncreate also adds a binding for org/sales/_service/ that is bound to the reference of org/sales/service/. After executing this command, names such as org/sales/service/calendar and org/sales/service/fax can then be bound in this service context.

The service context supports a hierarchical namespace, with slash-separated left-to-right names. The service namespace can be partitioned for different services. Continuing with the desktop applications example, a group of plotters may be named under the service context after the creation of the plotter context.


# fncreate -t service org/sales/service/plotter

Names such as org/sales/service/plotter/speedy and org/sales/service/plotter/color could then be bound under the service context.

Note –

Because the terminal atomic name is not a namespace identifier, no additional binding is added (as was the case with service and _service).

The service context created is owned by the administrator who ran the fncreate command.

Printer Context

The printer context is created under the service context of the respective composite name.

Generic Context

The generic type creates a context for binding names used by applications.

A generic context is similar to a service context except it can have a different reference type. The -r option is used to specify the reference type for the generic context being created. If it is omitted, the reference type is inherited from its parent generic context or, if the parent context is not a generic context, the reference type used is a default generic reference type.

Like a service context, there is no restriction on what type of references may be bound in a generic context. The policies depend on the applications that use the generic context.

For example, the command 


# fncreate -t generic -r WIDC_comm org/sales/service/extcomm

creates a generic context with the WIDC_comm reference type under the service context of the organization sales. Names such as org/sales/service/extcomm/modem can then be bound in this generic context.

The generic context supports a hierarchical namespace, with slash-separated left-to-right names, which allows an application to partition its namespace for different services. Continuing with the example above, a generic subcontext for modem can be created running the command


# fncreate -t generic org/sales/service/extcomm/modem

Names such as org/sales/service/extcomm/modem/secure and org/sales/service/extcomm/modem/public could then be bound under the modem context.

The generic context created is owned by the administrator who ran the fncreate command.

Site Context

The site type creates contexts in which site names can be bound.

For example, the command 


# fncreate -t site org/sales/site/

creates a site context. Because the terminal atomic name is a namespace identifier, fncreate also adds a binding for org/sales/_site/ that is bound to the reference of org/sales/site/.

The site context supports a hierarchial namespace, with dot-separated right-to-left names, which allows sites to be partitioned by their geographical coverage relationships.

For example, the commands


# fncreate -t site org/sales/alameda
# fncreate -t site org/sales/site/alameda.bldg-5

create a site context alameda and a site subcontext alameda.bldg-5 for it.

Note –

Because these terminal atomic names are not namespace identifiers, no additional bindings are added (as was the case with site and _site).

The site context created is owned by the administrator who ran the fncreate command.

File Context

The fs type creates a file system context (or file context) for a user or a host. For example, the command 


# fncreate -t fs org/sales/user/petrova/fs/

creates the fs context for user petrova. Because the terminal atomic name is a namespace identifier, fncreate also adds a binding for org/sales/user/petrova/_fs/ that is bound to the reference of org/sales/user/petrova/fs/.

The fs context of a user is the user's home directory as it is stored in the NIS+ passwd.org_dir table. The fs context of a host is the set of NFS file systems that the host exports.

Use the fncreate_fs command to create file contexts for organizations and sites or to create file contexts other than the defaults for users and hosts. See File Contexts Administration for details.

The fs context created is owned by the administrator who ran the fncreate command.

Namespace Identifier Context

The nsid (namespace identifier) type creates a context in which namespace identifiers can be bound.

For example, the command 


# fncreate -t nsid org/sales/site/alameda.bldg-5/

creates the nsid context for the site alameda.bldg-5 and permits the creation of subcontexts such as service/. Continuing with this example, you could then execute the command


# fncreate -t service org/sales/site/alameda.bldg-5/service/

to create the service context for alameda.bldg-5.

The nsid context created is owned by the administrator who ran the fncreate command.

Administering Enterprise Level Contexts

A number of tools are provided for examining and managing FNS contexts. The commands and their syntax are shown in the sections that follow.

Displaying the Binding

fnlookup displays the binding of the given composite name. 


fnlookup [-v][-L] composite_name
Table 25–14 fnlookup Command Options

Option 

Description 

-v

Displays the binding in more detail 

-L

Displays the reference to which the XFN link is bound 

For example, to show the binding for the user darwin in detail, you would enter:


# fnlookup -v user/darwin/
Reference type: onc_fn_user
Address type: onc_fn_nisplus
 length: 52
 context type: user
 representation: normal
 version: 0
 internal name: fns_user_darwin.ctx_dir.sales.doc.com.

Suppose user/Charles.Darwin is linked to user/darwin. The first command in the following example shows what user/Charles.Darwin is bound to (an XFN link). The second command follows the XFN link, user/darwin, and shows what user/darwin is bound to (the user context).


# fnlookup user/Charles.Darwin
Reference type: fn_link_ref
Address type: fn_link_addr
 Link name: user/darwin
# fnlookup -L user/Charles.Darwin
Reference type: onc_fn_user
Address type: onc_fn_nisplus
 context type: user

Listing the Context

fnlist lists the contents of the context identified by the given name. 


fnlist [-lv] [name]
Table 25–15 fnlist Command Options

Option 

Description 

-v

Displays the binding in more detail 

-l

Displays the bindings of the names bound in the named context 

For example, to display the bindings under the user context:


# fnlist user/
Listing 'user/':
jjones
julio
chaim
James.Jones

If no name is given, the command lists the contents of the initial context.


# fnlist
Listing '':
_myorgunit
...
_myself
thishost
myself
_orgunit
_x500
_host
_thisens
myens
thisens
org
orgunit
_dns
thisuser
_thishost
myorgunit
_user
thisorgunit
host
_thisorgunit
_myens
user

When the -l option is given, the bindings of the names bound in the named context are displayed.


# fnlist -l user/
Listing bindings 'user/':
name: julio
Reference type: onc_fn_user
Address type: onc_fn_nisplus
 context type: user
name: chaim
Reference type: onc_fn_user
Address type: onc_fn_nisplus
 context type: user
name: James.Jones
Reference type: fn_link_ref
Address type: fn_link_addr
 Link name: user/jjones
name: jjones
Reference type: onc_fn_user
Address type: onc_fn_nisplus
 context type: user

When the -v option is given in conjunction with the -l option, the bindings are displayed in detail.


# fnlist -lv user/
Listing bindings 'user/':
name: julio
Reference type: onc_fn_user
Address type: onc_fn_nisplus
 length: 52
 context type: user
 representation: normal
 version: 0
 internal name: fns_user_julio.ctx_dir.sales.doc.com.
name: chaim
Reference type: onc_fn_user
Address type: onc_fn_nisplus
 length: 52
 context type: user
 representation: normal
 version: 0
 internal name: fns_user_chaim.ctx_dir.sales.doc.com.
name: James.Jones
Reference type: fn_link_ref
Address type: fn_link_addr
 length: 11
 data: 0x75 0x73 0x65 0x72 0x2f 0x6a 0x6a 0x6f 0x6e 0x65
user/jjones
name: jjones
Reference type: onc_fn_user
Address type: onc_fn_nisplus
 length: 52
 context type: user
 representation: normal
 version: 0
 internal name: fns_user_jjones.ctx_dir.sales.doc.com.

Binding a Composite Name to a Reference

fnbind allows you to bind a composite name to a reference.

There are two uses of this command.

Binding an Existing Name to a New Name

The syntax of fnbind for binding existing names to new names is: 


fnbind [-s][-v][-L] oldname newname
Table 25–16 fnbind Command Options (Binding Names)

Option 

Description 

oldname

The existing composite name. 

newname

The new name to which you are binding the old name. 

-s

Supersedes any existing binding of the original composite name. 

-v

Prints out the reference used for the binding. 

-L

Creates an XFN link using name and binding it to new_name.

For example, to bind the name user/julio/service/printer to the reference of myorgunit/service/printer you would enter:


# fnbind myorgunit/service/printer user/julio/service/printer

If the given newname is already bound, fnbind -s must be used or the operation will fail. In the above example, if user/julio/service/printer is already bound, the -s option must be used to overwrite the existing binding with that of myorgunit/service/printer as shown below:


# fnbind -s myorgunit/service/printer user/julio/service/printer

The -v option prints out the reference used for the binding.


# fnbind -v myorgunit/service/printer user/julio/service/printer
Reference type: onc_printers
Address type: onc_fn_printer_nisplus

The following command constructs an XFN link out of user/jjones and binds it to the name user/James.Jones:


# fnbind -L user/jjones user/James.Jones

Similarly, to create a link from user/julio/service/printer to myorgunit/service/printer you would enter:


# fnbind -sL myorgunit/service/printer user/julio/service/printer

Constructing a Reference on the Command Line

The syntax of fnbind for building a reference on the command line is: 


fnbind -r [-s] [-v] newname [-O | -U] reftype {[-O | -U] | addresstype 
[-c|-x] addresscontents}+
Table 25–17 fnbind Command Options (Reference Construction)

Option 

Description 

newname

The new name for which you are constructing a reference. 

reftype

The type of reference you are creating. Unless the -O or -U options are used, FN_ID_STRING is used as the indentifier for reftype.

addresstype

The type of address you are creating. Unless the -O or -U options are used, FN_ID_STRING is used as the indentifier for addresstype.

addresscontents

The address of the reference you are creating. Unless the -c or -x options are used, the address is stored as an XDR-encoded string.

-s

Supersedes any existing binding of the original composite name. 

-v

Prints out the reference used for the binding. 

-c

Stores address contents without XDR encoding. 

-x

Interprets address contents as a hexadecimal input string and store it as is. 

-r

Creates a reference with a specified type and binds the reference to a name specified on the command line. 

-O

Interprets and stores type string as ASN.1 dot-separated integer list. 

-U

Interprets and stores type string as a DCE UUID. 

For example, to bind the name thisorgunit/service/calendar to the address contents of staff@cygnus with a reference type of onc_calendar and and an address type onc_cal_str you would enter:


# fnbind -r thisorgunit/service/calendar onc_calendar 
onc_cal_str staff@cygnus

By default, the address contents supplied in the command line is XDR-encoded before being stored in the reference. If the -c option is given, the address contents are stored in normal, readable characters, not as an XDR-encoded string. If the -x option is given, the address contents supplied in the command line are interpreted as a hexadecimal string and stored (and not XDR-encoded).

By default, the reference and address types of the reference to be constructed uses the FN_ID_STRING identifier format. If the -O option is given, the identifier format is FN_ID_ISO_OID_STRING, an ASN.1 dot-separated integer list string. If the -U option is given, the identifier format is FN_ID_DCE_UUID, a DCE UUID in string form.

Note –

For more information on ASN.1, see ISO 8824: 1990, Information Technology — Open Systems Interconnection — Specification of Abstract Syntax Notation One (ASN.1). For more information on DCE UUID see X/Open Preliminary Specification, October 1993, X/Open DCE: Remote Procedure Call (ISBN: 1-872630-95-2).

For example, to bind to the name thisorgunit/service/nx a reference with a hexadecimal string as the address contents and OIDs as reference and address types, you would enter:


# fnbind -r thisorgunit/service/nx -O 1.2.99.6.2.1 
-O 1.2.99.6.2.3 -x ef12eab67290

Removing a Composite Name

fnunbind removes the given composite name from the namespace. Note that this does not remove the object associated with the name; it only unbinds the name from the object.

For example, to remove the binding associated with the name user/jjones/service/printer/color, you would enter:


# fnunbind user/jjones/service/printer/color

Renaming an Existing Binding

The fnrename command renames an existing binding.

For example, to rename the binding of clndr to calendar, in the context named by user/jjones/service/ you would enter:


# fnunbind user/jjones/service/printer/color

Destroying a Context

fndestroy removes the given composite name from the namespace and destroys the context named by the composite name.

For example, to unbind the name user/jones/ from the namespace and destroys the context named by user/jjones/ you would enter:


# fndestroy user/jjones/

If the composite name identifies a context to be removed, the command fails if the context contains subcontexts.

Administering FNS: Attributes Overview

Attributes can be applied to named objects. Attributes are optional. A named object can have no attributes, one attribute, or multiple attributes.

Each attribute has a unique attribute identifier, an attribute syntax, and a set of zero or more distinct attribute values.

XFN defines the base attribute interface for examining and modifying the values of attributes associated with existing named objects. These objects can be contexts or any other type of object. Associated with a context are syntax attributes that describe how the context parses compound names.

The extended attribute interface contains operations that search for specific attributes and that create objects and their associated attributes.

Examining Attributes

Search for attributes with the fnsearch command.

The syntax of the fnsearch command is 


fnsearch [-ALlv] [-n max] [-s scope] name [-a ident]... [-O|-U] filter_expr [filter_arg]
Table 25–18 fnsearch Command Options

Option 

Description 

-n max

Display only max number of objects. 

-s scope

Set the scope of the search. 

-a ident

Display only those attributes that match ident. 

name

Composite name. 

filter_expr

Boolean, logical, grouping, relational, and comparison operators (see Table 25–19).

filter_arg

Arguments for filter expressions (see Table 25–19).

-A

Consult only the authoritative source. 

-L

Follow XFN links. 

-l

Display the object references for the matching objects. 

-v

Verbose. Display detailed object references for the matching objects. 

-O

Use an OSI OID as the identifier. 

-U

Use a DCE UUID as the identifier. 

Searching for Objects Associated With an Attribute

With the fnsearch command, you can search for objects that are associated with the attributes you choose.

For example, to find all the objects that are associated with the attribute for_sale in orgunit/sales/site/, you would enter the following command:


 % fnsearch orgunit/sales/site/ for_sale

Customizing Attribute Searches

You can also use all the following in filter expressions in your search patterns.

Table 25–19 fnsearch Filter Expression Operators

Filter Expression Operator 

Symbols and Forms 

Logical operators 

or, and, not

Parentheses for grouping 

( )

Relational operators: Compare an attribute to a supplied value 

== True if at least one attribute value is equal to the supplied value. != True if none of the attribute values are equal to the supplied value. < True if at least one attribute value is less than the supplied value. <= True if at least one attribute value is less than or equal to the supplied value. > True if at least one attribute value is greater than the supplied value. >= True if at least one attribute value is greater than or equal to the supplied value. ~= True if at least one attribute value matches the supplied value according to some context-specific approximate matching criterion. This criterion must subsume strict equality.

Example: 

% fnsearch name "not (make == 'olds' and year == 1983)"

Substitution tokens: 

Helpful when writing shell scripts; allow the use of OSI OIDs and DCE UUIDs when used with the -O and -U options

%a for attribute

%s for string

%i for identifier

%v for attribute value (only fn_attr_syntax_ascii is currently supported)

Example: 

The following three examples are equivalent. 

% fnsearch name "color == 'red'"

% fnsearch name "%a == 'red'" color

% fnsearch name "%a == %s" color red

Wild card strings 

*, *string, string*, str*ing, %s*

Extended operators 

'name'(wildcarded_string), 'reftype'(identifier), 'addrtype' (identifier)

Example: 

Search for objects with names starting with "Bill" and IQ attributes over 80. 

% fnsearch name "'name'('bill'*) and IQ > 80"

See the fnsearch man page for detailed information about creating search patterns.

Updating Attributes

The fnattr command lets you update and examine attributes associated with FNS named objects. You can perform four attribute operations with the fnattr command: 


fnattr -a [-s] name [-O|-U] identifier values


fnattr -d name [[-O|-U] identifier [values]]
 

fnattr -m name [-O|-U identifier oldvalue newvalue


fnattr -l name [[-O|-U] identifier
Table 25–20 fnattr Command Options

Option 

Description 

name

Composite name. 

identifier

Attribute name. 

values

One or more attributes values. 

oldvalue

The attribute value that you want to change. 

newvalue

The new attribute value. 

-aa

Add (create) a new attribute. 

-d

Delete an attribute. 

-m

Change (modify) an attribute. 

-l

List attribute values. 

-s

Add in “supersede” mode. Removes any existing values for the identifier attribute and creates new attribute values.

-l

List attributes and values. 

-O

Use an OSI OID as the identifier. 

-U

Use a DCE UUID as the identifier. 

In each of these cases, the identifier format is FN_ID_STRING, unless the option -O or -U is used.

Adding an Attribute

The -a option is for adding an attribute or adding a value to an attribute. Specify the composite name the attribute is associated with, the attribute identifier, and the values to add.


fnattr -a [-s] name [-O | -U] identifier value1 [value2+]

The following example adds the attribute identifier model and the value hplaser to thisorgunit/service/printer.


# fnattr -a thisorgunit/service/printer model hplaser

The -s option means “add in supersede” mode. If an attribute with the specified identifier already exists, -s removes all of its values and replaces them with the values added. If this option is omitted, the resulting values for the specified attribute includes the existing values and the new values added.


# fnattr -as thisorgunit/service/printer model hplaser

The example above will first remove any existing values associated with model and add hplaser as the value.

Deleting an Attribute

To delete an attribute associated with an FNS named object, use the -d option.


fnattr -d name [[-O | -U] identifier value1 [value2+]]]

You can control what to delete:

For example, to delete all the attributes associated with thisorgunit/service/printer.


# fnattr -d thisorgunit/service/printer

Listing an Attribute

The -l option is for listing attributes and their values.


fnattr -l name [[-O | -U] identifier]

For example to list the values of the model attribute of thisorgunit/service/printer.


# fnattr -l thisorgunit/service/printer model
laser
postscript

If an identifier is not specified, all the attributes associated with the named object are displayed.

Modifying an Attribute

The -m option lets you modify an attribute value.


fnattr -m name [-O | -U] identifier old_value new_value

For example, to replace the value postscript with laser you would enter:


# fnattr -m thisorgunit/service/printer model postscript laser

Only the specified values are affected. Other attributes and values associated with the name are not affected.

Other Options

The -O option assumes the format of the attribute identifier is an ASN.1 dot-separated integer string list (FN_ID_ISO_OID_STRING).

The -U option assumes the format of the attribute identifier is a DCE UUID string form (FN_ID_DCE_UUID).

FNS and Enterprise-Level Naming Services

Enterprise-level naming services are used to name objects within an enterprise. FNS currently supports three enterprise-level naming services: NIS, NIS+, and local files.

Choosing an Enterprise-Level Name Service

When you initially set up and configure your FNS namespace with the fncreate command., See Preparing the Namespace for FNS for information on how to set up the namespace. the correct default name service is automatically selected for each machine.

If you later change a machine's primary enterprise-level name service, you should run the fnselect command on that machine. See Selecting a Naming Service for details.

FNS and Naming Service Consistency

As a system administrator one of your tasks is to maintain consistency between FNS and the underlying naming service by ensuring that the contents of FNS contexts and the files, maps, or tables of the underlying naming service correspond.

When you initially set up and configure your FNS namespace with the fncreate command as described in Preparing the Namespace for FNS, fncreate ensures that FNS contexts are correctly created and are consistent with the underlying naming service data. After the FNS contexts have been set up, this correspondence needs to be maintained as users, hosts, printers, and so forth are added to and removed from the system. The following sections describe how to maintain FNS and name service consistency.

FNS and Solstice AdminSuite

If you have the Solstice AdminSuite product, you can use it to add, change, or delete user and host information in the underlying name service. This is a recommended method because the AdminSuite tools update the corresponding FNS namespace automatically.

Checking Naming Inconsistencies

When updates to FNS or the primary name service are made independent of the Solstice AdminSuite product, the resulting inconsistencies are resolved by the use of the FNS tool, fncheck. The fncheck command checks for inconsistencies between the FNS hostname and user contexts, and:

The fncheck command lists those host and user names that are in the FNS namespace but not in the name service data, and those host and user names that are in the name service data but not in the FNS namespace.

The command syntax is: 


fncheck [-r][-s][-u][-t hostname|username][domain_name]
Table 25–21 fncheck Command Options

Option 

Description 

domain

Apply the command to an NIS+ domain other than the one in which you are running the command. 

-t

Specifies the type of context to check. Allowed types are hostname or username.

-s

Lists host or user names from the namespace dataset that are not in the FNS namespace 

-r

Lists host or user names from the FNS namespace that do not have entries in the corresponding namespace dataset 

-u

Updates the FNS namespace based on information in the relevant namespace dataset 

The -t option is used to specify the contexts to check (host or user). If you omit the -t option, both the hostname and username contexts are checked.

When the -r option is used with the -u option, items that appear only in the FNS context are removed from the FNS context. When the -s option is used with the -u option, items that appear only in the namespace dataset are added to the FNS context. If neither -r or -s are specified, items are added and removed from the FNS context to make it consistent with the corresponding namespace data.

Selecting a Naming Service

When FNS constructs the bindings in the initial context for a machine, it does so on the basis of a particular naming service.

You can choose which name service FNS is to use with the fnselect command. The name service setting you specify with fnselect affects the entire machine, all applications running on that machine, and all users logged in to that machine.

Only root can run fnselect. The command syntax is: 


fnselect [-D] [namesvc]
Table 25–22 fnselect Command Options

Option 

Description 

namesvc

The naming service you want to select. Must be one of: default, nisplus, nis, or files.

-D

Display the naming service used to generate the FNS initial context. 

For example, to select NIS+ as a machine's name service:


#fnselect nisplus

For example, to select the default as a machine's name service and print the name of the service used to generate the FNS initial context:


#fnselect -D default

Default Naming Service

If you do not designate a naming service with fnselect, FNS uses the default naming service. The default naming service is determined by FNS based on the name service that the machine is using. If the machine is an NIS+ client, FNS uses NIS+ as the name service. If the machine is an NIS client, FNS uses NIS. If the machine is neither an NIS+ nor an NIS client, FNS uses /etc files as the machine's default name service.

When NIS+ and NIS Coexist

In rare cases you may need to access both NIS+ and NIS-based contexts. For example, you might have an NIS server running that is itself an NIS+ client. In this situation, you use the fnselect command to select the enterprise-level naming service that you want to work with.

Advanced FNS and NIS+ Issues

This section provides detailed information on the relationship between NIS+ objects and FNS objects. This information is useful when you must change the access control of FNS objects.

Note –

See:

Mapping FNS Contexts to NIS+ Objects

FNS contexts are stored as NIS+ objects. All contexts associated with an organization are stored under the FNS ctx_dir directory of the associated NIS+ domain. The ctx_dir directory resides at the same level as the org_dir directory of the same domain. In other words, when running in conjunction with FNS, for every NIS+ domain or subdomain, there are corresponding org_dir, groups_dir and ctx_dir directory objects.

Use the -v option for the fnlookup or fnlist command to see the detailed description of references. The internal name field displays the name of the corresponding NIS+ object.

Browsing FNS Structures Using NIS+ Commands

The NIS+ command, nisls, can be used to list the NIS+ objects used by FNS. For example, the following commands list the contents of the NIS+ domain directory and its ctx_dir subdirectory. 


# nisls doc.com.
doc.com.:
manf
sales
groups_dir
org_dir
ctx_dir
 

# nisls ctx_dir.doc.com.
ctx_dir.DOC.COM.:
fns
fns_user
fns_host
fns_host_alto
fns_host_mladd
fns_host_elvira
fns_user_jjones
fns_user_jsmith
fns_user_aw

Use the niscat command to list the contents of the fns_hosts table. 


# niscat fns_host.ctx_dir
altair *BINARY* *BINARY*
cygnus *BINARY* *BINARY*
centauri *BINARY* *BINARY*

Checking Access Control

Use niscat -o to see the access control of a context. To see the access control of a particular binding, use the name of the binding entry in the parent context's binding table (that is, the name displayed in the internal name field in the output of fnlookup -v and fnlist -v): 


# niscat -o fns_host.ctx_dir
Object Name     	:	fns_host
Owner           	:	alto.doc.com.
Group      	        :       admin.doc.com.
Domain	                :	ctx_dir.doc.com.
Access Rights   	:	r-c-rmcdrmcdr-c-
Time to Live    	:	53:0:56
Object Type     	:	TABLE
Table Type      	:	H
Number of Columns	:	3
Character Separator	
Search Path     	:
Columns         	:
[0]	Name    	:	atomicname
	Attributes	:	(SEARCHABLE, TEXTUAL DATA,	CASE INSENSITIVE)
	Access Rights	:	r-c-rmcdrmcdr-c-
[1]	Name    	:	reference
	Attributes	:	(BINARY DATA)
	Access Rights	:	r-c-rmcdrmcdr-c-
[2]	Name    	:	flags
	Attributes	:	(BINARY DATA)
	Access Rights	:	r-c-rmcdrmcdr-c-
 

# niscat -o "[atomicname=altair],fns_host.ctx_dir"
Object Name	:	fns_host
Owner   	:	altair.doc.com.
Group   	:       admin.doc.com.
Domain  	:	ctx_dir.doc.com.
Access Rights	:	r-c-rmcdrmcdr-c-
Time to Live	:	12:0:0
Object Type	:	ENTRY
 Entry data of type H
 [1] - [5 bytes] 'alto'
 [2] - [104 bytes] '0x00 ...'
 [3] - [1 bytes] 0x01

(See The niscat Command for additional information on the niscat command.)

To change the access control or ownership of a particular context, use the commands:

Give either the binding entry or the bindings table as an argument, depending on the object the operation is to affect.

Advanced FNS and NIS Issues

This section provides specific information on the relationship between NIS and FNS.

NIS and FNS Maps and Makefiles

FNS uses six new maps which are stored in /var/yp/domainname directories on the NIS master and slave servers:

Service and file context information for hosts, users, and the organization are stored in the respective fns_host.ctx, fns_user.ctx, and fns_org.ctx maps. Printer context information is stored in the same maps as other service context information. However, the older printers.conf.byname map is still supported.

Sites are subcontexts of the organization and site context information is stored in the fns_org.ctx map.

Note –

These FNS maps should not be edited directly. You modify or work with these maps by running the appropriate FNS commands such as fncreate, fndestroy, fnbind, fnunbind, fnrename, fnattr, fnlookup, and fnlist. These commands must be run on the NIS master server. You cannot run them on slave servers or client machines.

The FNS map files are placed in the /var/yp/domainname directory. The NIS Makefile in /var/yp is modified to be aware of the FNS Makefile in /etc/fn/domainname.

Large FNS Contexts

NIS has a 64K limit on the number of entries an NIS map can contain. If only service and printer contexts are created for each object (host or user), that limit will be reached when the number of users or hosts exceeds 7K. If additional contexts are created for hosts or users, as is usually the case, the upper 64K limit will be reached with far fewer hosts or users.

FNS solves this problem by automatically creating new maps after an old map has reached its maximum size. Each new map is identified by adding a numeric suffix to the map's name. For example, when a second fns_user.ctx map is created it is given the name fns_user_0.ctx. If a third map became necessary it would be given the name fns_user_1.ctx. As additional maps are created, the number is incremented each time.

Printer Backward Compatibility

In Solaris release 2.5, FNS support for printer naming under NIS was provided for the organization context with a map named printers.conf.byname. In the current Solaris release, organization context printer support is maintained in the fns_org.ctx map. That is, the fncreate_printer command now modifies the fns_org.ctx map and not the printers.conf.byname map.

Migrating From NIS to NIS+

The fncopy command handles the FNS-related aspects of changing your underlying enterprise-level naming service from NIS to NIS+. This command copies and converts NIS-based FNS contexts to NIS+ based contexts.

The command syntax is: 


fncopy [-i oldsvc -o newsvc] [-f filename] oldctx newctx
Table 25–23 fncopy Command Options

Option 

Description 

-i oldsvc

Source naming service. Only nis or files may be specified.

-o newsvc

Target naming service. Only nisplus or nis may be specified.

-f filename

Name of file listing the FNS contexts to be copied 

oldctx

Old FNS context to be copied. 

newctx

Target new FNS context. 

For example, to copy the contexts listed in the file /etc/sales_users from the doc.com domain of an NIS-based naming service to the sales.doc.com domain of an NIS+ naming service, you would enter:


fncopy -i nis -o nisplus -f /etc/sales_users org/sales.doc.com/user

Advanced FNS and File-Based Naming Issues

This section provides specific information on the relationship between files-based naming and FNS.

FNS Files

FNS uses new files which are stored in /var/fn directories on each machine. (While a /var/fn directory is normally stored on each machine, you can mount and export a central /var/fn directory via NFS.)

The new FNS files are:

Service and file context information for hosts, users, and the organization are stored in the respective fns_host.ctx, fns_user.ctx, and fns_org.ctx files. Printer context information is stored in the same files as other service context information.

Sites are subcontexts of the organization and site context information is stored in the fns_org.ctx file.

Note –

These FNS files should not be edited directly. You modify or work with these files by running the appropriate FNS commands such as fncreate, fndestroy, fnbind, fnunbind, fnrename, fnattr, fnlookup, and fnlist. When you run these commands as root, they affect the context that they are applied to such as hosts, site, and organization unit. When you run these commands as a user, they affect only your own user sub-contexts.

Migrating From Files-Based Naming to NIS or NIS+

The fncopy command handles the FNS-related aspects of changing your underlying enterprise-level naming service from files to NIS or NIS+. This command copies and converts files-based FNS contexts to NIS or NIS+ based contexts.

The command syntax is: 


fncopy [-i oldsvc -o newsvc] [-f filename] oldctx newctx

For example, to copy the contexts listed in the file /etc/host_list to the doc.com domain of an NIS+ naming service, you would enter:


fncopy -i files -o nisplus -f /etc/host_list //doc.com/host

Printer Backward Compatibility

In Solaris release 2.5, FNS support for printer naming for files was provided for the organization context with a file named printers.conf.byname. In the current Solaris release, organization context printer support is maintained in the fns_org.ctx map. That is, the fncreate_printer command now modifies the fns_org.ctx map and not the printers.conf.byname map.

File Contexts Administration

File contexts may be:

Creating a File Context With fncreate_fs

The fncreate_fs command creates file contexts for organizations and sites. It may also be used to override the default file contexts for users and hosts that are created by the fncreate command.

There are two methods of using the fncreate_fs command.

The two methods of fncreate_fs have the following syntax: 


fncreate_fs [-v] [-r] -f  file composite_name
fncreate_fs [-v] [-r] composite_name [options] [location...]
Table 25–24 fncreate_fs Command Options

Option 

Description 

composite_name

The composite name of the file context. 

-f file

Use an input file named file.

options

Mount options. 

location

Mount location. 

-v

Sets verbose output, displaying information about the contexts being created and modified. 

-r

Replaces the bindings in the context named by composite_name —and all of its subcontexts—with only those specified in the input. This is equivalent to destroying the context (and, recursively, its subcontexts), and then running fncreate_fs without this option. The -r option should be used with care.

The fncreate_fs command manipulates FNS contexts and bindings of the onc_fn_fs reference type. It uses an address of type onc_fn_fs_mount to represent each remote mount point. The data associated with an address of this type are the corresponding mount options and locations in a single, XDR-encoded string.

Creating File Contexts With an Input File

The input file supplies the names and values to be bound in the context of composite_name. Its format is based upon and similar, but not identical, to the format of indirect automount maps. The input file contains one or more entries with the form:


name [options] [location...]

Where:

For each entry a reference to the mount locations and the corresponding mount options is bound to the name composite_name/name.

If options and location are both omitted, then no reference is bound to composite_name/name. Any existing reference is unbound.

For example, suppose you want kuanda's file system to be an NFS mount of the directory /export/home/kuanda from host altair as shown in Figure 25–3. The command would be run as follows:


% fncreate_fs -f infile user/kuanda/fs

With infile containing: 


. altair:/export/home/kuanda

To set up a more complex file system distributed over more than one server as shown in Figure 25–4, run the command


% fncreate_fs -f infile org/sales/fs

with infile containing


tools/db	 	altair:/export/db
project		 	altair:/export/proj
project/lib             altair:/export/lib
project/src	 	deneb:/export/src

To change the NFS mounts for project and its subcontexts src and lib to be read-only, you can change infile as follows:


tools/db 	 			svr1:/export/db
project	      -ro			svr1:/export/projproject/lib 
altair:/export/lib
project/src	 			svr2:/export/src

The -ro is unnecessary in the third and fourth lines because src and lib are subcontexts of project, they will inherit the -ro mount option from above.

The following input file would make all of the mounts read-only except for org/sales/fs/project/src.


.	 		-ro
tools/db 			 	svr1:/export/db
project	 				svr1:/export/proj
project/lib altair:/export/lib
project/src         -rw	         svr2:/export/src

Creating File Contexts With Command-line Input

The fncreate_fs command also allows the binding description to be provided on the command line: 


fncreate_fs composite_name [mmount_options] [mount_location ...]

This is equivalent to using the input file form of the command but entering the individual bindings from your keyboard. The previous example in which kuanda's file system was set could be set from the command line as follows:


% fncreate_fs user/kuanda/fs altair:/export/home/kuanda

Similarly, the hierarchy illustrated in Figure 25–4 could have been set up by running the sequence of commands:


% fncreate_fs org/sales/fs/tools/db altair:/export/db
% fncreate_fs org/sales/fs/project altair:/export/proj
% fncreate_fs org/sales/fs/project/lib altair:/export/lib
% fncreate_fs org/sales/fs/project/src deneb:/export/src

To make all three of the mounts read-only, you would run this command:


% fncreate_fs org/sales/fs -ro

Advanced Input Formats

The following two sections apply to both input file and command-line input formats.

Multiple Mount Locations

Multiple location fields may be specified for NFS file systems that are exported from multiple, functionally equivalent locations:


% fncreate_fs org/sales/fs altair:/sales cygnus:/sales

The automounter will attempt to choose the best server from among the alternatives provided. If several locations in the list share the same path name, they may be combined using a comma-separated list of host names:


% fncreate_fs org/sales/fs altair,cygnus:/sales

The hosts may be weighted, with the weighting factor appended to the host name as an integer in parentheses: the lower the number, the more desirable the server. The default weighting factor is zero (most desirable). Negative numbers are not allowed.

The following example illustrates one way to indicate that cygnus is the preferred server:


% fncreate_fs org/sales/fs altair(2),cygnus(1):/sales

Variable Substitution

Variable names, prefixed by $, may be used in the options or location fields of fncreate_fs. For example, a mount location may be given as:


altair:/export/$CPU

The automounter will substitute client-specific values for these variables when mounting the corresponding file systems. In the above example, $CPU is replaced by the output of uname -p; for example, sparc.

Backward Compatibility Input Format

For additional compatibility with automount maps, the following input file format is also accepted by fncreate_fs: 


name	 [mount_options] [mount_location ...] \ 
 /offset1	[mount_options1] mount_location1 ... \
 /offset2	[mount_options2] mount_location2 ... \
 ...

Where each offset field is a slash-separated hierarchy. The backslash (\) indicates the continuation of a single long line. This is interpreted as being equivalent to:


name [mount_options] [mount_location ...] \
name/offset1	[ mount_options1] mount_location1 ... \
name/offset2	[mount_options2] mount_location2 ......

The first line is omitted if both mount_options and mount_location are omitted. This format is for compatibility only. It provides no additional functionality, and its use is discouraged.

Introduction to FNS and XFN Policies

XFN defines policies for naming objects in the federated namespace. The goals of these policies are

What FNS Policies Specify

FNS policies contain all the XFN policies plus extensions for the Solaris environment.

Computing environments now offer worldwide scope and a large range of services. Users expect to have access to services at every level of the computing environment. FNS policies provide a common framework for the three levels of services: global, enterprise, and application.

FNS provides to applications a set of policies on how name services are arranged and used:

What FNS Policies Do Not Specify

The FNS policies do not specify:

Policies for the Enterprise Namespace

FNS policies specify the types and arrangement of namespaces within an enterprise and how such namespaces can be used by applications. For example, which namespaces can be associated with which other namespaces. The FNS policies described here include some extensions to XFN policy. These are explicitly defined with notes.

Default FNS Enterprise Namespaces

The FNS enterprise policies deal with the arrangement of enterprise objects within the namespace. Each enterprise objects has its own namespace.

By default, there are seven FNS enterprise objects and namespaces:

The policies that apply to these namespaces are summarized in Table 25–26.

Enterprise Namespace Identifiers

Enterprise namespaces are referred to by their atomic names in the federated enterprise namespace.

XFN uses leading underscore (“_”) characters to indicate an enterprise namespace identifier. For example, _site. FNS also supports the use of these identifiers without the leading underscore (“_”) character. These names without the underscore are extensions to the XFN policies. The site and printer contexts are also extensions to the XFN policies. These atomic names are listed in Table 25–25.

Table 25–25 Enterprise Namespace Identifiers in the Enterprise

Namespace 

XFN Identifiers 

FNS Identifiers 

Resolves to 

Organization 

_orgunit 

orgunit or org 

Context for naming organizational units 

Site 

_site 

site 

Context for naming sites 

Host 

_host 

host 

Context for naming hosts 

User 

_user 

user 

Context for naming users 

File system 

_fs 

fs 

Context for naming files 

Service 

_service 

service 

Context for naming services 

Printer 

 

printer 

Context for naming printers, (subordinate to service namespace) 

Note –

In XFN terminology, the names with the leading underscore are the canonical namespace identifiers. The names without the underscore are namespace identifies that have been customized for the Solaris operating environment. These customized namespace identifiers, with the addition of printer, might not be recognized in non-Solaris environments. The canonical namespace identifiers are always recognized and so are portable to other environments.

Component Separators

The XFN component separator (/) delimits namespace identifiers. For example, composing the namespace identifier orgunit with the organizational unit name west.sales gives the composite name, orgunit/west.sales.

Default FNS Namespaces

There are seven namespaces supplied with FNS:

Organizational Unit Namespace

The organizational unit namespace provides a hierarchical namespace for naming subunits of an enterprise. Each organizational unit name is bound to an organizational unit context that represents the organizational unit. Organization unit names are identified by the prefixes org/, orgunit/, or _orgunit/. (The shorthand alias org/ is only used in the initial context, never in the middle of a compound name. See Initial Context Bindings for Naming Within the Enterprise and Composite Name Examples.)

NIS+ Environment

In an NIS+ environment, organizational units correspond to NIS+ domains and subdomains.

Under NIS+, organization units must map to domains and subdomains. You must have an organizational unit for each NIS+ domain and subdomain. You cannot have “logical” organization units within a domain or subdomain. In other words, you cannot divide an NIS+ domain or subdomain into smaller organization units. Thus, if you have an NIS+ domain doc.com. and two subdomains sales.doc.com. and manf.doc.com., you must have three FNS organizational units corresponding to those three domains.

Organizational units are named using dot-separated right-to-left compound names, where each atomic element names an organizational unit within a larger unit. For example, the name org/sales.doc.com. names an organizational unit sales within a larger unit named doc.com. In this example, sales is an NIS+ subdomain of doc.com.

Organizational unit names can be either fully qualified NIS+ domain names or relatively named NIS+ names. Fully qualified names have a terminal dot; relative names do not. Thus, if a terminal dot is present in the organization name, the name is treated as a fully qualified NIS+ domain name. If there is no terminal dot, the organization name is resolved relative to the top of the organizational hierarchy. For example, orgunit/west.sales.doc.com. is a fully qualified name identifying the west organization unit, and _orgunit/west.sales is a relatively qualified name identifying the same subdomain.

NIS Environment

In an NIS environment there is only one organization unit per enterprise which corresponds to the NIS domain. This orgunit is named orgunit/domainname where domainname is the name of the NIS domain. For example, if the NIS domain name is doc.com, the organizational unit is org/doc.com.

In an NIS environment, you can use an empty string as a shorthand for the organizational unit. Thus, org// is equivalent to org/domainname.

Files-Based Environment

There is only one FNS organization unit and no subunits when your primary enterprise-level name service is files-based. The only permitted organization unit under files-based naming is org//.

Site Namespace

The site namespace provides a geographic namespace for naming objects that are naturally identified with their physical locations. These objects can be, for example, buildings on a campus, machines and printers on a floor, conference rooms in a building and their schedules, and users in contiguous offices. Site names are identified by the prefixes site/or _site/.

In the Solaris operating environment, sites are named using compound names, where each atomic part names a site within a larger site. The syntax of site names is dot-separated right-to-left, with components arranged from the most general to the most specific location description. For example, _site/pine.bldg5 names the Pine conference room in building 5, while site/bldg7.alameda identifies building 7 of the Alameda location of some enterprise.

Host Namespace

The host namespace provides a namespace for naming computers. Host names are identified by the prefixes host/or _host/. For example, host/deneb identifies a machine named deneb.

Hosts are named in hostname contexts. The host context has a flat namespace and contains bindings of host names to host contexts. A host context allows you to name objects relative to a machine, such as files and printers found at that host.

In the Solaris operating environment, host names correspond to Solaris host names. Alias names for a single machine share the same context. For example, if the name mail_server is an alias for the machines deneb and altair, both deneb and altair will share the contexts created for mail_server.

Network resources should only be named relative to hosts as appropriate. In most cases, it is more intuitive to name resources relative to entities such as organizations, users, or sites. Dependence on host names forces the user to remember information that is often obscure and sometimes not very stable. For example, a user's files might move from one host to another because of hardware changes, file space usage, network reconfigurations, and so on. And users often share the same file server, which might lead to confusion if files were named relative to hosts. Yet if the files were named relative to the user, such changes do not affect how the files are named.

There might be a few cases in which the use of host names is appropriate. For example, if a resource is available only on a particular machine and is tied to the existence of that machine, and there is no other logical way to name the resource relative to other entities, then it might make sense to name the resource relative to the host. Or, in the case of a file system, if the files are being shared by many users it might make sense to name them relative to the machine they are stored on.

User Namespace

The user namespace provides a namespace for naming human users in a computing environment. User names are identified by the prefixes user/or _user/.

Users are named in user contexts. The user context has a single-level namespace and contains bindings of user names to user contexts. A user context allows you to name objects relative to a user, such as files, services, or resources associated with the user.

In the Solaris operating environment, user names correspond to Solaris login IDs. For example, _user/inga identifies a user whose login ID is inga.

File Namespace

A file namespace (or file system) provides a namespace for naming files. File names are identified by the prefixes fs/or _fs/. For example the name fs/etc/motd identifies the file motd which is stored in the /etc directory.

The file namespace is described in more detail in .Files-Based naming files and file contexts are discussed in File Contexts Administration.

Service Namespace

The service namespace provides a namespace for services used by or associated with objects within an enterprise. Examples of such services are electronic calendars, faxes, mail, and printing. Service names are identified by the prefixes service/ or _service/.

In the Solaris operating environment, the service namespace is hierarchical. Service names are slash-separated (/) left-to-right compound names. An application that uses the service namespace can make use of this hierarchical property to reserve a subtree for that application. For example, the printer service reserves the subtree printer in the service namespace.

FNS does not specify how service names or reference types are chosen. These are determined by service providers that share the service namespace. For example, the calendar service uses the name _service/calendar in the service context to name the calendar service and what is bound to the name calendar is determined by the calendar service.

Service Name and Reference Registration

Sun Microsystems, Inc., maintains a registry of the names bound in the first level of the service namespace. To register a name, send an email request to fns-register@sun.com, or write to:

FNS Registration Sun Microsystems, Inc., 4150 Network Circle Santa Clara, CA 95054

Please include a brief description of the intended use of the name and a description of the format of the reference that can be bound to that name.

Printer Namespace

The printer namespace provides a namespace for naming printers. The printer namespace is associated with (subordinate to) the service namespace. In other words, printer service and the printer namespace is one of the services in the service namespace. Printer names are identified by the prefixes service/printer or _service/printer. For example, service/printer/laser1 identifies the printer named laser1.

Significance of Trailing Slash

The trailing / names objects in the next naming system. You need it whenever you are going from one naming system to another.

For example, in the name, org/east.sales/service/printer the slash between org and east.sales is a component delimiter as described above and the slash that trails after the last element in the organization name (sales/) separates the service namespace from the organizational unit namespace. Thus, org/west.sales/service/printer names the printer service of the west.sales organization unit.

FNS Reserved Names

FNS reserves for its own use all the atomic names listed in Table 25–25 as namespace identifiers. For example: _orgunit, org, _site, site, and so forth. This limitation applies to contexts in which the namespace identifiers can appear, as defined by the arrangement of namespaces in Structure of the Enterprise Namespace. FNS does not otherwise restrict the use of these atomic names in other contexts.

For example, the atomic name service is used as a namespace identifier relative to a user name, as in user/fatima/service/calendar, to mean the root of user fatima's service namespace. This does not preclude a system from using the name service as a user name, as in user/service, because FNS specifies that the context to which the name user/ is bound is for user names and not for namespace identifiers. In this case, service is unambiguously interpreted as a user name. On the other hand, you should not create a directory named user because /user/mikhail would cause confusion between the user mikhail and the file (or subdirectory) /user/mikhail.

Composite Name Examples

This section shows examples of names that follow FNS policies. (See Table 25–26 for a summary of these policies.)

The specific choices of organization names, site names, user names, host names, file names, and service names (such as calendar and printer) are illustrative only; these names are not specified by FNS policy.

Composing Names Relative to Organizations

The namespaces that can be associated with the organization namespace (_orgunit, orgunit, or org) are: user, host, service, fs, and site.

For example:

Composing Names Relative to Users

The namespaces that can be associated with the user namespace are service and fs.

Composing Names Relative to Hosts

The namespaces that can be associated with the hosts namespace are service and fs.

Composing Names Relative to Sites

The namespaces that can be associated with the sites namespace are service and fs.

Composing Names Relative to Services and Files

No other namespaces can be associated with either the files (fs) or services (service) namespaces. For example, you cannot compose a name such as /services/calendar/orgunit/doc.com. In other words, you cannot compose a compound name relative to either the files or the service namespace. You can, of course, compose a file or service name relative to some other namespace such as /user/esperanza/service/calendar.

Structure of the Enterprise Namespace

FNS policies define the structure of the enterprise namespace. The purpose of this structure is to allow easy and uniform composition of names. This enterprise namespace structure has two main rules:

Table 25–26 isf FNS policies for arranging the enterprise namespace. The following table shows an example of a namespace layout that follows these FNS policies.

Table 25–26 Policies for the Federated Enterprise Namespace

Namespace Identifiers 

Subordinate Namespaces 

Parent Context 

Namespace Organization 

Syntax 

orgunit 

_orgunit 

org 

Site, user, host, file system, service 

Enterprise root 

Hierarchical 

Dot-separated right-to-left 

site 

_site 

Service, file system 

Enterprise root, organizational unit 

Hierarchical 

Dot-separated right-to-left 

user 

_user 

Service, file system 

Enterprise root, organizational unit 

Flat 

Solaris login name 

host 

_host 

Service, file system 

Enterprise root, organizational unit 

Flat 

Solaris host name 

service 

_service 

Application specific 

Enterprise root, organizational unit, site, user, host 

Hierarchical 

/ separated left-to-right 

fs 

 

_fs 

None 

Enterprise root, organizational unit, site, user, host 

Hierarchical 

/ separated, left-to-right 

printer 

None 

Service 

Hierarchical 

/ separated left-to-right 

Figure 25–1 Example of an Enterprise Namespace

Graphic

The namespace of an enterprise is structured around a hierarchy of organizational units. Names of sites, hosts, users, files, and services can be named relative to names of organizational units by composing the organizational unit name with the appropriate namespace identifier and object name.

In Figure 25–2, a user myoko in the west division of the sales organization of an enterprise is named using the name orgunit/west.sales/user/myoko.

Note the use of the namespace identifier user to denote the transition from the orgunit namespace to the user namespace. In a similar fashion (with the use of appropriate namespace identifiers), names of files and services can also be named relative to names of sites, users, or hosts. Names of sites can be named relative to organizational unit names.

The goal of easy and uniform composability of names is met using this structure. For example, once you know the name for an organizational unit within an enterprise (for example, orgunit/west), you can name a user relative to it by composing it with the user namespace identifier and the user's login name to yield a name such as orgunit/west/user/josepha.

To name a file in this user's file system, you can use a name like orgunit/west/user/josepha/fs/notes.

Enterprise Root

The root context of an enterprise, is a context for naming objects found at the root level of the enterprise namespace. Enterprise roots are bound in the global namespace.

There are two ways of naming the enterprise root:

Using Three Dots to Identify the Enterprise Root

You can use .../rootdomain/ to identify an enterprise root where:

Using org// to Identify the Enterprise Root

You can use org// to identify an enterprise root. In essence, org// is an alias or functional equivalent for .../domainname/. When using org//, the double slashes identifies the root enterprise context and namespaces associated with it.

For example, org//site/alameda names the Alameda site associated with the enterprise root.

In contrast, org/ or orgunit/ (with a single slash) points to an organizational context which is not necessarily named relative to the enterprise root. For example, org/sales/site/alameda.

Enterprise Root Subordinate Contexts

The following objects can be named relative to the enterprise root:

These objects are named by composing the namespace identifier of the target object's namespace with the name of the target object.

Enterprise Root and Organizational Subunits

Organizational subunits can be named relative to the enterprise root.

Given an organization root name, you can compose names for its subordinate organizational unit contexts by using one of the namespace identifiers, orgunit or _orgunit.

For example, if .../doc.com is the name of an enterprise, the root of the context for naming organizational units is .../doc.com/orgunit/, and organizational unit names look like .../doc.com/orgunit/sales and .../doc.com/orgunit/west.sales. Or, you could achieve the same result with org//orgunit/sales.

The following objects can be named relative to an organizational unit name:

For example, the name ...doc.com/orgunit/sales/service/calendar, identifies the calendar service of the sales organizational unit. (See Organizational Unit Namespace and Composing Names Relative to Organizations for a more detailed description of naming objects relative to organization units.)

Enterprise Root and Sites

Sites are an extension to the XFN policies.

Sites can be named relative to

These objects are named by composing the site name with the namespace identifier of the target object's namespace and the name of the target object. For example, the name site/Clark.bldg-5/service/calendar names the calendar service of the conference room Clark.bldg-5 and is obtained by composing the site name site/Clark.bldg-5 with the service name service/calendar. (See Composing Names Relative to Sites for a more detailed description of naming objects relative to sites.)

Enterprise Root and Users

Users can be named relative to

These objects are named by composing the user's name with the namespace identifier of the target object's namespace and the name of the target object. For example, the name user/sophia/service/calendar names the calendar for the user sophia. (See User Namespace and Enterprise Root and Users for more information on the user namespace and naming objects relative to users.)

Enterprise Root and Hosts

Hosts can be named relative to

These objects are named by composing the host name with the namespace identifier of the target object's namespace and the name of the target object. For example, the name host/sirius/fs/release names the file directory release being exported by the machine sirius. (See Host Namespace and Composing Names Relative to Hosts for more information on the host namespace and naming objects relative to hosts.)

Enterprise Root and Services

A service can be named relative to

Services named relative to the enterprise root are the same as services named relative to the top organizational unit.

A service context is named by using the namespace identifiers service or _service, relative to the organization, site, user, or host with which it is associated. For example, if orgunit/corp.finance names an organizational unit, then orgunit/corp.finance/service/calendar names the calendar service of the organizational unit corp.finance. (See Service Namespace and Composing Names Relative to Services and Files for more information on the user namespace and naming objects relative to users.)

FNS does not restrict the types of bindings in the service namespace. Applications can create contexts of a type other than service contexts and bind them in the service namespace.

FNS supports the creation of generic contexts in the service context. A generic context is similar to a service context except that a generic context has an application-determined reference type. All other properties of a generic context are the same as a service context.

For example, a company named World Intrinsic Designs Corp (WIDC), reserves the name extcomm in the service namespace to refer to a generic context for adding bindings related to its external communications line of products. The context bound to extcomm is a generic context, with reference type WIDC_comm. The only difference between this context and a service context is that this context has a different reference type.

Service names should be registered with Sun Microsystems, Inc., as directed in Service Name and Reference Registration.

Enterprise Root and Files

A file namespace can be named relative to

Files named relative to the enterprise root are the same as files named relative to the top organizational unit. A file context is named by using the namespace identifiers fs or _fs, relative to the organization, site, user, or host with which it is associated. For example, if orgunit/accountspayable.finance names an organizational unit, then the name user/jsmith/fs/report96.doc names her file report96.doc. The file service of the user defaults to her home directory, as specified in the NIS+ passwd table. (See File Namespace for more information on the user namespace.)

There can be no other type of context subordinate to a file system.

Enterprise Root and Printers

The printer context is an extension of XFN policies.

A printer namespace can be named in the service context. A printer context is named by using the namespace identifier, printer, in the service context relative to

For example, if org/east.sales names an organizational unit, then org/eastsales/service/printer names the printer service of the organizational unit east.sales. Thus, an individual printer named lp1 would be identified as: org/east.sales/service/printer/lp1.

There can be no other type of context subordinate to a printer.

Initial Context Bindings for Naming Within the Enterprise

An initial context is the starting place from which client users, hosts, and applications can (eventually) name any object in the enterprise namespace.

The figure below shows the same naming system as the one shown in Figure 25–2, except that the initial context bindings are shaded and shown in italics. These initial contexts are shown from the point of view of the user, host, or application asking for a name to be resolved.

Figure 25–2 Example of Enterprise Bindings in the Initial Context

Graphic

XFN provides an initial context function, fn_ctx_handle_from_initial(), that allows a client to obtain an initial context object as a starting point for name resolution. The initial context has a flat namespace for namespace identifiers. The bindings of these initial context identifiers are summarized in Table 25–27 and are described in more detail in subsequent sections. Not all of these names need to appear in all initial contexts. For example, when a program is invoked by the superuser, only the host and client-related bindings appears in the initial context, none of the user-related bindings appear.

Table 25–27 Initial Context Bindings for Naming Within the Enterprise

Namespace Identifier 

Binding 

myself, _myself, thisuser

The context of the user who is trying to resolve a name. 

myens, _myens

The enterprise root of the user who is trying to resolve a name. 

myorgunit, _myorgunit

The user's primary organizational unit context. For example, in an NIS+ environment, the primary organizational unit is the user's NIS+ home domain. 

thishost, _thishost

The context of the host that is trying to resolve a name. 

thisens, _thisens

The enterprise root of the host that is trying to resolve a name. 

thisorgunit, _thisorgunit

The host's primary organizational unit context. For example, in an NIS+ environment, the primary organizational unit is the host's NIS+ home domain. 

user, _user

The context in which users in the same organizational unit as the host are named. 

host, _host

The context in which hosts in the same organizational unit as the host are named. 

org, orgunit, _orgunit

The root context of the organizational unit namespace in the host's enterprise. For example, in an NIS+ environment, this corresponds to the NIS+ root domain. 

site, _site

The root context of the site namespace at the top organizational unit if the site namespace has been configured. 

In XFN terminology, names with a leading underscore prefix are called the canonical namespace identifiers. The names without the leading underscore, with the additions of org and thisuser, are Solaris customizations. Solaris customized namespace identifiers are not guaranteed to be recognized in other, non-Solaris operating environment. The canonical namespace identifiers are always recognized and therefore portable to other environments.

Note –

The current implementations of FNS does not support the addition or modification of names and bindings in the initial context.

Initial context bindings fall into three basic categories:

User-related Bindings

FNS assumes that there is a user associated with a process when the XFN initial context function is invoked. This association is based on the effective user ID (euid) of the process. Although the association of user to process can change during the life of the process, the original context handle does not change.

FNS defines the following bindings in the initial context that are related to the user requesting name resolution.

myself

The namespace identifier myself (or either synonym _myself or thisuser) in the initial context resolves to the user context of whomever is making the request. For example, if a process owned by the user jsmith requests name resolution, the name:

myorgunit

FNS assumes that each user is affiliated with an organizational unit of an enterprise. A user can be affiliated with multiple organizational units, but there must be one organizational unit that is primary, perhaps by its position in the organizational namespace or by the user's role in the organization.

myens

FNS assumes that there is an association of a user to an enterprise. This corresponds to the namespace that holds myorgunit.

The namespace identifier myens (and _myens) resolves in the initial context to the enterprise root of the enterprise to which the user making the request belongs. For example, if jsmith is making the request, and jsmith's NIS+ home domain is east.sales, which in turn is in the NIS+ hierarchy with the root domain name of doc.com. The name myens/orgunit/ resolves to the top organizational unit of doc.com.

Note –

Be careful about set-user-ID programs when using user-related composite names, such as myorgunit or myself/service, because these bindings depend on the effective user ID of a process. For programs that set-user-ID to root to access system resources on behalf of the caller, it is usually a good idea to call seteuid(getuid()) before calling fn_ctx_handle_from_initial().

Host-related Bindings

A process is running on a particular host when the XFN initial context function is invoked. FNS defines the following bindings in the initial context that are related to the host the process is running on.

thishost

The namespace identifier thishost (or _thishost) is bound to the host context of the host running the process. For example, if the process is running on the machine cygnus, thishost is bound to the host context of cygnus, and the name thishost/service/calendar refers to the calendar service of the machine cygnus.

thisorgunit

FNS assumes that a host is associated with an organizational unit. A host can be associated with multiple organizational units, but there must be one that is primary. In an NIS+ namespace, this organizational unit corresponds to the host's home domain.

The namespace identifier thisorgunit (or _thisorgunit) resolves to the primary organizational unit of the host running the process. For example, if that host is the machine cygnus, and cygnus's NIS+ home domain is west.sales, then thisorgunit resolves to the organizational unit context for west.sales and the name thisorgunit/service/fax refers to the fax service of the organizational unit west.sales.

thisens

FNS assumes that there is an association of a host to an enterprise. This corresponds to the namespace that holds thisorgunit.

The namespace identifier thisens (or _thisens) resolves to the enterprise root of the host running the process. For example, under NIS+, if the host's home domain is sales.doc.com, then the name thisens/site/ resolves to the root of the site namespace of doc.com.

“Shorthand” Bindings

FNS defines the following “shorthand” bindings in the initial context to enable the use of shorter names to refer to objects in certain commonly referenced namespaces.

user

The namespace identifier user (or _user) is bound in the initial context to the username context in organizational unit of the host running the process. This allows other users in the same organizational unit to be named from this context.

From the initial context, the names user and thisorgunit/user resolve to the same context. For example, if the host running the process is a machine altair and altair is in the east.sales organizational unit, the name user/medici names the user medici in east.sales.

host

The namespace identifier host (or _host) is bound in the initial context to the hostname context organizational unit of the host running the process. This allows other hosts in the same organizational unit to be named from this context.

From the initial context, the names host and thisorgunit/host resolve to the same context. For example, if the host running the process is a machine named sirius and it is in the east.sales organizational unit, the name host/sirius names the machine sirius in the organizational unit east.sales.

org

The namespace identifier org (or orgunit, _orgunit) is bound in the initial context to the root context of the organization of the enterprise to which the host running the process belongs.

From the initial context, the names org and thisens/orgunit resolve to the same context. For example, if the host running the process is the machine aldebaran and aldebaran is in the enterprise doc.com., the name org/east.sales names the organizational unit east.sales in doc.com.

site

The namespace identifier site (or _site) is bound in the initial context to the root of the site naming system of the top organizational unit of the enterprise to which the host running the process belongs.

From the initial context, the names site and thisens/site resolve to the same context. For example, if the host running the process is the machine aldebaran and aldebaran is in the enterprise doc.com., the name site/pine.bldg-5 names a conference room, pine in building 5 of doc.com.

FNS and Enterprise Level Naming

FNS provides a method for federating multiple naming services under a single, simple interface for basic naming operations. FNS is designed to work with three enterprise-level name services, NIS+, NIS and Files. FNS is also designed to work with applications such as printer and calendar service as described in Target Client Applications of FNS Policies.

How FNS Policies Relate to NIS+

FNS stores bindings for enterprise objects in FNS tables which are located in domain-level org_dir NIS+ directories on NIS+ servers. FNS tables are similar to NIS+ tables. These FNS tables store bindings for the following enterprise namespaces:

NIS+ Domains and FNS Organizational Units

FNS names organization, user, and host enterprise objects within NIS+ which is the preferred Solaris enterprise name service. An NIS+ domain is comprised of logical collections of users and machines and information about them, arranged to reflect some form of hierarchical organizational structure within an enterprise.

FNS is implemented on NIS+ by mapping NIS+ domains to FNS organizations. An organizational unit name corresponds to an NIS+ domain name and is identified using either the fully qualified form of its NIS+ domain name, or its NIS+ domain name relative to the NIS+ root. The top of the FNS organizational namespace is mapped to the NIS+ root domain and is accessed using the name org/ from the initial context.

In NIS+, users and hosts have a notion of a home domain. A host or user's home domain is the NIS+ domain that maintains information associated with them. A user or host's home domain can be determined directly using its NIS+ principal name. An NIS+ principal name is composed of the atomic user (login) name or the atomic host name and the name of the NIS+ home domain. For example, the user sekou with home domain doc.com. has an NIS+ principal name sekou.doc.com and the machine name vega has an NIS+ principal name vega.doc.com.

A user's NIS+ home domain corresponds to the user's FNS organizational unit. Similarly, a host's home domain corresponds to its FNS organizational unit.

Trailing Dot in Organization Names

The trailing dot in an organization name indicates that the name is a fully qualified NIS+ domain name. Without the trailing dot, the organization name is an NIS+ domain name to be resolved relative to the NIS+ root domain.

For example, if the NIS+ root domain is doc.com., with a subdomain sales.doc.com., the following pairs of names refer to the same organization:

Table 25–28 Example of Relative and Fully Qualified Organization Names Under NIS+

Relative Name 

Fully Qualified Name 

org/ 

org/doc.com. 

org/sales 

org/sales.doc.com. 

The name org/manf. (with trailing dot) would not be found, because there is no NIS+ domain with just the manf. name.

NIS+ Hosts and FNS Hosts

Hosts in the NIS+ namespace are found in the hosts.org_dir table of the host's home domain. Hosts in an FNS organization correspond to the hosts in the hosts.org_dir table of the corresponding NIS+ domain. FNS provides a context for each host in the hosts table.

NIS+ Users and FNS Users

Users in the NIS+ namespace are listed in the passwd.org_dir table of the user's home domain. Users in an FNS organization correspond to the users in the passwd.org_dir table of the corresponding NIS+ domain. FNS provides a context for each user in the passwd table.

NIS+ Security and FNS

The FNS fncreate command creates FNS tables and directories in the NIS+ hierarchy associated with the domain of the host on which the command is run. In order to run fncreate, you must be an authenticated NIS+ principle with credentials authorizing you to Read, Create, Modify, and Destroy NIS+ objects in that domain. You will be the owner of the FNS tables created by fncreate. One way to obtain this authorization is to be a member of the NIS+ group that has administrator privileges in the domain.

The NIS_GROUP environment variable should be set to name of the NIS+ administration group for the domain prior to running fncreate. You can specify whether or not individual users can make changes to FNS data that relates to them.

How FNS Policies Relate to NIS

FNS stores bindings for enterprise objects in FNS maps which are located in a /var/yp/domainname directory on the NIS master server (and NIS slave servers, if any). FNS maps are similar in structure and function to FNS maps. These NIS maps store bindings for the following enterprise namespaces:

FNS provides contexts which allow other objects to be named relative to these five namespaces.

The FNS fncreate command creates the FNS maps in the /var/yp/domainname directory of an NIS master server. This can be the same machine that is master server for the NIS naming service, or it can be a different machine that functions as an FNS master server. (If there are slave servers, NIS pushes the FNS maps to them as part of its normal operation.) To run fncreate, you must be a privileged user on the server that will host the FNS maps. Individual users cannot make changes to FNS data.

How FNS Policies Relate to Files-Based Naming

FNS stores bindings for enterprise objects in files which are located in a /var/fn directory which is normally NFS mounted on each machine. These FNS files store bindings for the following enterprise namespaces:

FNS provides contexts which allow other objects to be named relative to these five namespaces.

The FNS fncreate command creates the FNS files in the /var/fn directory of the machine on which the command is run. To run fncreate, you must have super-user privileges on that machine. Based on UNIX user IDs, individual users are allowed to modify their own contexts, bindings, and attributes using FNS commands.

Target Client Applications of FNS Policies

One goal of the FNS policies is to maintain coherence across the most commonly used tools, including the file system, the DeskSet tools, such as Calendar Manager, Print Tool, File Manager, and Mail Tool, and services that support these tools, such as RPC, email, and print subsystems.

Note –

Some of these examples are not currently implemented in the Solaris operating environment. They are listed here to illustrate how FNS can be used.

Example Applications: Calendar Service

This is a description of how one application, a calendar service, could be modified to use FNS policies. This example illustrates how FNS composite names might be presented to and accepted from users.

The DeskSet's calendar service is typical of client-server applications. Calendar servers run on some set of machines and maintain the users' calendars. Calendar Manager (cm) runs on the desktop and contacts the appropriate server to obtain the calendars of interest.

The calendar service could benefit from FNS using a simple registry/lookup model as follows:

In the previous example, we used the name “calendar” to denote a calendar binding. The developers of the calendar service should register the name “calendar” with the FNS administrator, much as RPC programs are registered with the RPC administrator. Refer to Service Name and Reference Registration.

Note –

The name “calendar” used here is an example. FNS policy does not specify the names of specific services.

The calendar service could take further advantage of FNS policy by allowing calendars to be associated with sites, organizations, and hosts, while still naming them in a uniform way. For example, by allowing calendars to be associated with a conference room (a site), the service can be used to “multibrowse” the conference room's calendar as well as a set of user calendars to find an available time for a meeting in that room. Similarly, calendars can be associated with organizations for group meetings and hosts for keeping maintenance schedules.

The cm calendar manager could simplify what the user needs to specify by following some simple steps.

  1. cm uses a tool for accepting composite names from the user and constructing the name of the object whose calendar is of interest.

    The object is the name of a user, a site, a host, or an organization. For example, the user might enter the name kuanda and the calendar manager generates the composite name user/kuanda. This tool could be shared among a group of DeskSet applications.

  2. cm uses the XFN interface to compose this name with the suffix /service/calendar to obtain the name of the calendar.

  3. This calendar name is then resolved relative to the process's initial context.

    Continuing with the example, this results in the resolution of the name user/kuanda/service/calendar. Similarly, if the user enters the name of a site, pine.bldg-5, cm generates the name site/pine.bldg-5/service/calendar for resolution.

    Other services such as printing and mail could take advantage of the FNS policies in a similar way.

FNS File System Namespace

Files may be named relative to users, hosts, organizations, and sites in FNS by appending the fs enterprise namespace identifier to the name of the object, and following this with the name of the file. For example, the file draft96 in the sales division's budget directory might be named org/sales/fs/budget/draft96.

The initial context is located under /xfn in the file system's root directory. Thus a user might view the file by typing 


% more /xfn/org/sales/fs/budget/draft96

Existing applications can access this directory just as they would any other directory. Applications do not need to be modified in any way or use the XFN API.

NFS File Servers

NFS is Sun's distributed file system. The files associated with an object will generally reside on one or more remote NFS file servers. In the simplest case, the namespace identifier fs corresponds to the root of an exported NFS file system, as shown in Figure 25–3.

Figure 25–3 NFS File System—Simple Case

Graphic

In contrast, an object's file system may be composed of multiple—and possibly overlapping—remote mounts, woven together into a “virtual” directory structure managed by FNS.

Figure 25–4 illustrates how this capability might be used to piece together an organization's file system from three separate file servers. The project directory, along with its lib subdirectory, resides on one file server, while the src subdirectory resides on another. Users and applications need not be aware of the use of multiple servers; they see a single, seamless namespace.

Figure 25–4 NFS File System—Multiple Servers

Graphic

The Automounter

For efficiency, the automounter is used to mount FNS directories on demand. The default /etc/auto_master configuration file contains the line: 


/xfn -xfn

which tells the automounter that the FNS namespace is “mounted” under /xfn, as specified by XFN.

Since the automounter is used to mount directories named through FNS, the subdirectories of an FNS directory cannot be listed until they have been mounted. For example, suppose the file system of the sales organization is composed of multiple NFS file systems. The following ls command shows only two file systems that have been visited recently and are currently mounted: 


% ls /xfn/org/sales/fs
customers products

To see the entire listing, use the fnlist command:


% fnlist org/sales/fs
Listing org/sales/fs:
products
goals
customers
incentives

The FNS Printer Namespace

The printer context is not part of the XFN policies. It is provided in FNS in order to store printer bindings.

FNS provides the capability to store printer bindings in the FNS namespace. This gives print servers the means to advertise their services and allow users to browse and choose among available printers without client-side administration.

Printer bindings are stored in printer contexts, which are associated with organizations, users, hosts, and sites. Hence, each organization, user, host, and site has its own printer context.

The printer context is created under the service context of the respective composite name. For example, the composite name shown below has the following printer context:


org/doc.com./service/printer

The name of a printer for a host, deneb, with a printer context might look like this:


host/deneb/service/printer/laser

Policies for the Global Namespace

Global name services have worldwide scope. This section describes the policies for naming objects that use global naming systems.

In regard to naming, an enterprise links to the federated global namespace by binding the root of the enterprise in the global namespace. This enables applications and users outside the enterprise to name objects within that enterprise. For example, a user within an enterprise can give out the global name of a file to a colleague in another enterprise to use.

DNS and X.500 contexts provide global-level name service for naming enterprises. FNS provides support for both DNS and X.500 contexts. Without FNS, DNS and X.500 allow outside access to only limited portions of the enterprise namespace. FNS enables outside access to the entire enterprise namespace including services such as calendar manager.

Initial Context Bindings for Global Naming

The atomic name ”...” (three dots) appears in the initial context of every FNS client. The atomic name “...” is bound to a context from which global names can be resolved.

Table 25–29 Initial Context Bindings for Global Naming

Atomic Name 

Binding 

. ..

Global context for resolving DNS or X.500 names 

/ ...

Synonym for three dots 

Global names can be either fully qualified Internet domain names, or X.500 distinguished names.

Federating DNS

Any fully qualified DNS name can be used in the global context. When a DNS name is encountered in the global namespace, it is resolved using the resolver library. The resolver library is the DNS name-resolution mechanism. A DNS name typically resolves to an Internet host address or to DNS domain records. When the global context detects a DNS name, the name is passed to the DNS resolver for resolution. The result is converted into an XFN reference structure and returned to the requester.

The contents of DNS domains can be listed. However, the listing operations might be limited by practical considerations such as connectivity and security on the Internet. For example, listing the global root of the DNS domain is generally not supported by the root DNS servers. Most entities below the root, however, do support the list operation.

DNS hosts and domains are distinguished from each other by the presence or absence of name service (NS) resource records associated with DNS resource names.

DNS can be used to federate other naming systems by functioning as a non-terminal naming system.

For example, an enterprise naming system can be bound to doc.com in DNS such that the FNS name .../doc.com/ refers to the root of that enterprise's FNS namespace.

The enterprise naming system is bound to a DNS domain by adding the appropriate text (TXT) records to the DNS map for that domain. When the FNS name for that domain includes a trailing slash (/), the TXT resource records are used to construct a reference to the enterprise naming system.

For general information about DNS, see the in.named man page or the System Administration Guide: Naming and Directory Services (DNS, NIS, and LDAP).

Federating X.500/LDAP

X.500 is a global directory service. It stores information and provides the capability to look up information by name as well as to browse and search for information.

X.500 information is held in a directory information base (DIB). Entries in the DIB are arranged in a tree structure. Each entry is a named object and comprises a defined set of attributes. Each attribute has a defined attribute type and one or more values.

An entry is unambiguously identified by a distinguished name that is the concatenation of selected attributes from each entry in the tree along a path leading from the root down to the named entry. For example, using the DIB shown in Figure 25–5, c=us/o=doc is a distinguished name of the doc organization in the U.S. Users of the X.500 directory can interrogate and modify the entries and attributes in the DIB.

Figure 25–5 Example of an X.500 Directory Information Base

Graphic

FNS federates X.500 by supplying the necessary support to permit namespaces to appear to be seamlessly attached below the global X.500 namespace.

For example, FNS facilitates linking the enterprise naming system for the doc organization below X.500. Starting from the initial context, an FNS name to identify the sales organizational unit of the doc organization might be

.../c=us/o=doc/orgunit/sales

The name within the enterprise is simply concatenated onto the global X.500 name. (Note that FNS names use the name ”...” in the initial context to indicate that a global name follows.)

Name resolution of FNS names takes place as follows. When an X.500 name is encountered in the global namespace, it is resolved using the X.500 name- resolution mechanism. One of three outcomes is possible:

FNS Problems and Solutions

This section presents problem scenarios with a description of probable causes, diagnoses, and solutions.

See FNS Error Messages for general information about FNS error messages.

Cannot Obtain Initial Context

Symptom:

You get the message Cannot obtain initial context.

Possible Cause:

This is caused by an installation problem.

Diagnosis:

Check that FNS has been installed properly by looking for the file, /usr/lib/fn/fn_ctx_initial.so.

Solution:

Install the fn_ctx_initial.so library.

Nothing in Initial Context

Symptom:

When you run fnlist to see what is in the initial context, you see nothing.

Possible Cause:

This is caused by an NIS+ configuration problem. The organization associated with the user and machine running the fn* commands do not have an associated ctx_dir directory.

Diagnosis:

Use the nisls command to see whether there is a ctx_dir directory.

Solution:

If there is no ctx_dir directory, run fncreate -t org/nis+_domain_name/ to create the ctx_dir directory.

“No Permission” Messages (FNS)

Symptom:

You get no permission messages.

Possible Cause:

“No permission” messages mean that you do not have access to perform the command.

Diagnosis:

Check permission using the appropriate NIS+ commands, described in Advanced FNS and NIS+ Issues. Use the nisdefaults command to determine your NIS+ principal name.

Another area to check is whether you are using the right name. For example, org// names the context of the root organization. Make sure you have permission to manipulate the root organization. Or maybe you meant to specify myorgunit/, instead.

Solution:

If you do have permission, then the appropriate credentials probably have not been acquired.

This could be caused by the following:

Check that the /etc/nsswitch.conf file has a publickey: nisplus entry. This might manifest itself as an authentication error.

fnlist Does not List Suborganizations

Symptom:

You run fnlist with an organization name, expecting to see suborganizations, but instead see nothing.

Possible Cause:

This is caused by an NIS+ configuration problem. Suborganizations must be NIS+ domains. By definition, an NIS+ domain must have a subdirectory named org_dir.

Diagnosis:

Use the nisls command to see what subdirectories exist. Run nisls on each subdirectory to verify which subdirectories have an org_dir. The subdirectories with an org_dir are suborganizations.

Solution:

Not applicable.

Cannot Create Host- or User-related Contexts

Symptom:

When you run fncreate -t for the user, username, host, or hostname contexts, nothing happens.

Possible Cause:

You have not set the NIS_GROUP environment variable. When you create a user or host context it is owned by the host or user, and not by the administrator who set up the namespace. Therefore, fncreate requires that the NIS_GROUP variable be set to enable the administrators who are part of that group to subsequently manipulate the contexts.

Diagnosis:

Check the NIS_GROUP environment variable.

Solution:

The NIS_GROUP environment variable should be set to the group name of the administrators who will administer the contexts.

Cannot Remove a Context You Created

Symptom:

When you run fndestroy on the host or user context the context is not removed.

Possible Cause:

You do not own the host or user context. When you create a user or host context it is owned by the host or user, and not by the administrator who set up the namespace.

Diagnosis:

Check the NIS_GROUP environment variable.

Solution:

The NIS_GROUP environment variable needs to be set to the group name of the administrator who will administer the contexts.

Name in Use with fnunbind

Symptom:

You get “name in use” when trying to remove bindings. It works for certain names but not for others.

Possible Cause:

You cannot unbind the name of a context. This restriction is in place to avoid leaving behind contexts that have no name (“orphaned contexts”).

Diagnosis:

Run the fnlist command on the name to verify that it is a context.

Solution:

If the name is a context, use the fndestroy command to destroy the context.

Name in Use with fnbind/fncreate -s

Symptom:

You use the -s option with fnbind and fncreate, but for certain names you get “name in use.”

Possible Cause:

fnbind -s and fncreate -soverwrite the existing binding if it already exists; but if the old binding is one that must be kept to avoid orphaned contexts, the operation fails with a “name in use” error because the binding could not be removed. This is done to avoid orphaned contexts.

Diagnosis:

Run the fnlist command on the name to verify that it is a context.

Solution:

Run the fndestroy command to remove the context before running fnbind or fncreate on the same name.

fndestroy/fnunbind Does Not Return Operation Failed

Symptom:

When you do an fndestroy or fnunbind on certain names that you know do not exist, you receive no indication that the operation failed.

Possible Cause:

The operation did not fail. The semantics of fndestroy and fnunbind are that if the terminal name is not bound, the operation returns success.

Diagnosis:

Run the fnlookup command on the name. You should receive the message, “name not found.”

Solution:

Not applicable.

Some Common Error Messages


attribute no permission

:. The caller did not have permission to perform the attempted attribute operation.


attribute value required

:. The operation attempted to create an attribute without a value, and the specific naming system does not allow this.


authentication failure

:. The operation could not be completed because the principal making the request cannot be authenticated with the name service involved. If the service is NIS+, check that you are identified as the correct principal (run the command nisdefaults) and that your machine has specified the correct source for publickeys. Check that the /etc/nsswitch.conf file has the entry, publickey: nisplus.


bad reference

:. FNS could not interpret the contents of the reference. This can result if the contents of the reference have been corrupted or when the reference identifies itself as an FNS reference, but FNS doesn't know how to decode it.


Cannot obtain Initial Context

:. Indicates an installation problem. See Cannot Obtain Initial Context.


communication failure

:. FNS could not communicate with the name service to complete the operation.


configuration error

An error resulted because of configuration problems. Examples:

(1) The bindings table is removed out-of-band (outside of FNS).

(2) A host is in the NIS+ hosts directory object but does not have a corresponding FNS host context.


context not empty

:. An attempt has been made to remove a context that still contains bindings.


continue operation using status values

:. The operation should be continued using the remaining name and the resolved reference returned in the status.


error

:. An error that cannot be classified as one of the other errors listed above occurred while processing the request. Check the status of the naming services involved in the operation and see whether any of them are experiencing extraordinary problems.


illegal name

:. The name supplied is not a legal name.


incompatible code sets

:. The operation involved character strings from incompatible code sets, or the supplied code set is not supported by the implementation.


invalid enumeration handle

:. The enumeration handle supplied is invalid. The handle could have been from another enumeration, an update operation might have occurred during the enumeration, or there might have been some other reason.


invalid syntax attributes

:. The syntax attributes supplied are invalid or insufficient to fully specify the syntax.


link error

:. An error occurred while resolving an XFN link with the supplied name.


malformed link

:. A malformed link reference was found during a fn_ctx_lookup_link() operation. The name supplied resolved to a reference that was not a link.


name in use

:. The name supplied is already bound in the context.


name not found

:. The name supplied was not found.


no permission

:. The operation failed because of access control problems. See “No Permission” Messages (FNS). See also No Permission.


no such attribute

:. The object did not have an attribute with the given identifier.


no supported address

:. No shared library could be found under the /usr/lib/fn directory for any of the address types found in the reference bound to the FNS name. Shared libraries for an address type are named according to this convention: fn_ctx_address_type.so. Typically there is a link from fn_ctx_address_type.so to fn_ctx_address_type.so.1.

For example, a reference with address type onc_fn_nisplus would have a shared library in the path name: /usr/lib/fn/fn_ctx_onc_fn_nisplus.so.


not a context

:. The reference does not correspond to a valid context.


partial result returned

:. The operation returned a partial result.


Success

(1) The request was successful. This message is generated by the NIS+ error code constant: NIS_SUCCESS. See the nis_tables man page for additional information.

(2) :. Operation succeeded.


syntax not supported

:. The syntax type is not supported.


too many attribute values

:. The operation attempted to associate more values with an attribute than the naming system supports.


unavailable

:. The name service on which the operation depends is unavailable.


link loop limit reached

:. A nonterminating loop was detected due to XFN links encountered during composite name resolution, or the implementation-defined limit was exceeded on the number of XFN links allowed for a single operation.