The nistbladm Command

The nistbladm command is the primary NIS+ table administration command. With it, you can create, modify, and delete NIS+ tables and entries. To create a table, its directory must already exist. To add entries to the table, the table and columns must already be defined.

To create a table, you must have Create rights to the directory under which you will create it. To delete a table, you must have Destroy rights to the directory. To modify the contents of a table, whether to add, change, or delete entries, you must have Modify rights to the table or the entries.

Syntax

-- To create or delete a table:

nistbladm -c table-type columnspec... tablename

  nistbladm -d tablename

            columnspec ::=      column=[CSI,rights]

-- To add, modify, or remove entries:

nistbladm -a
nistbladm -A entry
nistbladm -m new-entry old-entry
nistbladm -r
nistbladm -R entry

entry ::= column=value ... tablename | [column=value,...],tablename

The columnspec syntax is explained under the task "Creating a Table" on page 191. The entry syntax is explained under the task "Adding an Entry to a Table" on page 193.

Creating a Table

An NIS+ table must have at least one column and at least one of its columns must be searchable. To create an NIS+ table, use the nistbladm command with the -c option:

nistbladm -c table-type columnspec... tablename

The table-type is simply a string that identifies the table as belonging to a class of tables. It can be any string you choose.

The columnspec argument describes how to specify the characteristics of each column. To use the default column characteristics, simply provide the column names followed by equal signs, and separate the columns with spaces:

column= column=

To assign the column some non-default characteristics, such as access rights that are different from those of the table as a whole, append each column's characteristics to the equal sign:

column=[CSI,rights] column=[CSI,rights]

A column can have any of the following characteristics:

Table 12-1 Column Characteristics

S	Searchable. The nismatch command can search through the column.
I	Case-insensitive. When nismatch searches through the column, it will ignore case.
C	Encrypted.

rights Access Rights. These access rights are over and above those granted to the table as a whole or to specific entries.

If you specify only access rights, you don't need to use a comma. If you include one or more of the S, I, or C flags, add a comma before the access rights. The syntax for access rights is described in Chapter 9, "Administering NIS+ Access Rights."

This example creates a table named "Races" in the Wiz.Com. directory (the "org_dir" directory is reserved for system tables). The table has three searchable columns, Name, Year, and Winner. (Within any table there should be no two entries with the same values for all searchable columns.)

Name	Year	Winner

This is the same example as the above, but access rights are added to each column:

rootmaster% nistbladm -c race-table Name=S,w+m Year=S,w+m \ Winner=S,w+m races.Wiz.Com.

For more information about specifying column access rights when creating a table, see "Setting Column Rights When Creating a Table" on page 152.

Deleting a Table

To delete a table, simply use the -d option and enter the table name:

nistbladm -d tablename

The table must be empty before you can delete it (see "Removing a Single Entry From a Table" on page 195). This example deletes the Races table from the "Wiz.Com." directory:

rootmaster% nistbladm -d races.Wiz.Com.

Adding an Entry to a Table

You can add an entry to a table in two ways:

• With the -a option
• With the -A option

The -a option is recommended for administrators. It adds an entry to a table unless the entry already exists, in which case it returns an error. To use it, you must specify a value for every column in the table:

  nistbladm -a entry

To find the name of a particular column, use the niscat -o command. You can use two different syntaxes to specify an entry:

entry ::=    column=value ... tablename | 
             [column=value,...],tablename

The first consists of one or more column=value pairs, separated by spaces and followed by the table name. The second consists of one or more column=value pairs, separated by commas and enclosed in square brackets, followed by a comma and the table name. The second syntax is referred to as an indexed-name.

These two examples add the same entry to the races table, but they each use a different form:

rootmaster% nistbladm -a Name=derby Year=1992 Winner=yoyoma \ races.Wiz.Com.

rootmaster% nistbladm -a [Name=derby,Year=1992,Winner=yoyoma],\ races.Wiz.Com.

Name	Year	Winner
derby	1992	yoyoma

You can only add one entry with each instance of the nistbladm command. This example adds three more entries to the races table:

