Subject: PSARC FastTrack [11/15/2006]: Enhancements to zpool history


Template Version: @(#)sac_nextcase 1.2 04/14/09 SMI
Copyright 2006 Sun Microsystems, Inc.
1. Introduction
    1.1. Project/Component Working Name:
	 Enhancements to zpool history
    1.2. Name of Document Author/Supplier:
	 Author:  Mark Shellenbaum
    1.3  Date of This Document:
	07 November, 2006
4. Technical Description

This case adds two flags to the 'zpool history' command: '-l' and '-i'.
The stability of these additions is committed, and the release binding is
patch/micro.

Summary:

	This proposal is to add some additional functionality to
	the zpool history mechanism as described in 2006/288.
	The additions are to support logging the user id, hostname
	zone and transaction group that the ZFS administration command
	was executed in.

	Additionally, some ZFS commands require some internal events
	in order to achieve the desired ZFS command.  This proposal will
	also start logging many ZFS internal events.

Problem:
	
	It is desirable to know what user, zone and hostname various ZFS
	administrative commands were performed on.  This is particularly
	important for proper support of the ZFS delegated adminstration
	model as described in PSARC/2006/465.  Also, several zfs commands
	such as recursive snapshot, zfs receive and others may need to
	create or destroy datasets in order to perform the user requested
	administrative task and will be logged as an "internal event".
	
Solution:
	
	The solution will be to add user id, zone and hostname to the 
        persistent log records.  By default those fields won't be displayed
	when "zpool history" is invoked.  Two new options -l and -i will
	be added to "zpool history".  The first option -l will display
	log records in a long format which will include the "user, hostname
	and zone".  The -i option is used for displaying the internal events
	in additional to the standard events.  

	zpool history [-il] [<pool>]

	The default format without either -l or -i is:

	# zpool history
	History for 'sandbox':
	2006-11-03.08:12:35 zpool create sandbox c2d0
	2006-11-03.08:37:35 zfs create sandbox/test1
	2006-11-03.10:19:00 zfs create sandbox/marks
	...

	long format log record display format: 

	# zpool history -l
	2006-11-03.08:12:35 zpool create sandbox c2d0 \
	      [user root on rousay:global]
	2006-11-03.08:37:35 zfs create sandbox/test1 \
	      [user root on rousay:global]
	2006-11-03.10:19:00 zfs create sandbox/marks \
	      [user root on rousay:global]
	...

	Internal event format:

	<timestamp> [internal <event> txg:<number>] <event data> <dataset>
	
        For example a zfs receive would log file following

	# zfs receive sandbox/marks </var/tmp/zfs.data
	# zpool history -i
	...
	2006-11-03.10:51:13 [internal create txg:1890] \
	        sandbox/marks/fs 
	2006-11-03.10:51:13 [internal snapshot txg:1892] \
	        sandbox/marks/fs/fs2@snap1
	2006-11-03.10:51:13 [internal receive txg:1892] \
	        sandbox/marks/fs/fs2@snap1@snap1
	2006-11-03.10:51:13 zfs receive -d sandbox/marks

Man Page diffs
***************
*** 44,49 ****
--- 44,51 ----
  
       zpool import [-d dir] [-f]       [-a]
  
+      zpool history [-il] [pool] ...
+ 
  DESCRIPTION
       The zpool command configures ZFS storage  pools.  A  storage
       pool  is  a  collection  of  devices  that       provides physical
***************
*** 213,218 ****
--- 215,223 ----
       is       "/", rather than the normal default "/pool".
  
    Subcommands
+      All subcommands that modify state are logged persistenly to
+      the pool in their original form.
+ 
       The zpool command provides       subcommands to create and destroy
       storage  pools,  add  capacity to storage pools, and provide
       information about the storage pools. The  following  subcom-
***************
*** 708,713 ****
--- 713,727 ----
                  potentially active.
  
  
+ 
+ 
+      zpool history [-il] [pool] ...
+ 
+             Displays the command history of the specified pools (or all
+             pools if no pool is specified).
+ 
+	      -i 
+
+		 Displays ZFS internally logged events in addition to 
+                user initiated events.		 
+
+	      -l Displays log records in long format, which in addition
+                to standard format includes, user name, hostname and zone
+		 operation was performed under.
+

6. Resources and Schedule
    6.4. Steering Committee requested information
   	6.4.1. Consolidation C-team Name:
		ON
    6.5. ARC review type: FastTrack