
XDiary Installation
===================
  
  This chapter describes the installation of XDiary, version 3.0.
  
  XDiary is a simple personal calendar that makes it easier for you 
  to plan your day.
  
  XDiary has been tested on the platforms below:
  
   * IBM RISC Station/6000, AIX Version 4.1, X11R5 and Motif 1.2
  
   * HP "Snake" series 700, HP-UX 9.n, X11R5 and Motif 1.2
  
   * SUN Sparcstation, Solaris 2.3, X11R5 and Motif 1.2
  
   * SGI Iris, IRIX 5.3, X11R5 and Motif 1.2
  
  Although not tested, XDiary should compile and run on most UNIX 
  platforms which have:
  
    * POSIX libraries and include files.
    
    * ANSI-C compiler and standard make.
  
    * X11R5 (including Imake and xmkmf)
  
    * Motif 1.2
  
  To make the compilation an installation smooth and easy, read the
  'Installation' chapter below.
  
  Enjoy!
  
  
  

Installation
============
  
  This chapter describes the unpacking, compilation and installation of
  XDiary. Just follow the steps and you will soon have your own XDiary
  up and running.
  
  The Quick-Start procedure is described below:
  
    $ uncompress xmdiary-n.m.tar.Z
    $ tar -xvf xmdiary-n.m.tar
    $ cd xmdiary-n.m
    
    Edit XDiary.tmpl
  
    $ xmkmf
    $ make Makefiles
  
    $ make
    $ make install
    $ make install.man
  
    $ xdiary
  
  

Unpacking
=========
  
  The XDiary distribution comes as a compressed tar file. The first
  thing you need to do is to unpack this file. After the file has been
  unpacked, the directory xmdiary-n.m has been created (n.m stands for
  the version and release number).
  
  To unpack the XDiary distribution, proceed as follows:
  
    $ uncompress xmdiary-n.m.tar.Z
    $ tar -xvf xmdiary-n.m.tar
  
  You should now have the following directory structure:
  
    xmdiary-n.m
      tools - General routines
      xtools - X-windows routines
      dtools - XDiary routines
  
      xdiary - The main XDiary program
  
      xdaclafs - Program to control calendar access under AFS
      xdaclunix - Program to control calendar access under UNIX
      xdalarm - Program to remind you about calendar events
      xdcustom - Customize XDiary
      xddump - Dump a calendar to an ASCII file.
      xdinitdb - Initialize a calendar with correct permissions
      xdlight - A "light" version of XDiary
      xdnotify - Watch for calendar notifications
      xdprformat - Convert calendar output to Postscript
      xdremind - Remind you about events
      xdremove - Remove entries form a calendar
      xdrestore - Insert calendar events from ASCII file
  

Compiling and installing XDiary
===============================
  
  The first thing you need to do is to configure to suit you needs.
  Look at the file XDiary.tmpl and make the necessary changes. All
  parameters that can be configured are described.
  
  After you have tailored XDiary.tmpl, create the Makefiles with the
  commands:
  
    $ cd xmdiary-n.m
    $ xmkmf
    $ make Makefiles
  
  This will use Imake to create Makefiles from the distributed
  Imakefiles.
  
  To compile XDiary, run the command:
  
    $ make
  
  After the compilation, you must install XDiary. XDiary will be
  installed in the directories you configured in XDiary.tmpl. The XDiary
  executable must be in your PATH and the XDiary resource files must be
  picked up by the Xt calls.
  
  To check where XDiary will install the files, run the command:
  
    $ make -n install
    $ make -n install.man
  
  To actually install the files, run the command:
  
    $ make install
    $ make install.man
  
  XDiary will install the executable files in a directory which must be
  in your PATH. Library files (help files, scripts etc.) will be
  installed in another directory. Both these directories are
  configurable in XDiary.tmpl.
  

Running XDiary
==============
  
  After installing XDiary, you are probably eager to try it out. Just
  type the command:
  
    $ xdiary
  
  XDiary will now start and will ask you if it is OK to create your
  personal calendar in the directory $HOME/Diary.
  
  After the calendar is created, you can enjoy your first XDiary
  session.
  