rootmaster% nistbladm -a [Name=derby,Year=1991,\ Winner=elvis], races.Wiz.Com. rootmaster% nistbladm -a [Name=derby,Year=1990,\ Winner=LittleFeat], races.Wiz.Com. rootmaster% nistbladm -a [Name=derby,Year=1989, \ Winner=bocefus], races.Wiz.Com.

Name	Year	Winner
derby	1992	yoyoma
derby	1991	elvis
derby	1990	LittleFeat
derby	1989	bocefus

The -A option is designed for applications. Like the -a option, it adds a new entry to a table. However, if the entry already exists, instead of exiting with an error, it changes the operation to "modify," as if the -m option had been used instead. Unlike the -m option, however, with the -A option, you must specify all columns in the entry.

This example demonstrates how -A overwrites an existing entry:

Name	Year	Winner
derby	1992	yoyoma
derby	1991	elvis

rootmaster% nistbladm -A Name=derby Year=1992 \ Winner=chilipepper races.Wiz.Com.

Name	Year	Winner
derby	1992	chilipepper
derby	1991	elvis

The -a option would have returned an error, since the entry specified by Name=derby Year=1992 already exists.

Modifying a Table Entry

To modify a table entry, use the -m option:

nistbladm -m new-entry old-entry

Specify the new-entry with a set of column=value pairs. Use an indexed name to specify the old-entry and the table name. This example modifies an entry in the races table:

Name	Year	Winner
derby	1992	LittleFeat
derby	1991	elvis
derby	1990	LittleFeat
derby	1989	bocefus

Removing a Single Entry From a Table

To remove a single entry from a table, use the -r option:

nistbladm -r indexed-name

You can specify as few column values as you wish. If NIS+ finds duplicates, it does not remove any entry and returns an error message instead. This example removes the Year 1990 entry from the races table:

rootmaster% nistbladm -r \ [Name=derby,Year=1990,Winner=LittleFeat],races.Wiz.Com.

You could have removed the same entry by specifying only the Year column value, as in this example:

rootmaster% nistbladm -r [Year=1990],races.Wiz.Com.

However, you could not have removed the 1990 entry by specifying only the Winner column value (LittleFeat), because two entries have that same value (1992 and 1990):

Name	Year	Winner
derby	1992	LittleFeat
derby	1991	elvis
derby	1990	LittleFeat
derby	1989	bocefus

Removing Multiple Entries From a Table

To remove multiple entries from a table, use the -R option:

nistbladm -R indexedname

As with the -r option, you can specify as few column values as you wish. Unlike the -r option, however, if NIS+ finds duplicates, it removes all of them. You can find the name of a table's column by using the niscat -o command. This example removes all entries in which the Winner is LittleFeat:

rootmaster% nistbladm -R [Winner=littlefeat],races.Wiz.Com.

Name	Year	Winner
derby	1992	LittleFeat
derby	1991	elvis
derby	1990	LittleFeat
derby	1989	bocefus

You can use the -R option to remove all the entries from a table. Simply do not specify any column values, as in this example:

rootmaster% nistbladm -R [],races.Wiz.Com.

The niscat Command

The niscat command displays the contents of an NIS+ table. However, you can also use it to display the object properties of the table. You must have Read rights to the table, entries, or columns that you wish to display.

Syntax

-- To display the contents of a table:

niscat [-hM] tablename

-- To display the object properties of a table:

niscat -o tablename
niscat -o entry

-- Options:

Table 12-2 niscat Syntax Options

-h	Header. Displays a header line above the table entries, listing the name of each column.
-M	Master. Displays only the entries of the table stored on the Master server. This ensures you get the most up-to-date information & should be used only for debugging.
-o	Object. Displays object information about the table, such as column names, properties, and servers.

Displaying the Contents of a Table

To display the contents of a table, use niscat with a tablename:

niscat tablename

This example displays the contents of the table named races.

rootmaster% niscat -h races.Wiz.Com. #Name:Year:Winner Derby:1992:LittleFeat Derby:1991:Elvis Derby:1990:LittleFeat Stakes:1992:DaBulls Stakes:1991:DaBulls Stakes:1990:LittleFeat AlmadenOpen:1992:LittleFeat AlmadenOpen:1991:Buckaroo AlmadenOpen:1990:Trigger

