2 <! $FreeBSD: src/release/picobsd/doc/src/UCI.html,v 1.4 1999/08/28 01:33:24 peter Exp $ >
3 <! $DragonFly: src/release/picobsd/doc/src/Attic/UCI.html,v 1.2 2003/06/17 04:27:20 dillon Exp $ >
5 <h1><center> Unified Configuration Interface Project
8 <p>The idea behind this project is to completely replace currently
9 used configuration approach, which is based on several shell scripts, and to
10 provide ability to change system behaviour basing on set of well-defined
11 parameters' hierarchy. One of the goals is also to provide an object
12 oriented model of the OS management and structure, instead of currently
13 used (inconsistent) procedural model of system/service startup/shutdown.</p>
15 <p>This project involves such issues as:
18 providing consistent view of the system and its functional subsystems as
19 a set of interrelated objects equipped with certain properties.
22 providing global approach to user interface, either command-line or with GUI
26 managing system resources and subsystems. This includes managing
27 static and dynamic interdependencies between subsystems, ability to
28 upgrade/downgrade specific subsystems on-the-fly.
33 <p><i><b>This is work in progress</b> - I'm aware that many pieces
34 are either completely missing or misplaced. Please send any comments and
35 changes you seem appropriate either directly to me, or better to
36 freebsd-small@freebsd.org. I'll gladly welcome anyone who can help with
37 design and/or implementation.</i></p>
42 <h1><center> Unified Configuration Interface
47 <p>Let's first introduce the following terms:
50 <b>management base</b> - the actual structure holding configuration and
51 information data according to defined structure. This structure will most
52 probably have a form of tree (possibly with cross-branch links or some other
53 mechanism representing mutual dependencies) - the way it's stored is
54 something which needs to be discussed.
57 <b>user interface</b> - a method (and agent) for presenting data stored in
58 management base in such a way that it can be viewed and modified by
62 <b>system monitor</b> - an entity performing actual configuration and monitoring
63 tasks, from one side dealing with management base, and from the other
64 dealing with the system resources and subsystems, and from yet another dealing
65 either directly with the user (thus acting as a user interface),
66 or passing requests to other entity which acts as user interface.
69 <b>subsystem</b> - a package containing programs, configuration data, as well
70 as installing/deinstalling/start/stop stubs, which form together one logical
71 entity performing specific services on behalf of the system. Each subsystem
72 is viewed as an object with specific properties, dependencies, which is able
73 to generate events, service general requests common to all such subsystems,
74 and provide specific services to other subsystems.
79 <p>One possible approach to storing the management data is to use already
80 existing framework known as MIB, as defined in applicable RFCs.</p>
82 <p>This approach has several advantages: it represents well thought-out work
83 of many experienced individuals and teams, it has already proven to be
84 useful, it's widely used and accepted, it's easily extensible, it's able to
85 represent quite complicated objects, etc.</p>
87 <p>It has some drawbacks, as well: e.g. there is no standard mechanism for
88 representing events and indirectly related objects, it tends to create
89 deep and narrow trees which require to descent several levels to change some
90 commonly used parameters, it doesn't say anything about the mutual
91 dependencies between objects and parameters (except parent-child-sibling),
92 and about required sequence to properly set their parameters, etc.</p>
94 <p>These issues are not directly addressed in standards, and real
95 implementations (known to me) have to implement these additional mechanisms
96 "behind the scenes", so that their workings are not obvious nor easily
97 accessible (let alone changeable).</p>
99 <p>So, if we decide to use it, we need to address these issues somehow.
100 The next point presents one possible approach to this dilemma.</p>
103 <p>The term "object" used in the following discussion represents a functional
104 subsystem, such as system service, usually performed by some specific
105 process (or, a set of global system parameters, in which case the system
106 monitor agent is the service itself). </p>
108 <p>Each object represented in management base can be characterized by
109 following properties:
112 its internal state, possibly consisting of several parameters and currently
113 performed functions, but represented to the rest of the system as a symbolic
114 state, one of set of states common to all objects.
117 a temporary space for new sets of parameters, which are being supplied by
118 other subsystems, prior to their actual application,
121 FSM definition, describing state transitions in reaction to received events,
124 list of events it can generate and accept,
127 list of dependencies on other objects' states and services,
130 list of requests it can handle,
133 list of parameters it can accept and/or provide, with their valid ranges.
138 <p>A few words on system startup: the system startup routines should ensure
139 that dependencies can be unwound into linear, ordered list. If it's not
140 possible, they should detect possible deadlocks at runtime, and act as an
141 arbiter between conflicting parties (or signal an error). In case of
142 unsatisfied dependency on some missing subsystem, the system monitor will
143 act appropriately as described below (in paragraph on request handling).</p>
145 <p>The <b>set of symbolic states</b> may consist of the following states,
146 depicting object's current internal state (as described by its FSM):
148 <center><table border>
149 <tr><th>Name</th><th>Meaning</th></tr>
151 <td>INIT</td><td>the subsystem is initializing itself, possibly loading
152 necessary data and binaries from permanent storage.</td>
155 <td>CHECK</td><td>performing consistency check on newly supplied parameter values</td>
158 <td>READY</td><td>ready to start performing its primary function, but not started</td>
161 <td>START</td><td>start-up tasks (related to its primary function, as opposed
162 to INIT which is related to its own initialization)</td>
165 <td>STOP</td><td>stop (shutdown) tasks (when the object intends to stop
166 performing its function). This can involve unloading data and binaries from
170 <td>RUN</td><td>primary (work) phase</td>
173 <td>IDLE</td><td>waiting for some external event to happen</td>
176 <td>BUSY</td><td>the subsystem is busy (either with performing some
177 high-priority task, or just simply hung), and cannot be interrupted without
178 complete restart,</td>
181 <td>ERROR</td><td>this object is either improperly configured, or
185 <td>(other...)</td><td>(other...)</td>
190 <p>The <b>set of possible actions</b> may include the following actions:</p>
192 <center><table border>
193 <tr><th>Name</th><th>Meaning</th></tr>
195 <td>LIST_EV_REQ</td><td>get list of events the subsystem can generate</td>
198 <td>LIST_ACT_REQ</td><td>get list of actions the subsystem can respond to</td>
201 <td>GET_DEF_REQ</td><td>get definition of given parameter (the arguments, and
205 <td>SET_REQ</td><td>set given parameter to given value (this value will
206 be used only after COMMIT_REQ)</td>
209 <td>GET_REQ</td><td>get currently used value of given parameter</td>
212 <td>COMMIT_REQ</td><td>commit changes supplied in last transaction to currently
213 used set of parameters</td>
216 <td>ROLLBACK_REQ</td><td>revert last commit</td>
219 <td>INIT_REQ</td><td>perform initialization tasks</td>
222 <td>START_REQ</td><td>start performing primary function</td>
225 <td>STOP_REQ</td><td>stop performing primary function</td>
228 <td>RESTART_REQ</td><td>restart operation, possibly forcefully</td>
231 <td>NOTIFY_REQ</td><td>notify me of any changes in your state</td>
234 <td>CHECK_REQ</td><td>perform self-consistency check</td>
237 <td>UPGRADE_REQ</td><td>upgrade the subsystem - this possibly involves
238 downloading necessary pieces via network to permanent storage area. The
239 upgrade process should be transactional, and should save the older version
240 of the subsystem in case the DOWNGRADE_REQ should be issued.</td>
243 <td>DOWNGRADE_REQ</td><td>downgrade the subsystem - restore the previous
244 version of the subsystem from the copy on permanent storage.</td>
247 <td>UNINSTALL_REQ</td><td>uninstall the subsystem completely - possibly
248 freeing the space on permanent storage.</td>
251 <td>(other...)</td><td>(other...)</td>
254 <p><i>(Each request includes source service identifier and credentials of
257 <p>The <b>set of events</b> which can be generated by subsystems may include
260 <center><table border>
261 <tr><th>Name</th><th>Meaning</th></tr>
263 <td>EV_ACK</td><td>positive acknowledge of the last operation</td>
266 <td>EV_NACK</td><td>negative acknowledge of the last operation</td>
269 <td>EV_CHANGE</td><td>change notification (includes the name of changed
270 parameter, and/or FSM state change)</td>
273 <td>EV_DEP</td><td>signal the dependency on another subsystem - ask for
274 existence of the service. Probably there should be two types of the dependency:
275 a soft one (where the subsystem can still function even if the dependency is
276 unresolved) and a hard one (when the existence and proper functioning of the
277 other subsystem is mandatory for its function).</td>
280 <td>(other...)</td><td>(other...)</td>
284 <p>One of event attributes can be a flag which says that this particular event
285 is a directed, or broadcast message. In case of directed message, it should
286 be forwarded only to interested parties. Broadcast message is sent to all
289 <p>System monitor agent will process these events and route them to
290 appropriate subsystems which are registered with it. Generally, if some
291 subsystem is dependent on some other, it will want to also receive all events
292 generated by the other subsystem.</p>
294 <p>In case the subsystem
295 is missing, and the system monitor received events signalling that some other
296 subsystem is depending on it, the system monitor should arrange either for
297 installing necessary pieces from some media (be it permanent storage, or the
298 network), or to send an EV_NACK to the requesting subsystem. It's the
299 responsibility of the requesting subsystem to deal with such case
300 appropriately to the type of dependency (i.e. either "hard" or "soft").
302 <p>Ideally, the system monitor agent will be equipped with routines to
303 serialize the management data into human-readable form, so that it's easily
304 stored, backed up, and repaired in case of inconsistencies.</p>
307 <p>Actual user interface is still quite another story: I've seen UIs which
308 merely followed the standard MIBs, and menus were composed of actual OID
309 numbers plus DESCRIPTION field. In my experience, they are (barely)
310 acceptable, though due to the usual width and depth of MIB trees you had to
311 traverse several levels down and up in order to change some (protocol-wise)
312 related parameters.</p>
314 <p>More acceptable UI would collect interrelated items under common menu
315 entries, irrespectibly of their actual position in the MIB tree.</p>
317 <p>A worthwhile goal to pursue is to create such an UI which could guide
318 you through the most common configuration tasks, while at the same time
319 allowing for unrestricted and quick use by power users. This can be done
320 either as a set of configuration "wizards" or extensive hinting, command
324 <p>The management database should be easily exportable via standard
325 protocols, such as SNMP or LDAP.</p>
327 <p>Most known to me (if not all) implementations of agents for these
328 protocols are (contrary to their name) quite heavy-weight - so their use
329 should be either optional, or replaced with some other light-weight
330 protocol and a proxy agent running on other machine. One example of
331 such proxy agent is existing UCD-SNMP implementation which in
332 significant part follows the sysctl(3) tree, merely exporting it as
333 a part of the MIB trees.</p>
335 <p>It's worthwhile to consider also use of other protocols such as
336 DHCP (and BOOTP), Service Location Protocol (SLP - RFC2165) for easy
337 integration with LAN resources, easy initial configuration, and peer
341 <p>All operations performed by system monitor agent should be transactional,
342 i.e. it should be possible to commit a set of changes as one logical entity,
343 and be sure that either it's applied in whole, or not at all. This includes
344 also ability to abort processing in the middle.</p>
346 <p>This probably means that each object (subsystem) should be able to store
347 not only its current configuration data, but also the newly supplied config
348 data that are to be applied after the transaction ends successfuly.</p>
350 <p>Operations should be verified against allowed values, as well as against
351 allowed credentials, and basing on this either committed or aborted.</p>
354 <p>A few notes on possible implementation of system monitor:</p>
357 let's assume that all configuration information is read on startup
358 by some specialized daemon (this can be part of init(8) as well),
359 which then performs role of communication agent through which passes
360 all configuration information, be it request for change, request
361 for info, request for start / shutdown, or notification about the change.
364 configuration information itself is stored either in binary database, or as
365 a filesystem hierachy mimicking configuration items hierarchy.
368 each user-level program performing some task (such as routing daemon, inetd
369 etc) is either equipped with the ability to communicate with config agent, or
370 is relinked with special stub which fakes to the program necessary config
371 files and events (such as signals to reread configuration).
372 <p>This probably means also that some libc routines would have to be replaced,
373 because they assume reading configuration from certain disk files.</p>
375 <p>Since each such subsystem needs to implement some common actions such as
376 installing, deinstalling, start/stop etc, we could use already present
377 system of packages (with some minor modifications) to easily achieve
378 part of the goals (i.e. install/deinstall/upgrade/downgrade/stop/start).</p>
381 each subsystem performing some task requests its initial config data
382 from system monitor, at the same time registering with it to receive
383 configuration events, such as request to re-read data, to provide currently
384 used config data, return status, react for signals, restarts, etc...
387 system monitor acts as a meeting point for all producers and consumers
388 of events and config data. It needs to maintain a table of registered
389 subsystems, set of events they provide, set of events they want to receive,
390 etc.. Basing on this table, it routes appropriate information to
394 user interface is then just one of clients of system monitor, albeit possessing
398 one of important tasks of system monitor, in case given
399 object (subsystem) registers with it to be notified about certain events, is
400 to ensure that such type of event can be possibly generated. This is to
401 prevent subsystems from waiting for events coming from other non-existent
402 subsystems. See the discussion above on satisfying dependencies.
405 <i><p>NOTE: this is one possible approach - a centralized one. It's worth to
406 consider other approach, distributed, in which case each object (subsystem)
407 sends and listens to the data at a meeting point specific to each other
408 object. This eliminates (or drastically minimizes) the role of system
409 monitor which is a single point of failure in centralized case.</p></i>
415 <p>Here is my initial proposal for the User Interface hierarchy:</p>
419 System configuration.
422 Boot device and file <br>
423 <small>Name of the boot device (possibly networked) and boot
427 (Enumeration of available devices)
430 (Enumeration of available files)
438 <small>Configuration file management - loading and saving, either
439 local or remote (if applicable). </small>
445 Source / Destination <br>
446 (Enumeration of available storage places, possibly
452 Edit directly (geek mode)
460 Module management <br>
461 <small>Optional hardware drivers and protocol modules
465 (Enumeration of available loadable modules)
468 Load / unload / status
475 Package management<br>
476 <small>Management of basic and optional system services.</small>
479 (Enumeration of locally available packages)
482 Start / Stop / Status / Configure
489 Default source of service packages<br>
490 <small>Where to automatically get the missing packages from.
494 (Enumeration of available media) <br>
495 (local and remote disks, ftp, http)
505 Memory consumption <br>
506 <small>This is entry point to a subtree, which allows to set
507 up various resource limits for subsystems, services and
511 Space consumption<br>
512 <small>(Things like minimal free space on permanent storage..)
517 <small>This includes not only currently running tasks, but all
518 which can possibly be started.</small>
531 Virtual consoles (if applicable)
534 System Date / Time Zone
553 Network configuration.
562 (Enumeration of physical interfaces) <br>
563 (Enumeration of virtual interfaces, if applicable) <br>
564 (Options for creating virtual interfaces, if applicable)
567 Interface options (speed, media, encapsulation,
580 Adress / netmask / alias
598 IP, UDP, TCP, ARP, IPX, ATM ... <br>
599 (Enumeration of available protocols)
602 (Enumeration of protocol specific options, such as
603 buffer sizes, algorithms, ARP tables etc)
606 List / Add / Delete / Modify / Set (where
638 (Enumeration of available routing protocols)
687 Local DNS server config
720 Add / Delete / Reserve / List
723 (IP address expressions)
739 Access Control Lists <br>
740 <small>(This is either full-blown ACL system in case
741 of SNMPv2, or a community string for SNMPv1.)</small>
755 Add / Modify / Delete / List
763 Priority / Delete / List
775 Network Address Translation
799 Add / Delete / Modify / List
802 Name / Password / ACL
812 Access Control Lists.
815 Add / Delete / Modify / List
818 Name / Template / Definition
828 Add / Delete / Modify / List
834 Command restrictions list
837 Location restrictions list
840 Resources restrictions list
843 Time restrictions list
846 Authentication methods
890 (Enumeration of available FS-s)
893 FS / Mounting point / Options
898 Swap Partition / Swap File
920 (Enumeration of available status items)
931 (Enumeration of subsystems hierarchy, those of which can
932 provide debugging data)
945 Ping / traceroute / rtquery
953 <p>Please send your comments to <A HREF="mailto:abial@freebsd.org">
954 Andrzej Bialecki</a></p>