Glossary

Provides access authorization for file objects in NSS. The NSS system is designed so that the authorization system is modular. NSS is shipped with a default traditional NetWare® trustee-based authorization system. Other authorization systems might be provided in the future. Every volume has exactly one authorization system associated with it. The loaded authorization systems available on a server and information about which volumes use which authorization systems can be enumerated by reading the directory and file information contained in the NSS_ADMIN volume directory hierarchy of each server. The NULL authentication system always gives permission.

When a client is connected to and authenticated on a server, a connection is associated with that client. Callers of the NLM interfaces are also considered to be clients, even though they are local on the server. Each server has a built-in internal system connection which is preauthenticated with all supervisor rights to the server. An NLM has the option of establishing its own authenticated connection on behalf of remote clients (by using eDirectory™ login interfaces), or it can use the internal default system connection.

The concept of a current directory is used in most client environments. Rather than starting at the root of a volume’s tree, a key (obtained by opening a directory in the volume) can be used to identify a current directory context.

A single file can have multiple streams of data associated with it. The various data streams can be opened and read independently of each other. The primary data stream of a file is directly associated with the file object itself. All data files, by default, have a primary data stream. All additional secondary data streams are identified by a Unicode data stream name which further qualifies the file name. A NULL data stream name identifies the primary data stream. An example of a data stream would be the Macintosh Resource Fork, MAC_RF, which is a separate stream of data (containing icons) that is associated with a Macintosh file. There are two name types supported for data streams. The data stream names follow the naming semantics used by Windows 95/98/NT.

Normally, all reads and writes to a file pass through a file system cache buffer. Some applications, such as database programs, might need to do their own caching. With direct I/O, an application can bypass the cache buffer and do reads and writes directly to the file itself.

Effective rights are the maximum actual rights that a specific client (an authenticated eDirectory object) is allowed to have to a specific file object, not including the file-specific rights as defined by the file attributes. The authorization system associated with a volume controls how effective rights are granted, restricted and inherited, etc., within that volume. When a request is made to perform an operation on a file, the authorization system compares the rights needed to perform the operation against the effective rights to determine if the operation should be allowed.

Extended attributes are very similar to named data streams, except that they use the NetWare extended attribute naming semantics. Extended attributes also have their own object type, because they contain a unique piece of metadata that is not contained in the data stream object. This metadata is a user-defined 32-bit value that is stored with each extended attribute and that is opaque in meaning to NSS.

All file objects have basic file attributes associated with them. Among other things, these file attributes indicate whether the file is read-only, or whether it may be deleted, purged or copied. These file attributes are completely independent from the authorization system and take precedence over the effective rights granted via that authorization system. For example, effective rights might allow write access to a file; but if the file attributes for the file indicate the file is a read-only file, writes are not allowed on the file. Likewise, if the file attributes indicate that the file has the delete inhibit bit set, the file cannot be deleted, regardless of the effective rights a user has.

The file system is made up of many different types of files. A file object is an actual instance of a file type.

The file system is made up of many different types of file objects, the most basic of which is a file. Other types are used to represent system components such as volumes, extended attributes, and storage pools, or the NSS file system itself. The various components of the system can be enumerated by scanning the directories that contain these system component file objects and reading the information stored with those file objects.

Hard links let NSS users create multiple names for the same file object. These names can be in different directories as long as all the directories reside on the same volume. Hard links to directories, data streams, and extended attributes are not allowed. NSS keeps a count of how many links a file has and does not delete a file until all names for the file have been deleted (the link count goes to zero).

A junction is a special type of file that, instead of having data, contains a pathname to the root of another volume. The name parser (either on the client or in the File System API) finds the new volume and continues parsing the name on the new volume, which lets several volumes appear as one volume to the user.

To do anything with the file system, you must have a key. Keys are used to read and write files, open files, get information about files, scan directories, rename files, identify current directories, etc.

A key is a 64-bit random number that hashes to a door, which points to a file handle structure that can represent an open file or a directory with a search map for enumerating the directory, a context for beginning a pathname lookup, or all of the above. When a file is forcibly closed by the system, the door can still exist but is now broken and cannot be used for further operations, which makes local and remote operations look the same.