· How to Display Object Properties of a Table or Entry

To list the object properties of a table, use niscat -o and the table's name:

niscat -o tablename.org_dir

To display the object properties of a table entry, use niscat -o and specify the entry with an indexed name:

entry ::=    column=value ... tablename | 
             [column=value,...],tablename

Here are two examples, one for a table and one for a table entry:

rootmaster# niscat -o hosts.org_dir.Wiz.Com. Object Name : hosts Owner : rootmaster.Wiz.Com. Group : admin.Wiz.Com. Domain : org_dir.Wiz.Com. Access Rights : ----rmcdr---r--- Time to Live : 12:0:0 Object Type : TABLE Table Type : hosts_tbl Number of Columns : 4 Character Separator : Search Path : Columns : [0] Name : cname Attributes : (SEARCHABLE, TEXTUAL DATA, CASE INS Access Rights: ---------------- [1] Name : name Attributes : (SEARCHABLE, TEXTUAL DATA, CASE INS Access Rights: ---------------- [2] Name : addr Attributes : (SEARCHABLE, TEXTUAL DATA, CASE INS Access Rights: ---------------- [3] Name : comment Attributes : (TEXTUAL DATA) Access Rights: ----------------

rootmaster# niscat -o [name=rootmaster],hosts.org_dir.Wiz.Com. Object Name : hosts Owner : rootmaster.Wiz.Com. Group : admin.Wiz.Com. Domain : org_dir.Wiz.Com. Access Rights : ----rmcdr---r--- Time to Live : 12:0:0 Object Type : ENTRY Entry data of type hosts_tbl Entry has 4 columns. . . . #

The nismatch and nisgrep Commands

The nismatch and nisgrep commands search through NIS+ tables for entries that match a particular string or regular expression, respectively. They display either the entries themselves or a count of how many entries matched. The differences between the nismatch and nisgrep commands are highlighted in the table below.

Table 12-3 nisgrepnismatch

Characteristics	nismatch	nisgrep
Search Criteria	Accepts text only	Accepts regular expressions
Speed	Faster	Slower
Searches Through	Searchable columns only	All columns, whether searchable or not
Syntax of Search Criteria	column=string ... tablename [column=string,...],t ablename	column=exp ... tablename

The tasks and examples in this section describe the syntax for both commands.

To use either command, you must have Read access to the table you are searching through.

The examples in this section are based on the values in the following table, named races.Wiz.Com. Only the first two columns are searchable.

Table 12-4

Name (S)	Year (S)	Winner
Derby	1992	LittleFeat
Derby	1991	Elvis
Derby	1990	LittleFeat
Stakes	1992	Dabulls
Stakes	1991	Dabulls
Stakes	1990	LittleFeat
AlmadenOpen	1992	LittleFeat
AlmadenOpen	1991	Buckarro
AlmadenOpen	1990	Trigger

About Regular Expressions

Regular expressions are combinations of text and symbols that you can use to search for special configurations of column values. For example, the regular expression ^Hello searches for a value that begins with Hello. When using a regular expression in the command line, be sure to enclose it in quotes, since many of the regular expression symbols have special meaning to the Bourne and C shells. For example:

rootmaster% nisgrep -h greeting="^Hello" phrases.Wiz.Com.

The regular expression symbols are summarized in Table 12-5, below.

Table 12-5

Symbol	Description
^string	Find a value that begins with string.
string$	Find a value that ends with string.
.	Find a value that has a number characters equal to the number of periods

Table 12-5

Symbol	Description
[chars]	Find a value that contains any of the characters in the brackets
*expr	Find a value that has zero or more matches of the expr
+	Find something that appears one or more times
?	Find any value
\'s-char'	Find a special character, such as ? or $.
x | y	Find a character that is either x or y

Syntax

-- To search through the first column:

nismatch string tablename nisgrep reg-exp tablename

-- To search through a particular column:

nismatch column=string tablename nisgrep column=reg-exp tablename

-- To search through multiple columns:

nismatch column=string ... tablename nismatch [column=string,...],tablename nisgrep column=reg-exp ... tablename

-- Options:

Table 12-6 nismatch and nisgrep Syntax Options