Group calendar
==============
  
  This chapter describes various way of installing and configuring
  XDiary to be used as a group calendar. When used as a group calendar,
  it is possible to look at other peoples calendars and make entries in
  other peoples calendars (depending of the access permissions of
  course).
  
  Some if the differences between a group calendar and your personal
  calendar are:
  
   * A group calendar is accessed by many users.
  
   * The group calendar needs some form of access control which must be
     maintained.
  
  All the XDiary calendars are stored as files in the normal file
  system. To be able to access another person's calendar, you:
  
   * must be able to access the file where the calendar is stored. This
     assumes some kind of shared file system which for example can be NFS,
     DFS or AFS.
  
   * must have permission to access the files which contain the
     calendar. In DFS and AFS this is easier since you can define access
     control lists (ACLs) on directories. The ACL contains a list of
     people together with their access rights. In NFS this is more
     difficult since the access control is limited to owner, group and
     others.
  
  The following chapters try to provide you with some guidance if you
  want to setup XDiary as a group calendar.
  
  

User access
===========
  
  When you use XDiary as a group calendar, you must be able to define 
  the access rights for other users. If you have your private calendar, 
  this is easy; no other users except yourself can read or write the 
  diary. When you have a group calendar, there must be a way for you 
  to allow other users to read or write the diary database.
  
  In the standard UNIX world, you can define file protections, i.e. 
  for each file, you can define access rights for the owner, the group 
  and other users. The access rights you can define are read, write 
  and execute. 
  
  Assume you want other members in you group (engineering) to be able 
  to read and write your file while other users should only be allowed 
  to read the file. The access rights would the be:
  
   owner (rw),  group (rw), others (r).
  
  This is all fine, but what if you also would like the marketing group 
  to have read and write access to your file? 
  
  The only way to do this is to ask the system manager to define a 
  new group (e.g. markeng) containing the users in the engineering 
  group and the users in the marketing group. Each time you want to 
  add or delete users in the group markeng, it must be done by the 
  system manager.
  
  The example above shows some of the difficulties you will encounter 
  when you are using XDiary as a group calendar. Since the standard 
  UNIX file protection is not 'flexible' enough for XDiary, there are 
  some 'tricks' you can use depending on in which environment XDiary 
  is installed.
  
  If you don't know which environment you are using, ask your system 
  administrator.
  

Access standard UNIX
====================
  
  The standard UNIX environment allows you to define access rights 
  for files based on owner, group and others.
  
  This is the most 'primitive' of all environments.
  

Access UNIX ACL
===============
  
  Under some UNIX dialects, you can define Access Control Lists (ACL)
  for files and directories. An ACL is a list of users and groups where
  you can define access rights for each individual user and group.
  

Access Andrew File System
=========================
  
  The Andrew File System (AFS) allows you to specify Access Control 
  Lists (ACL) for directories (not for individual files!). An ACL is 
  a list of users and groups where you can define access rights for 
  each individual user and group.
  
  AFS defines the following access rights: 
  
   Read, Write, Insert, Delete, Lock, Lookup and Administer.
  
  This is the best and most flexible environment for XDiary as a group 
  calendar.
  

Scenarios
=========
  
  Here are a few examples of how XDiary's group calendar capabilities 
  can be used. Select the example that best describes your requirements:
  
   * Site information 
     A separate group calendar that can be (read) accessed by all users. 
     There are no private entries. One user administers the calendar.
  
   * Group bulletin board 
     A separate group calendar which a group of users can read and write. 
     There are no private entries.
  
   * Closed group bulletin board 
     A separate group calendar which selected users can read and write. 
     The users are members of different groups. There are no private entries.
  
   * Shared private calendar 
     Users within a group are sharing their private calendars, i.e. a 
     user can read other users calendars (with the exception of private 
     entries).
  
   * Manager-Secretary calendar 
     One user (a manager) allows specific users to read his/her private 
     calendar (with the exception of private entries). One specific user 
     (a secretary) can read and write the calendar (with the exception 
     of private entries).
  

Solutions
=========
  
  This section contains examples of how XDiary can be configured/installed 
  depending on the selected scenario. The guidelines described here 
  are a recommendation, your specific system might require another 
  setup.
  
  In the description below, (root) means that this step can only be 
  done if you have root privileges.
  

Standard UNIX
=============
  