Namespaces control the syntax of naming, such as which characters are legal in file names and in path separators, how big the name can be, and whether case is significant and/or preserved. The NSS file system is designed so that all namespaces are loadable and replaceable. NSS is shipped with namespace modules for DOS and LONG (OS2, NT/WIN95), Macintosh, UNIX, data stream and extended attribute support.

Every volume must have one or more namespaces associated with it. If a volume has more than one namespace associated with it, valid file names are maintained on that volume for all of its namespaces. If a file name is legal in more than one namespace, it is stored only once and shared by the namespaces. The loaded namespaces available on a server and information about which volumes use which namespaces can be enumerated by reading the file object information contained in the NSS_ADMIN volume directory hierarchy of each server.

The data stream and extended attribute namespaces are not used for standard filenames on volumes. They are used only for naming data streams or extended attributes.

Every directory file can store multiple types of named objects, which are identified by a name type. A name type is simply used to logically group similar types of named objects together in a directory. For example, a standard directory container can contain both named files and named data streams. Both types of names are stored in the same directory, but they are logically grouped together so that each type of name is distinguishable from the other. How name types are dealt with in the physical storage is left up to each individual storage system.

All normal file and directory names are stored with the zNTYPE_FILE name type. All data stream names are stored with either the zNTYPE_DATA_STREAM or with the zNTYPE_EXTENDED_ATTRIBUTE name type. Deleted files in the salvage system are stored with the zNTYPE_DELETED_FILE name type and other features can use additional name types.

When a file is opened or created, an internal data structure called an Open File Structure is allocated that represents that state of that open file. The user gets back a key to the open file structure that must be used for all subsequent accesses to the file (reads, writes, wild-reads, and getting and modifying file metadata).

Alhough not exposed by the File System functions, partial path resolution is where the server returns to the client when it encounters a junction or symbolic link while parsing the path. The client can then continue parsing the path on the appropriate server, which lets the client directly talk to the server that manages the file object named by the path without going through an intermediary server.

A pathname is made up of the name of a file object, preceded by optional directory container names and directory separators. All pathnames are relative to some starting base location, such as a directory container file object or the root of a volume. A fully qualified pathname is a pathname that includes an eDirectory tree name or it is a pathname that starts with a volume name.

Requested rights apply only to the files about to be opened. They are not the effective rights a client has on a file, but they are the rights that a client is requesting to have for a particular open instance of the file. For example, a client may choose to open the same file twice—the first time with read access and the second time with write access. The client would be given two keys but would be able to only read with the first key and able to only write with the second one. The rights granted to a key are stored with the open file structure.

When a request is made to open a file, the authorization system compares the client’s requested rights parameter with the client’s effective rights to the file and the additional file permission attributes (for example: read, write, deny-read, and deny-write). If the effective rights do not allow the requested rights to be granted, the open is denied.

Unlike most file systems, NetWare provides a well-defined way of recovering "deleted" files. Rather than immediately freeing the disk blocks for a deleted file, NSS marks the name as deleted. Only when the space of the deleted file is needed is the file actually purged from the system. By using zMODE_DELETED to augment the source namespace on zRename, you can recover deleted files. By using zNTYPE_DELETED_FILE for the name type in zOpen, the deleted files can be viewed.

Unlike previous versions of NetWare, the NSS volumes do not represent physical storage. An NSS storage pool is simply a collection of disk segments that provide physical storage to one or more NSS volumes. Volumes are logical entities that participate in naming and locating files. Storage pools provide storage for the volumes that reside on them.

The storage system provides basic raw file storage to NSS. It is a flat storage system, where all files are identified by a single identifier called a ZID. The storage system is also used to control how directory contents are organized and stored/retrieved. The NSS file system is designed so that the storage system is replaceable and so that several of these loadable storage systems (LSSes) can be active on the server at once. NSS is shipped with a default journal-based storage system, also known as the Z Loadable Storage System (ZLSS). Other storage systems (such as CD-ROM or DOS/FAT) are also provided. Every storage pool has exactly one loadable storage system associated with it. The loaded storage systems available on a server and information about which storage pools use which storage systems can be enumerated by reading the file object information contained in the NSS_ADMIN volume directory tree for each server.

A symbolic link is a special type of file whose data is a pointer to another file. The pointer is specified in the form of a path string identifying the new file. This new file does not need to be on the same volume or even on the same server. When a symbolic link is encountered while parsing a path, the link is followed and the path parsing continues with the newly specified path.