-c	Count. Instead of the entries themselves, displays a count of the entries that matched the search criteria.
-h	Header. Displays a header line above the entries, listing the name of each column.
-M	Master. Displays only the entries of the table stored on the Master server. This ensures you get the most up-to-date information & should be used only for debugging.

Searching the First Column

To search for a particular value in the first column of a table, simply enter the first column value and a tablename. In nismatch, the value must be a string. In nisgrep, the value must be a regular expression.

nismatch [-h] string tablename nisgrep [-h] reg-expression tablename

This example searches through the "races" table for all the entries whose first column has a value of "derby":

rootmaster% nismatch -h derby races.Wiz.Com. --OR-- rootmaster% nisgrep -h derby races.Wiz.Com. Name**Year**Winner Derby**1992**LittleFeat Derby**1991**Elvis Derby**1990**LittleFeat

Searching a Particular Column

To search through a particular column other than the first, use the following syntax:

nismatch column=string tablename
nisgrep

column=reg-expression tablename

This example searches through the races table for all the entries whose third column has a value of "LittleFeat":

rootmaster% nismatch -h Winner=LittleFeat races.Wiz.Com. --OR-- rootmaster% nisgrep -h Winner=LittleFeat \ races.org_dir.Wiz.Com. Name**Year**Winner Derby**1990**LittleFeat Derby**1992**LittleFeat Stakes**1990**LittleFeat AlmadenOpen**1992**LittleFeat

Searching Multiple Columns

To search for entries with matches in two or more columns, use the following syntax:

nismatch [-h] column=string ... tablename |
nismatch [-h] [column=string,...],tablename

nisgrep  [-h] column=reg-exp ... tablename

This example searches for entries whose second column has a value of "1992" and whose third column has a value of "LittleFeat":

rootmaster% nismatch -h [Year=1992,Winner=LittleFeat], \ races.Wiz.Com. --OR-- rootmaster% nisgrep -h Year=1992 Winner=LittleFeat \ races.Wiz.Com. Name**Year**Winner Derby**1992**LittleFeat AlmadenOpen**1992**LittleFeat

The nisln Command

The nisln command creates symbolic links between NIS+ objects and table entries. You can use it to link objects to objects or objects to table entries. (You cannot create a link that originates with a table entry.) All NIS+ administration commands accept the -L flag, which directs them to follow links between NIS+ objects.

To create a link to another object or entry, you must have Modify rights to the source object; that is, the one that will point to the other object or entry.

Syntax

-- To create a link:

nisln source target

-- Options:

Table 12-7 nisln Syntax Options

-L	Follow Links. If the source is itself a link, the new link will not be linked to it, but to that link's original source.
-D	Defaults. Specify a different set of defaults for the linked object. Defaults are described in "Overriding Defaults" on page 147.

Creating a Link

To create a link between objects, simply specify both object names, first the source, then the target. To create links between objects and entries use indexed names.

nisln source-object target-object nisln [column=value,...],tablename target-object

The nissetup Command

The nissetup command expands an existing NIS+ directory object into a domain by creating the org_dir and groups_dir directories, and a full set of NIS+ tables. It does not, however, populate the tables with data. For that, you'll need the nisaddent command, described in "The nisaddent

Command" on page 207. Expanding a directory into a domain is part of the process of setting up a domain. For a complete description of the prerequisites and required operations, see Part II.

The nissetup command can expand a directory into a domain that supports NIS clients as well.

To use nissetup, you must have Modify rights to the directory under which you'll store the tables.

Syntax

-- To expand a directory into an NIS+ domain:

/usr/lib/nis/nissetup
/usr/lib/nis/nissetup directory-name

-- To expand a directory into an NIS-compatible NIS+ domain::

/usr/lib/nis/nissetup -Y
/usr/lib/nis/nissetup -Y directory-name

Expanding a Directory into an NIS+ Domain

You can use the nissetup command with or without a directory name. If you don't supply the directory name, it uses the default directory. Each object that is added is listed in the output.