Site information
================
  
   * Select a directory to hold the new calendar.
  
   * Create the XDiary database directory (<directory>) with the command:
       $ xdinitdb <directory>
  
   * Set the following file protections:   
      $ find <directory> -type d -exec chmod 744 {} ';'
      $ find <directory> -type f -exec chmod 644 {} ';'
  
   * Check the file protections with:   
       $ ls -lR <directory>
  

Group bulletin board
====================
  
   * (root) If the group does not exist or you are not member of the group, 
     ask the system manager to define it for you.
  
   * Select a directory to hold the new calendar.
  
   * Create the XDiary database directory (<directory>) with the command:
       $ xdinitdb <directory>
  
   * Set the following file protections:   
       $ find <directory> -type d -exec chmod 770 {} ';'
       $ find <directory> -type f -exec chmod 660 {} ';'
  
   * Change group (<group>) of the files:   
       $ find <directory> -exec chgrp <group> {} ';'
  
   * Check the file protections with:   
       $ ls -lR <directory>
  

Closed group bulletin board
===========================
  
   * (root) Create a new group (/etc/group) with the selected users.
  
   * Select a directory to hold the new calendar.
  
   * Create the XDiary database directory (<directory>) with the command:
       $ xdinitdb <directory>
  
   * Set the following file protections:   
       $ find <directory> -type d -exec chmod 770 {} ';'
       $ find <directory> -type f -exec chmod 660 {} ';'
  
   * Change group (<group>) of the files:   
       $ find <directory> -exec chgrp <group> {} ';'
  
   * Check the file protections with:   
       $ ls -lR <directory>
  

Shared private calendar
=======================
  
   * Select a directory to hold the new diary database.
  
   * Create the XDiary database directory (<directory>) with the command:
       $ xdinitdb <directory>
  
   * Set the following file protections:   
       $ find <directory> -type d -exec chmod 771 {} ';'
       $ find <directory> -type f -exec chmod 661 {} ';'
  
   * (root) Make sure XDiary is installed as 'Privileged XDiary', see 
     chapter Installation below.
  
   * (root) Change group (diary) of the files:   
       $ find <directory> -exec chgrp diary {} ';'
  
   * (root) Set the SETGID bit on the directories:   
       $ find <directory> -type d -exec chmod g+s {} ';'
  
   * Check the file protections with:   
       $ ls -lR <directory>
  
   * Define the diary database in the customize window. 
  
   * In the Access Control window:
     Allow the selected users read, write and message access.
     Allow all users message access.
  

Manager-secretary calendar
==========================
  
   * Select a directory to hold the new diary database.
  
   * Create the XDiary database directory (<directory>) with the command:
       $ xdinitdb <directory>
  
   * Set the following file protections:   
       $ find <directory> -type d -exec chmod 771 {} ';'
       $ find <directory> -type f -exec chmod 661 {} ';'
  
   * (root) Make sure XDiary is installed as 'Privileged XDiary', see 
     chapter Installation below.
  
   * (root) Change group (diary) of the files:   
       $ find <directory> -exec chgrp diary {} ';'
  
   * (root) Set the SETGID bit on the directories:   
       $ find <directory> -type d -exec chmod g+s {} ';'
  
   * Check the file protections with:   
       $ ls -lR <directory>
  
   * Define the diary database in the customize window. 
  
   * In the Access Control window:
     Give the specific user (secretary) read and write, and Message access.
     Allow the selected users read and message access.
     Allow all users message access.
  

Andrew File System
==================
  

Site information
================
  
   * Select a directory to hold the new diary database.
  
   * Create the XDiary database directory (<directory>) with the command:
       $ xdinitdb <directory>
  
   * Remove all ACL information:   
       $ find <directory> -type d -exec fs setacl \
       -clear {} $LOGNAME all ';'
  
   * Allow read, lookup and lock privileges for all authorized users in 
     this cell:
       $ fs setacl <directory> system:authuser rlk
  
   * Allow read and write privileges for the group:
       $ fs setacl <directory> <group name> write
  
   * Check the ACL rights with:   
       $ find <directory> -type d -exec fs listacl {} ';'
  

