nsdb-annotate (8) - Linux Manuals

nsdb-annotate: modify an fedfsAnnotation attribute

Command to display nsdb-annotate manual in Linux: $ man 8 nsdb-annotate

NAME

nsdb-annotate - modify an fedfsAnnotation attribute

SYNOPSIS

nsdb-annotate [-?dy] [-a annotation] [-D binddn] [-k keyword] [-l nsdbname] [-r nsdbport] [-v value] distinguished-name

INTRODUCTION

RFC 5716 introduces the Federated File System (FedFS, for short). FedFS is an extensible standardized mechanism by which system administrators construct a coherent namespace across multiple file servers using file system referrals. For further details, see fedfs(7).

The bulk of FedFS junction information in a FedFS domain is stored on one or more LDAP servers. These servers are known as namespace databases, or NSDBs, for short.

FedFS-enabled file servers and clients access the information stored on NSDBs via standard LDAP queries. FedFS-enabled file servers use these queries to resolve FedFS junctions. FedFS administrators use them to manage information about file sets contained in a FedFS domain name space.

DESCRIPTION

The nsdb-annotate(8) command is part of a collection of low-level single-use programs that is intended for testing the NSDB protocol or for use in scripts. It allows FedFS administrators to update the fedfsAnnotation attribute of FedFS records stored on an NSDB.

This command has one positional parameter which specifies the LDAP distinguished name of the FedFS record to be modified. All FedFS object classes may have a fedfsAnnotation attribute, thus a fully qualified distinguished name, rather than, say, an FSN UUID by itself, must be specified.

The fedfsAnnotation attribute itself is multi-valued. Each attribute value is a structured string containing a keyword in double quotes, an equals-sign, and a value in double quotes. The keyword and value may contain any valid UTF-8 character. Escaping allows double quotes and equals-signs to appear in the keyword and values.

The nsdb-annotate(8) command can construct the structured string from a specified keyword and a value via the --keyword and --value command line options, or it can take a single structured string as the full keyword-value via the --annotation command line option. The nsdb-annotate(8) command inserts new values or deletes or replaces existing ones while maintaining the correct structure of each value of the fedfsAnnotation attribute.

Each value of the fedfsAnnotation attribute has no meaning to FedFS and is ignored. Annotation allows local extensions of FedFS without requiring changes to the NSDB's FedFS schema.

OPTIONS

-a, --annotation=spelled-out-annotation: Specifies a properly formed fedfsAnnotation string to process. The form of the string is not checked by the nsdb-annotate (8) command. If the --delete option is specified and this string exists as a value of the target record's fedfsAnnotation attribute, it is removed. Otherwise the value is added.
-d, --debug: Enables debugging messages during operation.
-?, --help: Displays nsdb-annotate(8) version information and a usage message on stderr.
-D, --binddn=bind-distinguished-name: Specifies a distinguished name of an entity used to bind to the LDAP server where the NSDB resides. If the --binddn option is not specified, the value of the FEDFS_NSDB_ADMIN environment variable is consulted. If this variable is not set, the NSDB connection parameter database is searched for this DN. If none of these is specified, or if this entity does not have permission to modify this area of the server's DIT, the nsdb-annotate(8) command fails.
-k, --keyword=annotation-keyword: Specifies the keyword part of a fedfsAnnotation string. Use either the --keyword and --value options or the --annotation option to specify the fedfsAnnotation string to process, not both. If the --delete option is specified and this string exists as a value of the target record's fedfsAnnotation attribute, it is removed. Otherwise the value is added.
-l, --nsdbname=NSDB-hostname: Specifies the hostname of the NSDB where the target record resides. If the --nsdbname option is not specified, the value of the FEDFS_NSDB_HOST environment variable is consulted. If the variable is not set and the --nsdbname option is not specified, the nsdb-annotate(8) command fails.
-r, --nsdbport=NSDB-port: Specifies the IP port of the NSDB where the target record resides. If the --nsdbport option is not specified, the value of the FEDFS_NSDB_PORT environment variable is consulted. The default value if the variable is not set is 389.
-v, --value=annotation-value: Specifies the value part of a fedfsAnnotation string. Use either the --keyword and --value options or the --annotation option to specify the fedfsAnnotation string to process, not both. If the --delete option is specified and this string exists as a value of the target record's fedfsAnnotation attribute, it is removed. Otherwise the value is added.
-y, --delete: Specifies that the specified value string is deleted rather than added.