rootmaster# /usr/lib/nis/nissetup Wiz.Com. org_dir.Wiz.Com. created groups_dir.Wiz.Com. created auto_master.org_dir.Wiz.Com. created auto_home.org_dir.Wiz.Com. created bootparams.org_dir.Wiz.Com. created cred.org_dir.Wiz.Com. created ethers.org_dir.Wiz.Com. created group.org_dir.Wiz.Com. created hosts.org_dir.Wiz.Com. created mail_aliases.org_dir.Wiz.Com. created sendmailvars.org_dir.Wiz.Com. created netmasks.org_dir.Wiz.Com. created netgroup.org_dir.Wiz.Com. created networks.org_dir.Wiz.Com. created passwd.org_dir.Wiz.Com. created protocols.org_dir.Wiz.Com. created rpc.org_dir.Wiz.Com. created services.org_dir.Wiz.Com. created timezone.org_dir.Wiz.Com. created

· Expand a Directory Into an NIS-Compatible Domain

To expand a directory into a domain that supports NIS+ and NIS client requests, use the -Y flag. The tables are created with Read rights for the Nobody class so that NIS clients requests can access them.

rootmaster# /usr/lib/nis/nissetup -Y Test.Wiz.Com.

The nisaddent Command

The nisaddent command loads information from text files or NIS maps into NIS+ tables. It can also dump the contents of NIS+ tables back into text files. If you are populating NIS+ tables for the first time, see the instructions in Chapter 5, "Setting Up NIS+ Tables." It describes all the prerequisites and related tasks.

You can use nisaddent to transfer information from one NIS+ table to another (for example, to the same type of table in another domain), but not directly. First you need to dump the contents of the table into a file, then load the file into the other table. Be sure, though, that the information in the file is formatted properly. Appendix A describes the format required for each table.

When you load information into a table, you can use any of three options: replace, append, or merge. The append option simply adds the source entries to the NIS+ table. With the replace option, NIS+ first deletes all existing entries in the table and then adds the entries from the source. In a large table, this adds a large set of entries into the table's .log file (one set for removing the existing entries, another for adding the new ones), taking up space in /var/nis and making propagation to replicas time-consuming.

The merge option produces the same result as the replace option, but uses a different process, one that can greatly reduce the number of operations that must be sent to the replicas. With the merge option, NIS+ handles three types of entries differently:

• Entries that exist only in the source are added to the table.
• Entries that exist in both the source and the table are updated in the table.
• Entries that exist only in the NIS+ table are deleted from the table.

When updating a large table with a file or map whose contents are not vastly different from those of the table, the merge option can spare the server a great many operations. Because it only deletes the entries that are not duplicated in the source (the replace option deletes all entries, indiscriminately), it saves one delete and one add operation for every duplicate entry.

If you are loading information into the tables for the first time, you must have Create rights to the table object. If you are overwriting existing information in the tables, you must have Modify rights to the tables.

Syntax

-- To load information from text files:

/usr/lib/nis/nisaddent -f filename table-type [domain]
/usr/lib/nis/nisaddent -f filename -t tablename table-type [domain]

-- To load information from NIS maps:

/usr/lib/nis/nisaddent -y NISdomain table-type [domain]
/usr/lib/nis/nisaddent -y NISdomain -t tablename table-type [domain]
/usr/lib/nis/nisaddent -Y map table-type [domain]
/usr/lib/nis/nisaddent -Y map -t tablename table-type [domain]

-- To dump information from an NIS+ table to a file:

/usr/lib/nis/nisaddent -d [-t tablename] tabletype > filename

-- Options:

Table 12-8 nisaddent Syntax Options

-a	Append. Contents of the source are appended to contents of the table.
-r	Replace. Contents of the source replace contents of the table.
-m	Merge. Contents of the source are merged with contents of the table.
-d	Dump. Contents of the NIS+ table are dumped to stdout.
-v	Verbose. The command prints verbose status messages.
-P	Follow path. If the command was unable to find a table, follow the search paths specified in the environment variable NIS_PATH.
-A	All data. Apply the operation to all the tables in the search path.
-M	Master server. Use the tables only in the Master server of the domain.
-D	Override defaults. For the new data being loaded into the tables, override existing defaults. For syntax, see "Overriding Defaults" on page 147.

Loading Information From a File

You can transfer the contents of a file into an NIS+ table in several different ways. One way is to use the -f option:

