•Network Setup Scripting AppleScript SDK January 22, 1999 What Is It? Network Setup Scripting is a tool that lets you examine and change all of the networking settings on a Mac OS computer. It is included as part of Mac OS 8.5. It lives in the Scripting Additions folder, but is not an AppleScript extension. It is in fact a faceless background-only application (FBA), which means that it has its own objects, its own verbs, and that you must target it with a ³tell² block. Using Network Setup Scripting, you can do anything you can do by hand using the networking control panels‹change your TCP/IP address, look up your AppleTalk zone, connect using a PPP server, and so on. You can also do several things that you can't do with the control panels‹Network Setup Scripting gives you access to a few previously hidden AppleTalk and TCP/IP settings, and you can group network settings together in sets to make switching configurations easier. Network Setup Scripting uses the new Network Setup API to do all of its work. If you need more detailed control over networking settings, or prefer to code in C or Pascal rather than AppleScript, refer to the Network Setup SDK. What Are These Objects? There are three basic entities in Network Setup Scripting: configurations, transport options, and configuration sets. Configurations: Contain settings specific to a network configuration, for example, a TCP/IP address. There are specific configuration types for each networking module: currently, AppleTalk, infrared, modem, Remote Access (which includes both ARA and PPP), and TCP/IP v4. Transport options: Contain settings that are global to an entire transport, for example, the idle time allowed before the AppleTalk stack is unloaded. Currently, only AppleTalk and TCP/IP v4 have transport options. Between configurations and transport options, you can change any settings you can change using the networking control panels, and even a few that you can't. Configuration sets: Contain any number of configurations, and at most one of each type of transport options (i.e., one AppleTalk options, one TCP/IP v4 options, and so on.) Currently, the same at-most-one restriction applies to configurations as well, though this may change in the future‹see below. A configuration or transport options object can belong to any number of sets, including no sets at all. There is always at least one set‹the active set. Adding or removing objects from the active set implicitly activates or deactivates those objects. Why the distinction between configurations and transport options? In a single-homing world, there is no real difference between a configuration and a transport options object, since you can only have at most one of each type active at once. With multi-homing, however, there is a difference, and one of the design goals for Network Setup Scripting was to make Mac OS ³multi-homing ready.² Under multi-homing, you might have three different TCP/IP configurations active, each describing a different IP address, but you would have only one TCP/IP options object, which would hold settings shared between all of them. Rules of the Road For the most part, Network Setup Scripting describes a simple object-model world: there are elements with properties that you get and set in the usual manner. However, there are some special commands that are necessary to keep everyone playing well with everyone else. These are: open database begin transaction end transaction close database open database and close database: Network Setup Scripting uses a new transaction-based database to store all of your network settings. However, the old network control panel preferences files are still around for backwards compatibility. Synchronizing these two pools is a fairly expensive operation‹on the order of a few seconds‹so open database and close database are are needed to provide explicit synchronization commands. open database updates the new database based on the legacy preferences files, and close database does the reverse. As a rule, call open database before doing any work, and call close database when you¹re done. A side effect of this scheme is that a Network Setup script is oblivious to any changes to the legacy files that occur between open database and close database. In fact, changes made via Network Setup Scripting will overwrite changes made via the networking control panels during the same time. The upshot of this is that you should keep the database open for as little time as possible. In particular, don't call open database, then sit in an idle loop making occasional changes, and finally call close database a few hours later. begin transaction and end transaction: The transaction-based nature of Network Setup Scripting provides protection against partial updates. For example, say a script is changing the TCP/IP setup, and it's managed to change the IP address, but not the router, when Something Goes Wrong. (Another program crashes, someone trips over the power cord, whatever.) Without transactions, the user would be left with an unusable TCP/IP setup. With transactions, Network Setup can cleanly roll back to a known state. Before making any changes using Network Setup Scripting, you must call begin transaction. Network Setup Scripting enforces this‹if you forget, you'll get an error when you try to change anything. When you're done, call end transaction to commit all your changes to the database. Having a transaction open prevents anyone else from writing to the database, so in the interests of politeness, try to keep your transactions short. Network Setup Scripting allows any number of clients to read the database at the same time, but only one client may write to it. If someone else has a transaction open when you attempt you begin one, you will get an error. Sample Scripts NSS skeleton: A starting point for writing Network Setup scripts. Demonstrates basic use of open database, close database, begin transaction, and end transaction. Switch AppleTalk on/off: Shows your current AppleTalk state and offers to toggle it for you. Make sets: Scans through all of your network configurations and makes sets of configurations with the same name. Switch active set: Presents you with a list of all your configuration sets and offers to make one of them active. Make configuration sample: An example showing how to create several configurations and put them into sets. This script is not directly useful, since all the networking information is made up, but it demonstrates the basic techniques involved in creating objects. ________________________________ © 1998 Apple Computer. Inc. All rights reserved. Apple, the Apple logo, LaserWriter, MacTCP, Power Macintosh, Mac, and Macintosh are trademarks of Apple Computer, Inc., registered in the U.S. and other countries. PowerPC is a trademark of International Business Machines Corporation, used under license therefrom. All other product names are trademarks or registered trademarks of their respective holders. Mention of non-Apple products is for information purposes and constitutes neither an endorsement nor a recommendation. Apple assumes no responsibility with regard to the selection, performance, or use of these products. Updated January 22, 1999 v 1.0