29.2.2 Actions in the NSS configuration

The second item in the specification gives the user much finer control on the lookup process. Action items are placed between two service names and are written within brackets. The general form is

[ ( !? status = action )+ ]

where

status ⇒ success | notfound | unavail | tryagain
action ⇒ return | continue

The case of the keywords is insignificant. The status values are the results of a call to a lookup function of a specific service. They mean:

‘success’ ¶

No error occurred and the wanted entry is returned. The default action for this is return.

‘notfound’ ¶

The lookup process works ok but the needed value was not found. The default action is continue.

‘unavail’ ¶

The service is permanently unavailable. This can either mean the needed file is not available, or, for DNS, the server is not available or does not allow queries. The default action is continue.

‘tryagain’ ¶

The service is temporarily unavailable. This could mean a file is locked or a server currently cannot accept more connections. The default action is continue.

The action values mean:

‘return’ ¶

If the status matches, stop the lookup process at this service specification. If an entry is available, provide it to the application. If an error occurred, report it to the application. In case of a prior ‘merge’ action, the data is combined with previous lookup results, as explained below.

‘continue’ ¶

If the status matches, proceed with the lookup process at the next entry, discarding the result of the current lookup (and any merged data). An exception is the ‘initgroups’ database and the ‘success’ status, where ‘continue’ acts like merge below.

‘merge’ ¶

Proceed with the lookup process, retaining the current lookup result. This action is useful only with the ‘success’ status. If a subsequent service lookup succeeds and has a matching ‘return’ specification, the results are merged, the lookup process ends, and the merged results are returned to the application. If the following service has a matching ‘merge’ action, the lookup process continues, retaining the combined data from this and any previous lookups.

After a merge action, errors from subsequent lookups are ignored, and the data gathered so far will be returned.

The ‘merge’ only applies to the ‘success’ status. It is currently implemented for the ‘group’ database and its group members field, ‘gr_mem’. If specified for other databases, it causes the lookup to fail (if the status matches).

When processing ‘merge’ for ‘group’ membership, the group GID and name must be identical for both entries. If only one or the other is a match, the behavior is undefined.

If we have a line like

ethers: nisplus [NOTFOUND=return] db files

this is equivalent to

ethers: nisplus [SUCCESS=return NOTFOUND=return UNAVAIL=continue
                 TRYAGAIN=continue]
        db      [SUCCESS=return NOTFOUND=continue UNAVAIL=continue
                 TRYAGAIN=continue]
        files

(except that it would have to be written on one line). The default value for the actions are normally what you want, and only need to be changed in exceptional cases.

If the optional ! is placed before the status this means the following action is used for all statuses but status itself. I.e., ! is negation as in the C language (and others).

Before we explain the exception which makes this action item necessary one more remark: obviously it makes no sense to add another action item after the files service. Since there is no other service following the action always is return.

Now, why is this [NOTFOUND=return] action useful? To understand this we should know that the nisplus service is often complete; i.e., if an entry is not available in the NIS+ tables it is not available anywhere else. This is what is expressed by this action item: it is useless to examine further services since they will not give us a result.

The situation would be different if the NIS+ service is not available because the machine is booting. In this case the return value of the lookup function is not notfound but instead unavail. And as you can see in the complete form above: in this situation the db and files services are used. Neat, isn’t it? The system administrator need not pay special care for the time the system is not completely ready to work (while booting or shutdown or network problems).