Group bulletin board
====================
  
   * Select a directory to hold the new diary database.
  
   * Create the XDiary database directory (<directory>) with the command:
       $ xdinitdb <directory>
  
   * Create a group with the users which you want to allow access (or 
     you can use an existing group):   
       $ pts creategroup <group name>
       $ pts adduser -user <user(s)> -group <group name>
  
   * Remove all ACL information:   
       $ find <directory> -type d -exec fs setacl \
       -clear {} $LOGNAME all ';'
  
   * Allow read, write, lookup and lock privileges for all authorized 
     users in this cell:
       $ fs setacl <directory> system:authuser rwdilk
  
   * Check the ACL rights with:   
       $ find <directory> -type d -exec fs listacl {} ';'
  

Closed group bulletin board
===========================
  
   * Select a directory to hold the new diary database.
  
   * Create the XDiary database directory (<directory>) with the command:
       $ xdinitdb <directory>
  
   * Create a group with the users which you want to allow access (or 
     you can use an existing group):   
       $ pts creategroup <group name>
       $ pts adduser -user <user(s)> -group <group name>
  
   * Remove all ACL information:   
       $ find <directory> -type d -exec fs setacl \
       -clear {} $LOGNAME all ';'
  
   * Allow read and write privileges for the group:
       $ fs setacl <directory> <group name> write
  
   * Check the ACL rights with:   
       $ find <directory> -type d -exec fs listacl {} ';'
  

Shared private calendar
=======================
  
   * Select a directory to hold the new diary database.
  
   * Create the XDiary database directory (<directory>) with the command:
       $ xdinitdb <directory>
  
   * Remove all ACL information:   
       $ find <directory> -type d -exec fs setacl \
       -clear {} $LOGNAME all ';'
  
   * Allow all users to send messages:   
       $ fs setacl <directory>/Message system:authuser lki
  
   * Allow specific users to read the calendar:   
       $ fs setacl <directory> <user> rlk
  
   * Check the ACL rights with:   
       $ find <directory> -type d -exec fs listacl {} ';'
  

Manager-secretary calendar
==========================
  
   * Select a directory to hold the new diary database.
  
   * Create the XDiary database directory (<directory>) with the command:
       $ xdinitdb <directory>
  
   * Remove all ACL information:   
       $ find <directory> -type d -exec fs setacl \
       -clear {} $LOGNAME all ';'
  
   * Allow all users to send messages:   
       $ fs setacl <directory>/Message system:authuser lki
  
   * Allow specific users to read the calendar:   
       $ fs setacl <directory> <user> rlk
  
   * Check the ACL rights with:   
       $ find <directory> -type d -exec fs listacl {} ';'
  

Installation
============
  
  This chapter describes the step you (root) need to take to install 
  XDiary to be used as a group calendar. Depending on which environment 
  (file system) you are using, different installation procedures are 
  used.
  

Standard UNIX
=============
  
  To install XDiary as a group calendar, you will need to do the following 
  steps. If a step is marked with root, it means that this step can 
  only be made if you have root privileges.
  
  First you will need to make the following changes to XDiary. These 
  changes are made only once:
  
   * root: Create a special diary group that will be used for XDiary, 
     for example diary. This group should not have any members.
  
   * root: Change the group of the XDiary executable files:
       $ chgrp diary xdiary
       $ chgrp diary xdlight
       $ chgrp diary xdalarm
  
   * root: Set the SGID bit of the files:
       $ chmod g+s xdiary
       $ chmod g+s xdlight
       $ chmod g+s xdalarm
  
     When the files run, the run as if the user belonged to the group
     diary.
  
  For each UNIX directory that should contain (or contains) a group 
  calendar, do the following:
  
   * If the diary database does not exist, create it:
       $ mkdir <directory>
       $ xdinitdb <directory>
  
   * Set the following file protections:
       $ find <directory> -type d -exec chmod 771 {} ';'
       $ find <directory> -type f -exec chmod 660 {} ';'
  
   * root: Change group of the directory to the diary group and set the 
     SGID bit on all directories:
       $ find <directory> -exec chgrp diary {} ';'
       $ find <directory> -type d -exec chmod g+s {} ';'
  
     The allows the XDiary executables to access the calendar files.
     XDiary will then determine if you have the necessary privileges
     or not.
  

Andrew File System
==================
  
  If you are using Andrew File System (AFS), you are lucky since you 
  need to do nothing special to use XDiary under AFS.