The purpose of tasks is to maintain separate environments for each of the applications, while sharing a single authenticated connection. When a client workstation connects to a server, it typically establishes a single authenticated connection. However, the client might be running multiple applications, each of which needs to maintain separate open files, current directory context information, etc. Each client application has a taskID associated with it; and when an application terminates, all keys associated with the task can be reclaimed without affecting those in use by other tasks on the same connection. An NLM has the option of using tasks in any way it finds necessary to meet its own needs. If the NLM is providing services to other clients, it can use real taskID values. The file system API defines two special values for the task ID.

zSAME_TASK specifies to use the same task as the key.

zROOT_TASK corresponds to the task 0 in traditional NetWare and is created when the connection initializes with NSS.

A transaction allows a set of operations be treated as a single atomic operation where either all are completed or none are completed. Most functions can be, but are not required to be, bound to a transaction. The xid (transaction ID) parameter identifies whether or not the function is associated with a transaction. If xid contains the value zNILXID, the function is not a part of a transaction; otherwise, xid contains the ID of an in-progress transaction to be associated with the function. Functions like zCreate take a transaction ID because they can change metadata about a file, including creating or destroying a file, which permits backing out changes to the file system as part of a user transaction. Even though an interface might include a xid parameter, it does not mean that transactions are currently supported for that function. Instead, it is provided for future features so interfaces do not need to change or be added.

Transactions can be nested by making them part of another transaction. The original transaction is called the parent and the new transaction is called the child. The child can then create its own child transactions. A transaction cannot commit until all of its children are committed. Locks held by a child are passed back to the parent when the child commits.

Locks held by a transaction cannot be released until the transaction commits. If it is a child transaction, the locks are not released until all of its parents have committed. When the transaction is committed, all the locks are released.

All operating systems have a mechanism for identifying users on the system. In NetWare, the user’s NDS Object ID is used (a 128-bit value); in other operating systems, different IDs are used. The userID uniquely identifies a user to the system.

UTF-8 is a variable-length byte stream encoding of Unicode that is used by Java* and XML. Any Unicode character can be represented in UTF-8. It has numerous advantages over regular Unicode for serial communication, the best of which is that C ASCII strings have the same representation.

An NSS volume is different from the traditional NetWare volume of the past. NSS volumes do not represent physical storage; they represent only a logical collection of files. A logical NSS volume is stored in a physical NSS storage pool. Volumes are made up of a rooted collection of file objects arranged in a directory hierarchy. They can be migrated from storage pool to storage pool and server to server as access needs and space availability change. They can also be replicated in multiple locations for more efficient distributed access.

Volumes participate in the naming and location of files as follows. If a pathname is an NDS fully qualified pathname (starting with \\\), the name parsing begins at the root of the NDS tree and works its way down the NDS containers until it encounters the name of an NDS volume object or an NDS junction object. If a pathname begins with a single slash (\), the path does not specify a volume. However, it does indicate that the remainder of the path is relative to the root of the volume identified using a different mechanism. For the LONG and DOS namespaces, if a pathname begins with a name followed by a colon (:), the name preceding the colon must identify a volume object that is local on the server that is parsing the name. Through other NSS algorithms, an appropriate instance of the volume is located and the rest of the unparsed pathname is used to identify the file object within the volume.

Every server has a default NSS_ADMIN volume that stores system configuration information in its directory hierarchy. System objects such as volumes, storage pools, namespaces, storage systems and authorization systems can be enumerated by reading the directory container file objects in this volume.

Only the DOS and LONG namespaces support wildcards. When using these namespaces, some functions allow wildcard characters to allow multiple files to be acted upon by calling a single function. The legal wildcard characters for DOS and LONG namespaces are asterisk (*) and a question mark (?).

NSS employs a flat storage system, where all files are identified by a single identifier called a ZID. A ZID uniquely identifies a file within a given volume. In order to uniquely identify the path used to get to a file, a parent ZID and name identifier are also required because hard links make it possible for a file to have more than one parent, which creates a need to identify which parent was used to get to the file.

Returns an initial key for a particular connection. To use the system connection, an NLM passes the zSYS_CONNECTION value to zRootKey for the connectionID parameter; otherwise the NLM must pass in a valid connectionID which was returned by the login interfaces.