$Id: xchklogs.txt,v 1.1 1997/01/11 22:21:16 grimaldo Rel $
------------------------------------------------------------------------

			X C H K L O G S
			  Version 1.1


INTRODUCTION

Xchklogs is a graphical user interface to the ChkLogs package. Since not many
people have access to Motif libraries (including myself at home) I decided
to implemented in Tcl/Tk (although I would favour Perl/Tk once that is
more spread).

The idea behind this GUI is to present a nice, friendlier interface to
ChkLogs that could be even more helpful to new users. 

The graphical user interface will hide you from dealing with chklogs and
chklogsadm directly although in some cases you may wish to use the
command line.

This is now distributed as a separate package (but still free) from the
ChkLogs package, some parts might be included in the ChkLogs package.

Finally, any comments are welcome and if you have fixed any of the
current restrictions you are welcome to send me the patch.

For more information about known restrictions and changes see the
release notes rn-X.Y where X.Y is the version number. 



REQUIREMENTS

    - Tcl version 7.5
    - Tk version 4.0
    - Wish built with the above two packages
    - An installed & configured version of ChkLogs (1.9 or higher)
    - X-Windows


INSTALLATION

After you have unpacked the package with

	tar xvf xchklogs-X.Y-B.tar.gz

where X.Y is the version number and B the build level (BUILD in the
makefile) you can proceed with configuration.

    - Find out where your tcl/tk shell (wish) is located: which wish
      and modify the magic line (#!/usr/bin/wish) with your own. You
      can use the command `which wish` to find out.

    - Make sure you have enough permissions to run ChkLogs as the
      GUI heavily depends on it. The GUI is *not* a replacement for
      the chklogs package!.

    - Edit the makefile and adapt the following to your own system:
	BINDIR	  - Directory to place xchklogs, chklogsadm, chklogs
		    and any other binaries needed by ChkLogs + GUI
	DEGT_LIB  - Library directory where some GUI library files
		    are expected.
	U_GROUP   - group ID/name for the package files, as used by
		    the Unix install(1L) utility.
	DOCDIR	  - Directory to install documents. /usr/local/doc/
    
Now you have to manually edit the resource file of the GUI (xchklogsrc),
The file has very descriptive comments for each of the configuration
variables. You *must* edit it to reflect your own operating environment:

    InstallDir
	Where you have put the executables of ChkLogs (the core/main package)
	This is the BINDIR of the Chklogs makefile and not the one
	in this (GUI) makefile. Default: /usr/local/sbin

    ConfFile
	Where you put the ChkLogs config file, usually /etc/chklogs.conf
	Must match $ConfFile in chklogs.pl. Default: /etc/chklogs.conf

    LibDir
	Library directory of the Chklogs GUI, must match DEGT_LIB from
	the makefile. Default: /usr/local/lib/chklogs

    EditorCommand
	Your favourite editor under X-Windows.

    Confirm
	Certain important/destructive operations such as initialization
	and creation of a new configuration file can be guarded by 
	setting this to 'yes'. If 'yes' (without quotes) then you will
	first be presented with a confirmation dialog. If 'no' the
	program simply assumes you know what you are doing.
	Default: yes

    navStartDir
	The directory navigator's starting directory. Usually set to
	the directory where most of your logs are.
	Default: /var/log

Now you are ready to install the GUI, type the following command:

	make install

This will place all the files in their appropriate places as specified,
then you can try it out. If you aren't sure what it is going to do
use (for the paranoid, but we live in dangerous times):

	make -n install

Notice that the resource file will also be copied to your home directory
as $(HOME)/.xchklogsrc.


USING XCHKLOGS.TK

Assuming the executable is in a directory on your PATH you can start it
up with:

		xchklogs.tk &

Or make an entry in your root window menu (that's what I did) which 
depends on which window manager you use. An example is found in the
appendix.

The GUI is divided in four main areas: A menu bar at the top, a
log file selection box on the left side, a log specification and
global repository settings on the right side and a button bar at
the bottom.

All operations are made on the fly on the configuration file and
not on an edit temporary version!

For the purpose of clarity each of the menu entries etc is marked
with a status:

	NOT IMPLEMENTED	- obviously not done yet :-(
	BROKEN		- known bug, unsolved at time of release
	LIMITED		- limited functionality.
	OK		- it works.
	

Also mentioned is if there is a button at the bottom of the GUI
window that performs the same function. Accelerators/bindings
are also mentioned. Same goes for the administrative command.


The Menu bar
-----------

File | New				STATUS: OK
	Creates a fresh configuration file, it takes care of creating
	the appropriate header for Chklogs and specifying the global
	settings of the Alternate Repositories feature. Make sure you
	set the Global Repository checkbutton and entry field to
	those of your choice. See chklogs(5), chklogs(8).

	This is a destructive action, the old file is renamed with
	the .old extension and the new, empty one (only header) 
	replaces the original ConfFile.

File | Quit				STATUS: OK
	To quit the GUI. The setting of the Confirm variable applies.
	
	Button equivalency: [Quit] 


Group | New				STATUS:	NOT IMPLEMENTED
	Creates a new group on the configuration. The user can
	specify a new group and its Pre/Post attributes. Then
	the administrative program is executed.

	Admin equivalent: chklogsadm  newgroup -g GROUP -b PRE -a POST

Group | Modify				STATUS:	OK
	Presents you with the GroupSelect window, select a group
	from the listbox (can't modify common) by double clicking. Then
	change the Pre/Post attributes. Make sure you don't select on
	the entry fields because then you lose your 'group selection'.
	It uses the X selection mechanism. You can OK or Cancel the
	choice.

	Bindings:
		<Double-Button-1>  select group from listbox
	Admin equivalent: chklogsadm  newgroup -m -g GROUP -b PRE -a POST

Group | Delete				STATUS:	OK
	Shows the GroupSelect window, the Pre/Post entry fields are
	disabled. Select a group by double clicking and then press OK.
	Again, you cannot remove the common group.

	Bindings:
		<Double-Button-1>  select group from listbox
	Button equivalency: [Add] 
	Admin equivalent: chklogsadm  rmgroup -g GROUP


Log | Add				STATUS:	BROKEN
	Adds a new log to the configuration file. The Navigate window
	pops up showing the directory listing as specified by the
	navStartDir option (resource file). Selecting a directory
	reloads the window with a new directory listing. When a log
	is selected (double click) the Add to Group window (same as
	GroupSelect window) pops up. You can add to any group or to
	the 'common' (general) group. Press OK or Cancel. The
	Navigation window is destroyed with Control-C

	Bindings:
		<Double-Button-1>  select log, select group
		<Control-C>  destroys navigator window if on focus.
	Admin equivalent: chklogsadm  gadd -g GROUP -l LOG ....

	NOTES:
	  1) Broken because it invokes chklogsadm, some work seems to
	     be done but the config file does not reflect the changes!.
	     When the same options/parameters are tried from the command
	     line (no GUI) it works. In other cases an error window
	     pops up with the chklogsadm usage info. Somehow there is
	     something weird happening when exec'ing the program.
	     Command line works (I repeat).
	  2) The browser as implemented has the limitation that it is
	     not possible to select a directory as a log spec. ChkLogs
	     allows you to do that to put a whole directory under its
	     control.

Log | Delete				STATUS:	OK
	Delete a log from the configuration. First you *must* select
	a log from the listbox on the left side of the GUI and then
	select Delete. The type is the one in the Action frame on
	the right side.

	Button equivalency: [Delete] 
	Admin equivalent: chklogsadm  del -l LOG -t TYPE
	

Log | Browse				STATUS:	OK
	Allows you to view the contents of the log file using your
	favourite editor as specified by EditorCommand resource
	variable. You must first select a log from the listbox
	by double clicking. Very convenient.


Config | Init				STATUS:	OK
	Initializes the ChkLogs database. (See chklogsadm(8)). A
	confirmation dialog will be presented if Confirm is set.
	You only need to do this when you install chklogs (not the
	GUI!) for the first time or when you create a new
	configuration file (File | New + add logs). This will
	destroy your history file (ages) (database) and refresh it
	with today's date.

	Admin equivalent: chklogsadm  init

Config | Repository			STATUS:	OK
	Initializes the repositories (See chklogsadm(8), chklogs(8)).
	Needed when you change global repositories or add a new 
	group. This is not a destructive operation so no harm in
	doing it when not needed.

	Admin equivalent: chklogsadm  initrepos


Report | Show				STATUS:	OK
	Gives a report about the current status of the registered
	logs. No action is taken, this is good if you want to know
	what chklogs is up to without actually doing it. This is
	shown in a "ChkLogs Status" window.

	Admin equivalent: chklogs  -w

Report | Mail				STATUS:	OK
	It is similar to the Show option, except the report is
	mailed to the admin user as configured in ChkLogs. Like
	Show, no action is actually taken.

	Admin equivalent: chklogs  -w -m


Report | When				STATUS:	OK
	Presents the When window indicating the information in
	the ChkLogs database about the selected (double click
	before) log. This information includes logname, last
	action taken (archive, execute, truncate), when it was
	taken and how many days (age) have passed since then.
	The type depends on the action radiobutton for the particular
	log.

	Admin equivalent: chklogsadm -l LOG -t TYPE


Options | Show				STATUS: OK
	Shows you the current settings of the GUI per the values
	in the GUI resource file xchklogsrc. You can change them
	from here. These include InstallDir, ConfFile, EditorCommand,
	navStartDir and Confirm. Changes are always reflected in
	the operation of the program.

	NOTES:
	  1) Changes are valid for the current session but are
	     not saved across sessions.


Help | About				STATUS: OK
	Shows a dialog with my logo, author and version number.


Button Bar
---------

  Add
	Same as Log | Add

  Delete
	Same as Log | Delete

  Quit
	Same as File | Quit

  Sync
	Synchronize database. When not needed the button is disabled,
	when something is done that might require sync the button
	becomes enabled. A Sync is not a destructive operation so
	no harm in syncing to much. This doesn't work across sessions.
	The reason why it is not done automatically is for efficiency, 
	you may want to perform many operations and then do one sync 
	at the end.

The Log Specification Frame
---------------------------

The lower subframe presents you with the global settings of the
Alternate Repository feature by reading the header of the ChkLogs
configuration file.

The upper frame gives you the current settings for the log that
has been selected on the listbox (left frame) this includes:

	- Threshold amount
	- Threshold modifier (bytes, days, months)
	- Action (archive, truncate, execute)
	- Quantity of logs to be archived in the repository when
	  the archive attribute is set.
 	- Executable/parameters when the execute attribute is selected.

		******************************
		*        F  R  E  E          *
		******************************

AUTHOR
	D. Emilio Grimaldo T.	<grimaldo@panama.iaehv.nl>


ACKNOWLEDGEMENTS
  * Some of the directory navigator is taken from the Tk demo directory
    and modified to be usable in a standalone application.
  * The dialog routine is a mixed breed from the example given in
    the Tcl/Tk book and adapted.

COPYRIGHT

This software is freely distributable as long as all source is provided
and the authorship credits are left untouched.

   ---> I am marking all my tools with the dolphin icon <---


	      ************************
	      *	A P P E N D I X    A *
	      ************************

	Adding XChklogs to the FVWM Window Manager's root window menu

FVWM 
----
As mentioned at home I use fvwm (1.24) manager on Red Hat Linux. In my
configuration I added the following to /etc/X11/fvwm/system.fvwmrc

# This menu will fire up some System Administration utilities
Popup "SysAdmin-Popup"
        Title   "System Admin"
        Exec    "ControlPanel"  exec control-panel &
        Exec    "NetConsole"    exec /root/netconsole.tk &
        Exec    "X-Chklogs"     exec /usr/local/sbin/xchklogs.tk &
        Exec    "CR/PR"         exec /usr/local/sbin/crr.tk &
EndPopup

then in the same file I inserted the following in the Popup "Utilities"
definition:

	Popup   "System Admin"  SysAdmin-Popup

Alternatively you can put it on the GoodStuff module but I have
not done that.


HP-UX Visual User Environment
-----------------------------
Another lovely way to work with windows, usually you can create your
own toolbar and root window menus by modifying the ~/.vue/vuewmrc
file.
