TITLE
    Mac OS X Server: niutil Utility
Article ID:
Created:
Modified:
30760
9/23/98
11/1/00

TOPIC

    This article will show you how to use niutil to manipulate a NetInfo database.


DISCUSSION

    Why use niutil?

    Despite its reputation, niutil is fairly simple. Its options allow you to create, examine, and destroy NetInfo directories or properties. Many of the things you can do with niutil you can also do with NetInfoManager. Because it is easy to make mistakes on a command line, it is usually safer to use NetInfoManager when making modifications to NetInfo.

    Sometimes, though, niutil is the only choice-for example, if you are logged in over a modem without access to the graphic interface.

    niutil options

    - option function: list Display the subdirectories of a given NetInfo directory.

    - read: Display the properties and values associated with a given NetInfo directory.

    - create: Create a NetInfo directory.

    - createprop: Create a property.

    - destroy: Destroy a NetInfo directory.

    - destroyprop: Destroy a property.

    - t: Identify the domain with tagged domain notation.

    - p: Propt for the root password of the domain.


    A look at the database

    The two options for examining a NetInfo database are list, for directories, and read, for properties. With each, you must indicate the domain to read and the path of the directory. Because you're only examining the NetInfo database, there's no danger here.

    list

    You use the list option to examine the subdirectories of a given NetInfo directory. The following command looks at the subdirectories of the /machines directory in the parent domain (..):

    niutil -list .. /machines

    The output of this command includes the number of each subdirectory and, by default, the value or values of the name property. In this case, each subdirectory represents a host entry stored in the parent domain.

    35 earth_dialin
    33 earth_remote
    2 earth mailhost
    34 pluto
    37 venus

    If you want to examine the values of a different property, simply include the name of the property in the command:

    niutil -list .. /machines serves

    The output lists the values of the serves property instead of the name property. Notice that directory 35 (earth_dialin) has no value; it does not have a serves property.

    35
    33 earth_remote/local
    2 earth/local ./network
    34 mars/local
    37 venus/local

    read

    The read option displays the properties associated with a given NetInfo directory. The following command shows the properties stored in the host entry for earth in the parent domain:

    niutil -read .. /machines/earth

    The output includes each property key and the associated value(s). Notice that this directory has a host alias (mailhost) stored as the second value of the name property.

    name: earth mailhost
    ip_address: 192.82.163.1
    serves: earth/local ./network ../super

    If you can't access a domain with a relative name (".", "..", or "/"), you can use tagged domain notation with the t option. Remember that tagged domain notation is in the form host/tag, where host is the name or Internet address of the computer serving the domain, and tag is the tag of the NetInfo database. The following command lists the properties stored in the directory /users/root (the root user account) in the domain tagged super served from the host earth:

    niutil -read -t earth/super /users/root

    The output of this command contains all the properties for a user account:

    name: root
    uid: 0
    gid: 1
    realname: Operator
    home: /
    shell: /bin/csh
    _writers_passwd: root
    passwd: Vbg0X7ZIQSEIU

    The most familiar way to specify a NetInfo directory is with the value of the name property, and so far, the examples have all used this method. However, you can also identify a directory by the value of some other property. For example, the following command displays the properties associated with the subdirectory under /users that has a uid property with a value of 0 in the root domain:

    niutil -read / /users/uid=0

    Because the root account has user ID 0, the output of this command is the same as if you had indicated /users/root.

    What if the value you specify is ambiguous-if more than one directory has a property with the indicated value? The following command looks in the current domain for a user account that has the default group ID 1. Group ID 1 is the group wheel, and the users root, daemon, and me have it as their default group. Any guesses as to the result?

    niutil -read . /users/gid=1

    The read option displays only the properties for a single directory. The first directory that matches the specified path is displayed, as determined by the directory number. In this case, root has the lowest directory number, and its directory is the first one found. Remember, the list option displays directory numbers as well as, by default, the value of the name property.

    Finally, if you know the directory number, you do not need to use a path. For example, the output of niutil with the list option used earlier shows us that /machines/earth in the parent domain is directory number 2. The following commands are equivalent:

    niutil -read .. /machines/earth
    niutil -read .. 2

    create

    The following command creates a new directory named admins under the /aliases directory in the parent domain:

    niutil -create .. /aliases/admins
    niutil -read .. /aliases/admins
    name: admins

    As you can see from this output, you now have a new directory with a single property, name, assigned the value admins. A mail alias without any members, however, is not very useful.

    Note: When using create, be careful what you type so you create only directories you intend to create.

    createprop

    The next command creates a new property and assigns it several values:

    niutil -createprop .. /aliases/admins members root
    celia george mary
    niutil -read .. /aliases/admins

    The output from the second command shows that the new property members has been created and assigned the values root, celia, george, and mary.

    Note: Be very careful with createprop because it will overwrite an existing property that has the same key.

    name: admins

    members: root celia george mary

    If you use the createprop option to set the value(s) of an existing property, that property is overwritten. For example, the following command overwrites the name property so this mail alias can be used with either lowercase or uppercase letters:

    niutil -createprop .. /aliases/admins name admins
    ADMINS
    niutil -read .. /aliases/admins
    name: admins ADMINS
    members: root celia george mary

    If you want to modify a domain and you are not logged into the server as root, you need to use the p option. When you use this option, you are prompted for the root password of the domain you're modifying:

    niutil -create -t -p earth/super /aliases/engineers
    Password:


    Destructive Options

    The final pair of options is used to destroy directories or properties: destroy for directories and destroyprop for properties. Be very careful with both of these-you don't get a chance to change your mind.

    destroy

    Sometimes you may need to eliminate an existing directory. For example, let's say you make a mistake while entering a command to create a new mail alias directory:

    niutil -create .. /aliases/admisn

    To destroy the offending directory so you can start over, enter the following:

    niutil -destroy .. /aliases/admisn

    Of course, you can also fix this situation by using createprop to overwrite the name property.

    destroyprop

    Sometimes you need to destroy only a specific property. For example, say you made the following mistake when trying to create the members property in a new mail alias:

    niutil -createprop .. /aliases/admins root celia
    george mary

    As the output below shows, you've created a new property named root instead of a property named members.

    niutil -read .. /aliases/admins
    name: admins
    root: celia george mary

    You correct the situation by destroying the mistake and starting over:

    niutil -destroyprop .. /aliases/admins root

    Final Note:
    There is a program very similar to niutil called "liutil". It works in pretty much the same way, but the "domain" argument is a path to a NetInfo database rather than a domain in the NetInfo hierarchy. For example, rather than:

    niutil -list . /

    You can do the same operation on your local database like so:

    niutil -list /etc/netinfo/local.nidb /

    It must be noted, though, that niutil should be used whenever NetInfo is running on the database you are editing. Specifically, you should not use liutil to edit /etc/netinfo/local.nidb unless you are in single user mode without having started nibindd (1100_DirectoryServices). liutil is particularly useful for editing the NetInfo database when nibindd can't start due to a misconfigured NetInfo database, (See Article 30767: Mac OS X Server: "Cannot Connect to Network" Error) . In particular, when NetInfo is set up to bind to a parent server (e.g. the "Use NetInfo" option in Setup Assistant) and there is no parent, you can use liutil to fix that up in single user mode, usually like so:

    liutil -destroyprop /etc/netinfo/local.nidb /machines/broadcasthost serves

    It is also useful for copying the template local.nidb and editing it for installation on a computer later.

Document Information
Product Area: Mac OS System Software
Category: Mac OS X Server
Sub Category: General Topics
Keywords: kmosXserver

Copyright © 2000 Apple Computer, Inc. All rights reserved.