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.