By default, -f replaces the contents of table-type in the local domain with the contents of filename. With the -a option, it appends the contents of filename to table-type. With the -m option, it merges the contents of filename into the contents of table-type.

These two examples load the contents of a text file named /etc/passwd.xfr into the NIS+ Passwd table. The first is into a table in the local domain, the second into a table in another domain:

rootmaster# /usr/lib/nis/nisaddent -f /etc/passwd.xfr passwd rootmaster# /usr/lib/nis/nisaddent -f /etc/shadow.xfr shadow rootmaster# /usr/lib/nis/nisaddent -f /etc/passwd.xfr passwd \ Sales.Wiz.Com. rootmaster# /usr/lib/nis/nisaddent -f /etc/shadow.xfr shadow \ Sales.Wiz.Com.

Another way is to use stdin as the source. However, you cannot use the -m option with stdin. Here is an example:

Here is the output of cat being piped into nisaddent:

If the NIS+ table is one of the automounter tables or a nonstandard table, add the -t option and the complete name of the NIS+ table. To make it easier to find, it is highlighted in this example:

rootmaster# /usr/lib/nis/nisaddent -f /etc/auto_home.xfr \ -t auto_home.org_dir.Wiz.Com. key-value rootmaster# /usr/lib/nis/nisaddent -f /etc/auto_home.xfr \ -t auto_home.org_dir.Sales.Wiz.Com. \ key-value Sales.Wiz.Com.

Loading Data From an NIS Map

You can transfer information from an NIS map in two different ways, either by specifying the NIS domain, or by specifying the actual NIS map. If you specify the domain, NIS+ will figure out which map file in /var/yp/nisdomain to use as the source, based on the table-type::

Table 12-9

NIS+ Table Type	NIS Map Name
Hosts	hosts.byaddr
Passwd	passwd.byname
Group	group.byaddr
Ethers	ethers.byname
Netmasks	netmasks.byaddr
Networks	networks.byname
Protocols	protocols.byname
RPC	rpc.bynumber
Services	services.byname

To transfer by specifying the NIS domain, use the -y (lowercase) option and provide the NIS domain in addition to the NIS+ table type.

By default, nisaddent replaces the contents of the NIS+ table with the contents of the NIS map. Use the -a and -m options to append or merge. Here is an example that loads the NIS+ Passwd table from its corresponding NIS map (passwd.byname) in the OldWiz domain:

rootmaster# /usr/lib/nis/nisaddent -y OldWiz passwd rootmaster# /usr/lib/nis/nisaddent -y OldWiz passwd \ Sales.Wiz.Com.

The second example does the same thing, but for the "Sales.Wiz.Com." domain instead of the local domain, "Wiz.Com."

If the NIS+ table is one of the automounter tables or a nonstandard table, add the -t option and the complete name of the NIS table, just as you would if the source were a file. To make the option easier to find, it is highlighted in these examples:

rootmaster# /usr/lib/nis/nisaddent -y OldWiz \ -t auto_home.org_dir.Wiz.Com. key-value rootmaster# /usr/lib/nis/nisaddent -y OldWiz \ -t auto_home.org_dir.Wiz.Com. key-value Sales.Wiz.Com.

If instead of using the map files for a domain, you prefer to specify a particular NIS map, use the -Y (uppercase) option and specify the map name. To make the option easier to find, it is highlighted in these examples:

rootmaster# /usr/lib/nis/nisaddent -Y hosts.byname hosts rootmaster# /usr/lib/nis/nisaddent -Y hosts.byname hosts \ Sales.Wiz.Com.

If the NIS map is one of the automounter maps or a nonstandard map, combine the -Y option with the -t option:

rootmaster# /usr/lib/nis/nisaddent -Y auto_home \ -t auto_home.org_dir.Wiz.Com. key-value rootmaster# /usr/lib/nis/nisaddent -Y auto_home \ -t auto_home.org_dir.Wiz.Com. key-value Sales.Wiz.Com.

Dumping the Contents of an NIS+ Table to a File

To dump the contents of an NIS+ table into a file, use the -d and -t options. The -d options tells the command to dump, and the -t option specifies the NIS+ table:

/usr/lib/nis/nisaddent -d [-t tablename] tabletype > filename