Template Version: @(#)onepager.txt 1.29 04/11/15 SMI 1. Introduction 1.1. Project/Component Working Name: Gamin - the File Alteration Monitor 1.2. Name of Document Author/Supplier: Henry Zhang (hua.zhang@sun.com) 1.3. Date of This Document: 06/23/07 1.4. Name of Major Document Customer(s)/Consumer(s): 1.4.1. The PAC or CPT you expect to review your project: Solaris PAC 1.4.2. The ARC(s) you expect to review your project: LSARC 1.4.3. The Director/VP who is "Sponsoring" this project: Robert.Odea@Sun.Com 1.4.4. The name of your business unit: JDS Desktop Engineering, OPG 1.5. Email Aliases: 1.5.1. Responsible Manager: leo.binchy@Sun.COM 1.5.2. Responsible Engineer: hua.zhang@Sun.COM 1.5.3. Marketing Manager: jeff.mcmeekin@sun.com 1.5.4. Interest List: Prakash.Sangappa@Sun.COM, Darren.Kenny@Sun.COM 2. Project Summary 2.1. Project Description: Gamin is a file and directory monitoring system providing a subset of the FAM (File Alteration Monitor) system interfaces. Gamin provides library interfaces that allow programs to detect when a file or directory has been modified. There are actually several backends for Gamin already - inotify, dnotify, kQueue, Hurd Mach Notify and a generic polling mechanism. Because our File Event Notification mechanism is ready for Solaris, we want to use it as the backend for Gamin and ship Gamin on Solairs. 2.2. Risks and Assumptions: By default Gamin should work without needing any configuration, but sometimes using the kernel notification APIs will not work or lead to troubles (for example when trying to unmount device). 3. Business Summary 3.1. Problem Area: Currently when using Nautilus on Solaris, if there is some change to some files/directory, the user will not immediately see the change without polling. And on Sun Ray, having to poll costs a lot of time/CPU/Network traffic. Sun currently modifies the panel menu and menu-editor code to work around the fact that we do not support file change notification. We currently run many find(1) searches to find updated files in Desk Search. The system will work more effectively when notification is added to the system. For example, consider a graphical file manager: When the user creates or removes a file through the file manager, their changes are visible immediately, as they should be. However, if they create or remove a file through some other means (such as typing "touch foo" or "rm foo" in a shell), some file managers will continue to display out-of-date information until the user manually directs the file manager to reread the contents of the directory. That is not the way it should be! The user should be able to trust that their file manager really shows the current file information, not the file information as it was at some unknown time in the past. Gaimin makes tools more usable by enabling them to respond to changes in the system. 3.2. Market/Requester: JDS Desktop group 3.3. Business Justification: GUI tools should not mislead the user where there is some changes on the file system. GUI tools should display the current state of the system, even when changes to the system originate from outside of the GUI tool. Gamin helps make GUI tools more usable by notifying them when the files they are interested in are created, modified, executed, and removed. Your application can use Gamin to get an up-to-date view of the filesystem rather than having to poll the filesystem. Typically, if applications need to monitor the status of a file or directory, they must periodically poll the filesystem. Gamin provides a more efficient and convenient method. We should not keep using polling for these changes, because : * Latency:need longer waiting time; * Duplication of effort: If you have many processes polling the same file, they are all going to have to periodically wake up, check the file, and go back to sleep. * Network traffic: When a process asks to watch a file that is NFS mounted from a remote host, polling will cause lots of network load. 3.4. Competitive Analysis: SGI IRIX uses FAM, and Linux uses FAM/Gamin to show users filesystem changes immediately. Windows has a similar machinism to show users filesystem changes when they happen. 3.5. Opportunity Window/Exposure: It is expected that this project will be integrated into Nevada B71. This project will also be integrated into Solaris 10 Updates if the backend FEN is also integrated into Solaris 10 Updates. At the moment, there is no plan to support FEN on Solaris 10 Update. 3.6. How will you know when you are done?: We will be done when Gamin is ported to Solaris, and runs correctly. Furthermore, the project will be complete when there are no stoppers, P1, or P2 bugs. 4. Technical Description: 4.1. Details: Gamin can report when a file is created, deleted, modified, or executed. See the new /usr/include/port.h for more details on what kind of changes FEN can handle. Basically Gaimin works exactly like the FAM interface. From a programmers point of view, the API is the same, and one can make use of the existing FAM documentation for reference. Gamin uses a client-server model. This is in a large measure justified by the inappropriate dnotify kernel API method to signal modification events to an application but also to share kernel signal when multiple applications monitor the same resource. It also allows fine tuning and filtering of the event flow in the daemon, potentially minimizing resource consumption in applications. Starting with release 0.0.21, Gamin comes with Python bindings. Python programs can "import gamin" to load the module. 4.2. Bug/RFE Number(s): N/A 4.3. In Scope: Port to Solaris Nevada. 4.4. Out of Scope: At the moment, we only port Gamin to Solaris Nevada, and not into Solaris 10 due to the FEN dependency. FEN changes some of the kernel data structures like the 'vnode', which could break third party software. If FEN is backported to Solaris 10 Update, then Gaimin should also be backported. 4.5. Interfaces: Imported Interfaces Interface Stability Comments ---------------- ------------ --------- /usr/lib/libglib-2.0.so.0 Committed /usr/lib/port.h Committed /lib/libsocket.so.1 Committed /lib/libnsl.so.1 Committed /lib/libscf.so.1 Evolving File Events Notification Committed See PSARC/2007/027 Exported Interfaces Stability Comments ------------------ ----------- -------- /usr/lib/gam_server Volatile /usr/lib/libfam.so.0.0.0 Volatile /usr/lib/libgamin-1.so.0.1.8 Volatile /usr/lib/python2.4/vendor-packages/gamin.py Volatile /usr/include/fam.h Volatile SUNWgamin Volatile SUNWgamin-devel Volatile 4.6. Doc Impact: N/A 4.7. Admin/Config Impact: No. 4.8. HA Impact: N/A 4.9. I18N/L10N Impact: No. 4.10. Packaging & Delivery: The new packages are: - SUNWgamin - SUNWgamin-devel 4.11. Security Impact: The ability to receive file notification events could provide a malicious user with information about the system. That said, Gaimin provides no information that the user could not acquire by other means. A user is only able to receive notification about files that they have permission to access. Therefore, systems that make use of file ownership/permissions in a secure way would be protected from exploit. 4.12. Dependencies: Because this project is based on File Events Notification API, it has a dependency on File Events Notification. Gaimin will not be delivered until FEN is delivered. File Events Notification API: see PSARC/2007/027/ 5. Reference Documents: Gamin Project TWiki home page: http://jdswiki.ireland.sun.com/twiki/bin/view/Vermillion/Gamin Gamin home page: http://www.gnome.org/~veillard/gamin/index.html File Events Notification API ARC home page: http://sac.sfbay.sun.com/arc/PSARC/2007/027/ FAM home page: http://oss.sgi.com/projects/fam/ 6. Resources and Schedule: 6.1. Projected Availability: Expect to integrate into Nevada in build 71 in Q3 2007. If FEN is backported into Solaris 10, then Gamin would also integrated into Solaris 10. 6.2. Cost of Effort: Phase one: Solaris Nevada Development 1.0 Engineers - 1 Months Testing 0.5 Engineers - 0.5 Months RE 0.5 Engineers - 0.5 Months Phase two: Solaris 10 Updates Yet to be scoped. 6.3. Cost of Capital Resources: N/A 6.4. Product Approval Committee requested information: 6.4.1. Consolidation or Component Name: JDS / OpenSolaris 6.4.3. Type of CPT Review and Approval expected: Standard 6.4.4. Project Boundary Conditions: none 6.4.5. Is this a necessary project for OEM agreements: No 6.4.6. Notes: N/A 6.4.7. Target RTI Date/Release: Nevada B71 - July 2007, and it will also be planed to put into Solaris 10 6.4.8. Target Code Design Review Date: July 2007 6.4.9. Update approval addition: New project, no Solaris PAC approval yet 6.5. ARC review type: FastTrack 7. Prototype Availability: 7.1. Prototype Availability: July 2007 7.2. Prototype Cost: 1 engineer 1 QA 1 RE