EXIT CODES

The NSDB returns a value that reflects the success of the requested operation.

FEDFS_OK: The LDAP modify request succeeded.
FEDFS_ERR_ACCESS: The bound entity does not have permission to perform the requested operation.
FEDFS_ERR_INVAL: One of the arguments was not valid.
FEDFS_ERR_SVRFAULT: An unanticipated non-protocol error occurred.
FEDFS_ERR_NSDB_ROUTE: The nsdb-annotate(8) command was unable to find a route to the specified NSDB.
FEDFS_ERR_NSDB_DOWN: The nsdb-annotate(8) command determined that the specified NSDB was down.
FEDFS_ERR_NSDB_CONN: The nsdb-annotate(8) command was unable to establish a connection with the specified NSDB.
FEDFS_ERR_NSDB_AUTH: The nsdb-annotate(8) command was unable to authenticate and establish a secure connection with the specified NSDB.
FEDFS_ERR_NSDB_LDAP: A non-specific LDAP error occurred on the connection between the nsdb-annotate(8) command and specified NSDB.
FEDFS_ERR_NSDB_LDAP_VAL: An LDAP error occurred on the connection between the nsdb-annotate(8) command and specified NSDB. The specific error may be displayed on the command line.
FEDFS_ERR_NSDB_NONCE: The nsdb-annotate(8) command was unable to locate the NCE on the specified NSDB.
FEDFS_ERR_NSDB_NOFSN: The nsdb-annotate(8) command was unable to locate the specified FSN on the specified NSDB.
FEDFS_ERR_NSDB_NOFSL: The nsdb-annotate(8) command was unable to locate any FSLs for the specified FSN on the specified NSDB.
FEDFS_ERR_NSDB_RESPONSE: The nsdb-annotate(8) command received a malformed response from the specified NSDB.
FEDFS_ERR_NSDB_FAULT: An unanticipated error related to the specified NSDB occurred.
FEDFS_ERR_NSDB_PARAMS: The local NSDB connection parameter database does not have any connection parameters on record for the specified NSDB.
FEDFS_ERR_NSDB_LDAP_REFERRAL: The nsdb-annotate(8) command received an LDAP referral that it was unable to follow.
FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL: The nsdb-annotate(8) command received an LDAP referral that it was unable to follow. A specific error may be displayed on the command line.
FEDFS_ERR_NSDB_LDAP_REFERRAL_NOTFOLLOWED: The nsdb-annotate(8) command received an LDAP referral that it chose not to follow, either because the local implementation does not support following LDAP referrals or LDAP referral following is disabled.
FEDFS_ERR_NSDB_PARAMS_LDAP_REFERRAL: The nsdb-annotate(8) command received an LDAP referral that it chose not to follow because the local NSDB connection parameter database had no connection parameters for the NSDB targeted by the LDAP referral.

EXAMPLES

Suppose you are the FedFS administrator of the example.net FedFS domain and that you want to modify the record for FSN UUID dc25a644-06e4-11e0-ae55-000c29dc7f8a on the LDAP server nsdb.example.net. You might use:

$ nsdb-annotate -l nsdb.example.net \
       -k readonly -v yes -D cn=Manager \

       fedfsFsnUuid=dc25a644-06e4-\

       11e0-ae55-000c29dc7f8a,o=fedfs

Enter NSDB password:
Successfully updated annotation "readonly" = "yes" for

  fedfsFsnUuid=dc25a644-06e4-11e0-ae55-000c29dc7f8a,o=fedfs

To see the new annotation, use nsdb-resolve-fsn(8).

SECURITY

Permission to modify the LDAP's DIT is required to update an LDAP entry. The nsdb-annotate(8) command must bind as an entity permitted to modify the DIT to perform this operation. The nsdb-annotate(8) command asks for a bind password on stdin. Standard password blanking techniques are used to obscure the password on the user's terminal.

The target LDAP server must be registered in the local NSDB connection parameter database. The connection security mode listed in the NSDB connection parameter database for the target LDAP server is used during this operation. See nsdbparams(8) for details on how to register an NSDB in the local NSDB connection parameter database.

COLOPHON

This page is part of the fedfs-utils package. A description of the project and information about reporting bugs can be found at http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject.

AUTHOR

Chuck Lever <chuck.lever [at] oracle.com>