Minkowsky

Raum/Zeit-Verwaltung


Server documentation

********************************************************************************
*                                                                              *
*			Minkowsky Administration guide			       *
*                                                                              *
********************************************************************************

Contents

 1) The structure of Minkowsky
 2) Software requirements
 3) Installation of Minkowsky
    3.1)   Instalation using the installer scripts
 4) Configuration files
    4.1)   The file  /etc/minkowsky
    4.2)   Definition of Users and Groups    in DATA_PATH/users and  DATA_PATH/groups
    4.3)   Definition of Rooms and Locations in DATA_PATH/rooms
    4.4)   Definition of (public) holidays   in DATA_PATH/holidays
    4.5)   Definition of Mail templates for Reminders.
    4.6)   The Permission String
    4.7)   Users preferences
    4.7.1) Removing User passwords
 5) Files and directory in DATA_PATH
 6) Multithreading
 7) Adminko 
 8) Signals
 9) Automatic Backup
10)  Know Bugs.
11) Future plans


1) The structure of Minkowsky

   Minkowsky is a client-server-application. Its has a central server
   on which all the data of the  appointments, tasks, addresses etc. are stored.
   The clients request a subset of this data and display them on the screen.
   All the data in Minkowsky are assigned to one or more users. It is possible
   to restrict other users access on this data. To allow Minkowsky to 
   distinguish different users Minkowsky has its own user management (see 4.2)

   The communication between server and client is done via a tcp socket on
   port 41999 (default).

   After creating a new user his/her password is empty. She/He must set it
   on her own in the User Preferences dialog of the client application.


2) Software requirements

   Server:
	- Perl 5 with installed NET-Module
	- gdb and screen for running the server in debugging mode.
	

   Client:
	Tcl/Tk >= 8.0
	Tix    >= 8.0
	
	


3) Installation of Minkowsky
   
   There are two ways of installing Minkowsky:
   - installing the rpm-packages
   - running the installer scripts of the source distribution

   rpm packages will not always be in sync with the source distribution
   especially on x86 platforms (My preferred platform in LinuxPPC ;-) )
      
   rpm-packages will install everything in /opt/minkowsky, apart from
   the configuration file  /etc/minkowsky and the servers database in
   /var/minkowsky.
   With the installer script you may choose were to put the program.

3.1) Instalation using the installer scripts
     
   There are individual packages for the server application, the client 
   application and the client documentation of each language. In all of the
   tarballs you find a instalation script named

			      installer_en.sh

   The server instalation script knows two options:
       -d    for developmental purposes. This creates a configuration
	     file in $HOME/minkowsky and shifts the port for this
	     version two 42001. Therefore a developmental server
	     can run in parallel to the productive.
       -drc  Add the parameter 'SERVER_DEBUG' to /etc/minkowsky. With
	     this parameter set the server starts gdb session which in turn 
	     turn is started in a screen session. Therefore in case of 
	     problems the server can be examined in the debugger without 
	     being restarted.
   
   Both of the installer scripts ask for certain parameters such as where to put
   the server's database, where to put the binaries etc. This parameters are 
   needed are partly needed on runtime and will be put into /etc/minkowsky.
   Server and client can share a common /etc/minkowsky-file. There must be a 
   /etc/minkowsky-file on every machine running the server or a client.



4) Configuration files

   There are five configuration files used by Minkowsky:
   - /etc/minkowsky
   - DATA_PATH/users
   - DATA_PATH/groups
   - DATA_PATH/rooms
   - DATA_PATH/holidays
   
   With DATA_PATH in the path of the server database  as found in 
   /etc/minkowsky.

   Additionally you can define the templates for the Mails send by Minkowsky
   in DATA_PATH/templates. If none defined the precompiled defaults are 
   taken, which are currently always in German (translated templates
   are welcome to be added into the servers code)

4.1) The file  /etc/minkowsky

   All of Minkowsky's configuration files have to be read line wise with
   parameter per line. Each lines begins with the Name of the parameter.
   After a whitespace (space or tab)  the value follows until the end of the 
   line. If client and server share on /etc/minkowsky file they ignore
   each other parameters.

   This are the parameters defined for the server:

     SERVER_BIN_PATH	  On this path the server binaries are located.
     
     DATA_PATH		  on this path the server's database is located. This
			  includes the data for the appointments, task etc.
			  and the user management data.

     TERMIN_DATA_PATH	  old name of the parameter DATA_PATH. Still supported.

     COMPANY		  A string to be included into Mails send by Minkowsky.
			  Its meant to contain the name of your company, 
			  organization or what ever.
			  Its included in the default mail templates to 
			  indicated where this mail comes from (especially 
			  useful with mails send to external participants of 
			  appointments). You may use it or not in your own mail 
			  templates.

     MYSELF		  A string to be included into Mails send by Minkowsky.
			  This string is meant to contain the name of this
			  application. Hence its default value is 
			  "Minkowsky Space/Time Management". If you dislike it
			  you may change it. In the default mail templates its 
			  added to mails together with 'COMPANY'. 
			  You may use it or not in your own mail templates.

     REPLY_ADDRESS        A e-mail address to which replies on Mails send by
			  Minkowsky should go to. This e-mail address is added
			  to the mails Reply-TO-Field.

     DEVELSERVER          If this parameter is present the server will run in
			  developmental mode. This parameter is boolean in a 
			  way. True if present and false if not present.

     NOTIFY_EVERY	  Determines how often modification-notification mails
			  should be send (for modification-notification mails 
			  see the parameter 'GETNOTIFY4 in DATA_PATH/users).
			  The value interpreted is in seconds.

     CHECKPRESENCE	  Minkowsky may display which users are currently 
			  present on the location. However Minkowsky can't 
			  determine this on its own. 
			  This parameter determines if Minkowsky should display
			  the presence status and where to find the data about
			  presence of users.
			  If the parameter is not given in /etc/minkowsky
			  presence status will not be display.
			  If the parameter is not given in /etc/minkowsky
			  the value is the name of the file containing the 
			  presence status data. This file must contain a list
			  a Minkowsky-usernames, one per line. All users listed
			  there are assumed to be present.

     VERBOSE		  The usual verbose flag. This parameter is boolean 
			  again. True if present, false if not.
			  NOTE: verbose active together with a server in 
			  debugging mode will allow  the administrator to
			  see all transfered data. Hence there is not much
			  confidential any more.

     SERVER_LANGUAGE	  defines the language to be used by the server, e.g.
			  for reminder mails etc.
			  This must be a two letter code. Currently only
			  two languages are supported:
			      en  =  English
			      de  =  German.
			  If SERVER_LANGUAGE is undefined in /etc/minkowsky
			  the Minkowsky server will use the language defined in
			  the environment variable LANG. If still undefined
			  Minkowsky will use English.
			  
			  
			  Note: The does not apply to the error message send by
				the server. They will always be in English.
			  

			  Note 2: As of version 0.5.0-0 the translation of the
				  is still incomplete. Hence even if English is 
				  defined it will be mixed English/German. 
				  Especially texts of reminder mails will be
				  German by default (See 4.5 on how to define
				  your own mail templates). Notification mail
				  text are translate, however.

     SERVER_DEBUG	  This flag is used by the init script. If set the server 
			  starts in debugging mode using screen and gdb otherise
			  it starts as simple process.

     SENDERTHREADS        Number of Sender threads. 
			  For details see section 6 about  Multithreading.
			  
     LOGINTHREADS	  Number of process login  threads. 
			  For details see section 6 about  Multithreading.

     BACKUP_PATH	  Path on which the Backup of Minkowsky data should be 
			  written. If this Path is set in /etc/minkowsky
			  backup facility is enabled. For details see section 9
			  below.

     PERMANENT_BACKUP_AT  Once a day the backup is written to directory named
			  according to the day but not the hour. This happen 
			  by default at 0:00:15. You may change this this
			  with this parameter. The number given here
			  is interpreted as hour (in 24 hour system) on which
			  the "permantent" backup is written. Number larger than
			  23 will disable the "permantent" backup.
			  For further details see section 9 below.			  


   This are the parameters defined for the client:
   
     MINKO_PATH		  Path on with the client application look for the
			  tcl-scripts (on MINKO_PATH/client)  and the 
			  online documentation (on MINKO_PATH/html)

     MINKO_SERVER	  Name or IP of the  Minkowsky server.

     MINKO_AUTO_MRR	  Boolean parameter again. Determines if the the 
			  Minkowsky-Remote-Reminder will be installed in the
			  users autostart folder or not. Currently only 
			  supported for KDE1 and KDE2 (Hints for Gnome or other
			  window managers are welcome).
			  A running Minkowsky-Remote-Reminder will enable you
			  to receive Reminder in a dialog window rather than
			  by e-mail. To run this app even without the client
			  being started the Minkowsky-Remote-Reminder have to
			  be added to the window managers autostart mechanism.

     ENABLE_SYNC          This flag is only of temprary use. As long as the PDA-
			  syncronisation module is in alpha state, this module 
			  must be enabled explicitly, either with this flag in
			  /etc/minkowsky to enable it on all clients or with
			  the commandline option -enableSync for each client
			  speparately. 
			  Please note thissyncronisation module may crash 
			  your server, since it not well tested, yet.


4.2) Definition of Users and Groups in DATA_PATH/users and  DATA_PATH/groups

     To access Minkowsky each user needs an account in Minkowsky's user 
     management. This accounts are defined in the file DATA_PATH/users.
     Furthermore users can be grouped into groups defined in DATA_PATH/groups.
     
     Both files DATA_PATH/users and DATA_PATH/groups are constructed the usual
     Minkowsky way: parameter per line starting with the name of the
     parameter followed by the parameters value(s) after whitespace(s). 
     Parameters belonging to one users or group are groups into a block.
     Each block ends when the next block begins or the file ends.
     Each block begins with a particular parameter line. the line
     of the parameter 'ID'. This is the only parameter with a different
     syntax (see below).

     Some parameter are available in both DATA_PATH/users and  DATA_PATH/groups
     other in only one of them. See the parameters description below.

     Comments in DATA_PATH/users and  DATA_PATH/groups are easy. All lines
     starting not with a defined parameter name are ignored, and may be
     used as comment/remark

     This are the parameters defined for DATA_PATH/users and/or DATA_PATH/groups
     
     ID
	   SYNTAX: ID='uid' 'username'

		   With this parameter a new user or group block starts.
		   It defines the user- or group-ID (uid or gid) and assigns
		   a username or group name to it.

		   uids may range from 0 to 9999999. The uid=0 is a special
		   case (as on UNIX systems ;-) ). The User with  uid=0
		   is the 'Minkowsky Administrator0' no matter how the account
		   is named. If no user with uid=0 is defined the server
		   itself defines one internally named 
		   'admin / Minkowsky Administrator'
		   The username might not contain any whitespace.

		   gids may range from 0 to 19999999. The gid=0 is again a 
		   special case (as on UNIX systems ;-) ). Administrators 
		   of the group with  gid=0 are 'Minkowsky Administrators' 
		   no matter how the group is named. If no group with gid=0 is 
		   defined the server itself defines one internally named 
		   all / All'
		   The group name might not contain any whitespace.

           EXAMPLE:
		   ID=1 goetz
		   ID=1 Alle

           AVAILABILITY:  DATA_PATH/users and  DATA_PATH/groups

	   
     FULL
	   SYNTAX: FULL 'full user name'

		   Defines the long or full user or group name.
		   This  is the preferably display name in the client.
		   However to log in you need the username from the
		   ID parameter
           
           EXAMPLE:
		   FULL Rüdiger Goetz

           AVAILABILITY:  DATA_PATH/users and  DATA_PATH/groups

     MAIL
 	   SYNTAX: MAIL 'mail-address'

		   Defines the e-mail address to which reminder mails etc.
		   should be send.

           EXAMPLE:
		   MAIL goetz
		   MAIL me@r-goetz.de

           AVAILABILITY:  DATA_PATH/users 

     SMTP 
 	   SYNTAX: SMTP 'smtp-server'

		   If mail to the above given e-ail address can't be delivered 
		   through the local MTA (e.g. sendmail or exim, ....)
		   you specify here a SMTP server to use instead.

           EXAMPLE:
		    SMTP stmp.provider.net

           AVAILABILITY:  DATA_PATH/users 

    MAIL2, MAIL3, MAIL4
 	   SYNTAX: MAIL2 'mail-address'
		   MAIL3 'mail-address'
		   MAIL4 'mail-address'

		   You may define up to 4 e-mail addresses per user.
		   With the parameters MAIL2 to MAIL4 the additional three
		   will be defined.

           EXAMPLE:
		  MAIL2: user@gmx.de

           AVAILABILITY:  DATA_PATH/users 

     SMTP2, SMTP3, SMTP4
 	   SYNTAX: SMTP2 'smtp-server'
		   SMTP3 'smtp-server'
		   SMTP4 'smtp-server'

		   Like the SMTP-Parameter defines a SMTP server to deliver
		   e-mail to the address given in in MAIL parameter, you can
		   define SMTP servers for the mail address MAIL2, MAIL3, MAIL4
		   in SMTP2, SMTP3, SMTP4, respectively.

           EXAMPLE:
		    SMTP2 stmp.provider.net

           AVAILABILITY:  DATA_PATH/users 

     GETNOTIFY4
 	   SYNTAX: GETNOTIFY4 'list of users'

		   Minkowsky may inform users about changes in other users
		   calendar. 
		   The parameter GETNOTIFY4 defines the list of users the
		   on which Minkowsky will listen for the user defined by the 
		   last ID-parameter. See the example below.

		   However, if one gets an e-mail on every single change
		   it might fill up your mailbox. Therefore Minkowsky collects
		   this information for some time and send this delayed.
		   The parameter NOTIFY_EVERY in /etc/minkowsky defines
		   at which times this information is send

		   So, what is this good for?
		   For example this might be useful if a secretary
		   is about to maintain the bosses calendar and another
		   user creates a appointment to which the boss should attend.
		   Than the secretary will receive an e-mail (at most delayed
		   by the time defined by NOTIFY_EVERY) that there is a change
		   in this bosses calender and what kind of change this is.

	   EXAMPLE:
		   ID=33 mueller
		   FULL Fritz Mueller
		   GETNOTIFY4 meyer schulze

		   ID=34 schulze 

		   Here the user mueller will be informed about changes
		   in the calendars of the users meyer and schulze.

           AVAILABILITY:  DATA_PATH/users 

     GROUPS
 	   SYNTAX: GROUPS 'list of groups'

		   Defines in which groups the user is member. All
		   groups defined here must exist in DATA_PATH/groups

           AVAILABILITY:  DATA_PATH/users 

     DONTLIST
 	   SYNTAX: DONTLIST

		   Defines to list not the particular user or group in the 
		   clients lists of users or groups.
		   This parameter should be used for user or groups which
		   left your company or organization. So, you not delete them
		   from the users or groups list but mark them. Hence they
		   still are listed in old appointments which they attended in 
		   their time at your company, but are not listed to be invited
		   to new appointments any more.
		   This parameter is boolean and has no further value.

           AVAILABILITY:  DATA_PATH/users and  DATA_PATH/groups

     COLOR
 	   SYNTAX: COLOR 'color1' 'color2'  
		   Defines the colors identifying a user in the calendar.
		   Users have a two color code,one upper and one lower color.
		   It might be a good idea to assign have a common color2
		   with a department or a subgroup of your organization and
		   use color1 to distinguish users within the department or
		   subgroup.
		   If no color defined both colors are assumed to be black.
	   EXAMPLE
		 COLOR #FF0000 #0000FF
           AVAILABILITY:  DATA_PATH/users 

     COLOR
 	   SYNTAX: COLOR 'color'
		   Defines the color identifying a group in the calendar.
		   Like users groups have a color code in Minkowsky's calendar
		   view. However there symbol in somewhat larger and unicolour.
	   EXAMPLE
		 COLOR #FF0000 
           AVAILABILITY:  DATA_PATH/groups

     PERM
 	   SYNTAX: PERM 'perm-admin' 'perm-member' 'perm-others'
	   
		   Defines the access permission to appointments in the 
		   calendar.
		   perm-admin   are the permission for the groups administrators
				if the appointments is assigned to this group.
		   perm-member  are the permission on watching a groups calendar
				if you are a group member.
		   perm-others  are the permission on watching a groups calendar
				if you are not a group member.
		   The values of perm-admin, perm-member and perm-others are
		   given in form of the permission strings as defined in
		   the clients online documentation or on 
		       http://r-goetz.de/minkowsky/en/docu/rechte.html#kal
		   See there also on how permissions are determined in the
		   calendar

		   Note: Both German and English permission strings are
			 allowed.

           EXAMPLE:
		   PERM zütkzütkd zütk---k- zü-------

           AVAILABILITY:  DATA_PATH/groups

     ADMIN
 	   SYNTAX: ADMIN 'list of users'
	   
		  Defines which users are administrators of this group.

	   EXAMPLE:
		   ADMIN mueller meyer

           AVAILABILITY:  DATA_PATH/groups

     PRIMARY
 	   SYNTAX: PRIMARY
	   
		  Again a boolean option. Defines that this group is the primary group
		  to set as default group on creation of new appointments.
		  There can only be one primary group. If more than one primary groups
		  are defined the last in the list is taken.
		  If no primary group define the predefined group 0 (All/Alle)
		  is used.

	   EXAMPLE:
		   ADMIN mueller meyer

           AVAILABILITY:  DATA_PATH/groups


4.3) Definition of Rooms and Locations  in DATA_PATH/rooms

    Rooms and other locations at which appointment may situated are defined
    in DATA_PATH/rooms. This file has the same syntax as DATA_PATH/users and
    DATA_PATH/groups. It only differs in the set of parameters available.
    
    Note: By definition all locations are called 'rooms' internally in 
	  Minkowsky.


     ID
	   SYNTAX: ID='rid' 'roomname'

		   With this parameter a new room block starts. It defines the 
		   room-ID (rid) and assigns a room name to it.

		   rids may range from 0 to 39999999. There is no special
		   meaning of the room with rid=0.
		   The room name might not contain any whitespace.

           EXAMPLE:
		   ID=1 ConferenceRoom

     PERM
 	   SYNTAX: PERM 'permission-String'
	   
		   Similar to the PERM parameter in DATA_PATH/groups. This
		   parameter defines the access permissions on the rooms
		   calendar. (However if a users has access permission from
		   other source, e.g. his is invited to a appointment or is
		   administrator, this might be overruled.)

	   EXAMPLE:
		PERM zütk---k

     - DETAILS
 	   SYNTAX: DETAILS 'text'
	   
		  Here you can give a detailed description about the room.
		  Currently only read by the Minkowsky server, but not used
		  any further. It may show it in future expansion of the
		  Minkowsky client.

4.4) Definition of (public) holidays in DATA_PATH/holidays

    Minkowsky has no own algorithm to determine on which days holidays will be.
    Therefore you have to tell this to Minkowsky. This is done in the file
    DATA_PATH/holidays. The client will highlight this holidays.

    As usual this file has a line wise structure. Each line defines the holidays
    within a one month in one year. The syntax of line is the following:

    'year' 'mon'  'list of holidays'

    'year' may range from 0 to infinity (O.k> not really must fit into a 32bit 
           signed integer).
    'mon'  may range from 1 to 12 (fro January to December, as you probably 
	   already guessed)
    'list  of holidays' is string with an even number of whitespace separate 
	   values. The first value in each pair in the day of month with the 
	   month defined by 'mon' and 'year'. The second value is the name
	   of the holiday. If the name contains whitespace it must be enclosed
	   in braces ('{' and '}').

    EXAMPLE:

    2001 12 24 {Heilig Abend} 25 Weihnachten 26 Weihnachten 31 Sylvester
    
    (Please excuse the use of German holidays here)

4.5) Definition of Mail templates for Reminders.

    The content of reminder mails (and other mails) send by the Minkowsky server
    is generate from templates. (One exception are the Notification mail
    mentioned above).

    This templates must be stored in DATA_PATH/templates/. There are predefined
    and hard coded templates which the server will use if here doesn't find any
    templates in DATA_PATH/templates/. You may define only some templates and 
    leave others on there predefined default.

    Note: As of version 0.5.0-0 of the server there are no English templates
	  predefined. Hence unless defined in DATA_PATH/templates/ the German
	  templates will be used. Translation or suggestions for English 
	  templates are welcome.

	  
    There are two template files for each type of mail send by the server,
    one for the subject line of the mail and one for the text of the mail.
    The subject file must have the extension .subject, the text file .text.
    The base name of the template files define for which mail type they should
    be used. (Please excuse that this names are German)

    The following mail template files will be used:


    EinladungIntern.text      for invitation mails to internal participants
    EinladungIntern.subject      

    EinladungExtern.text      for invitation mails to external participants
    EinladungExtern.subject       (those invited from the address book)

    ErinnerungIntern.text     for reminder mails to internal participants
    ErinnerungIntern.subject      

    ErinnerungExtern.text     for reminder mails to external participants
    ErinnerungExtern.subject      (those invited from the address book)

    ErinnerungToDO.text	      for reminders mails on running tasks
    ErinnerungToDO.subject

    MahnungToDO.text	      for reminders mails on delayed task 
    MahnungToDO.subject

    ShiftDateIntern.text      for notes about shifts on a particular instance of
    ShiftDateIntern.subject       repeated appointment, send to internal 
				  participants
 
    ShiftDateExtern.text      for notes about shifts on a particular instance of
    ShiftDateExtern.subject       repeated appointment, send to external 
				  participants

    SuspendDateIntern.text    for notes about canceling particular instance of
    SuspendDateIntern.subject     repeated appointment, send to internal 
			 	  participants

    SuspendDateExtern.text    for notes about canceling particular instance of
    SuspendDateExtern.subject     repeated appointment, send to external 
			 	  participants


    Obviously this template must contain placeholders for the data of the 
    appoint meant or task. The following are defined:
    

       %I  Name of the initiators
       %A  Content of the COMPANY parameter from /etc/minkowsky
       %M  Content of the MYSELF  parameter from /etc/minkowsky
       %T  Name or title of the appointment or task 
       %D  Details or description text of the appointment or task 
       %S  End date and time of the appointment or target date of the task
       %H  Date of the day on which the mail is send.
       %%  The  '%'-letter itself
       %?T Conditional text:
	   The template text between $?T and the next %] will only be copied
	   to the mail if length of the name or title of the appointment or task
	   is not of zero length.
	   Please note you can't nest conditionals here.
       %]  End of the .conditional (text).

    Only valid on appointments:
       %E  List of the invited participants
       %l  with SERVER_LANGUAGE="de" this is replaced by the text 'läd' if the
	   number of inviting participants (including the initiator) is 1.
	   Otherwise it is replaced by the text 'laden'.
	   with SERVER_LANGUAGE="en"  this replaced by the text 'invites' or
	   'invite' depending on the of inviting participants like in the
	   German version.
       %B  The start date and time of the appointment
       %R  the location (room) in which the appointment took place.

    Only in shifts of appointments
       %N  Contents of the details field of the shift dialog.
       %?N Conditional text:
           Like %?T, but depends on the size of the Contents of the details 
	   field of the shift dialog.


4.6 The Permission String

    The permission string is used in PERM parameter of DATA_PATH/groups and
    DATA_PATH/rooms and in the Minkowsky client. The permission strings
    allows a fine graduation of permission.  You grant permission in four
    different areas of an appointment:

    * Time / Location: [short l or z]
      This includes all settings about the date, repeating and the location of 
      the appointment. Appointments are visible to a user if read access on 
      Time / Location is granted to him.
    * Texts: [short t or ü]
      This includes the title and text about appointment details.
    * Participants: [short p or t]
      This includes the list of participants and all settings made there. Also 
      included is the privacy status and the priority.
    * Comments: [short c or k]
      Includes reading and adding comments.

      Note: There are two sets of short symbols: ltpc and zütk (one derived
	    from English the other from German). In the configuration files 
	    only there position is relevant (see below). However, for reading 
	    convenience you should stick to one set.

      Note 2: To access reminder settings a user need permission on 
	      Time / Location and Participants.

    On each of the four areas read or write (or both) access may be granted. 
    Additionally the permission to delete might be granted (short symbol d in
    either set). This give a total of nine grants, which will be represented
    by a nine character long string:


	 ltpcltpcd    or    zütkzütkd

    The first 4 characters in permission string stands for the read permissions.
    The second 4 characters in permission string stands for the write 
    permissions and the last character for the delete permission. 
    A denied denied permission is symbolized by a '-'. A granted permission
    is symbolized by any other character preferable by the one given about.

    In each group of four characters  
       the first     stands for the  'Time / Location'-permission 
       the second    stands for the  'Texts'-permission 
       the third     stands for the  'Participants'-permission  and
       the forth     stands for the  'Comments'-permission 



    Note: The client application will display this string in a somewhat extended
	  form:
		r=ltpc w=ltpcd      or   r=zütk w=zütkd
          This form is _not_ valid for use in the PERM parameter of 
	  DATA_PATH/groups or DATA_PATH/rooms !.

    Example:
	The strings

	    lt-c-t-c-    and       zü-k-ü-k-

	both grant read and write permission for 'Texts' and 'Comments' and
	read permission on 'Time / Location', but no access on 'Participants'
	and no delete access.

	The string 

	    qr-h-v-w-

        will do the same. However it will be even worse readable than the
	the normal permission string.
    

4.7 Users preferences

    For each user Minkowsky maintains a file of user preferences on the
    server side in DATA_PATH/prefs/uid.prefs where uid is replaced by the 
    users ID as defined in DATA_PATH/users.
	
    This file has the usual line wise structure. However, this file can be 
    totally maintained through the Minkowsky client application.
	
    However there might is one exception:

4.7.1)   Removing User passwords

    If a user lost his/her password it can be removed by deleting
    the line starting with 'PWD' in the users preferences file.
	

5) Files and directory in DATA_PATH

   On DATA_PATH Minkowsky stores all its data and all its configuration
   apart from /etc.minkowsky:

   1) The appointment etc data is found in:

	   dates		The data of the appointments
	   dates.shift		The data of changes on particular instances of
				repeated appointments
           comments/*.txt       One file for each appointment to store the 
				comments on this appointment
	   todos		The data of the task (or todos)
	   projs		The data of the projects
	   address		The data of the addresses of the address book
	   notiz/*.txt		The data of the memo pad (Notizbuch) of each
				address.
				

	2) General configuration files

	   these are 
		 users
		 groups
		 rooms
		 holidays
		 templates/*
	   for detailed description see chapter 4 of this guide
	
	3) Users data

	   There are two kinds of users specific data in Minkowsky,
	   each stored in its own subdirectory:
	   
	   prefs	  Here the users preferences are stored. See Section
			  4.7 for details.
	   userData	  In this folder users modifications on particular
			  appointments are stored (e.g. the ignore status)

6) Multithreading.

   Starting with Version 0.5.2.0 the server of Minkowsky is multithreaded.
   When Minkowsky starts a couple of thread are spawned.
   These are:
   *  one listener thread
   *  a couple of sender threads (16 by default)
   *  one login listener thread
   *  a couple process login threads (8 by default)
   *  one process thread (to be precise this thread is not spwaned, but it
      is the main thread after spawning the other threads)
   The number of sender threads and process login threads might be changed
   in /etc/minkowsky with the SENDERTHREADS and LOGINTHREADS varibales.
   
   The login listener thread checks the socket for clients connecting.
   If a client connects the control is passed to the next free process login 
   thread which processes the login request. Therefore the login listener
   is back listing within a short period of time and hence several logins
   can be processed in parrallel (limited by the number of process login threads).

   The listener thread listens on the sockets of already connected client
   for there request. Certain special request  are processed directly by the
   listener. All other are put into a process queue and send back a task id 
   (or ticket) to the client. 
   The client may now request the result of a certain task. In this case
   the listener passes the request on to the next free sender thread.
   If the task is completly processed, the result is send to the client and the
   task is closed. If not s 'pending' signal is send to the client  and the
   client will request the result later again.
   Besides requesting reults of tasks the listener thread ansers 'exit' request
   and 'serverUp?" requests directly.

   The process thread in turn waits for task put into the process queue.
   If there are any tasks in the queue the process thread processes the first
   writes back the result  into the queue and marks the task as completed.
   Afterwards it continues with the next task (if any).
   Between to two client-task the process thread check for the internally
   scheduled task, such as sending reminders, amcking backup and so on.

   

7) Adminko 

   Adminko is a GUI-Tool to manage the configuration files described in 
   chapter 4 (expect for the user preferences).
   Please note that currently adminko can't mange DATA_PATH/holidays and
   DATA_PATH/templates. However, this is planed for future releases.

8) Signals

   Minkowsky traps three signals:
   
   SIGTERM
   SIGINT   : This two signals will initiate a clean shutdown of the Minkowsky
	      server. All data will be synced to disk before terminating.
   SIGUSR1  : This will cause Minkowsky to reread data. This includes both
	      the data managed by Minkowsky (appointments etc.) as well as
	      configuration data in the configuration files.
	      Note: Due to bugs this signal handling was disabled. Please
		    restart the sever instead.
   
9) Automatic Backup

      Starting with version  0.5.2.0 Minkowsky includes a backup module.
      This module is enabled if a BACKUP_PATH is defined in /etc/minkowsky.
      The backup is done once a hour on HH:00:15 (or so). The backup writes
      a complte copy of DATA_PATH to BACKUP_PATH/HH with HH replaced by the 
      current hour. Obviously this backups are overwritte the next day.

      Once a day (default: 00:00:15) the backup is written to another
      directory which is not overwritte the other day (hence it is "permanent"
      if you like). This directory is named by the current date 
      BACKUP_PATH/yyyy-mm-dd (yyyy-mm-dd beeing the ISO form of a date).
      You may change hour on which this "permanent" Backup is written with
      the PERMANENT_BACKUP_AT variable in /etc/minkowsky.

      The Backup is done by the  shell script DATA_PATH/backupMinkowsky.sh.
      You may replace this script with your own script. Minkowsky passes
      to arguments to this script, the source path and the destination path.
      The script is expected to create directory of the destination path as
      neccessary and copy the whole contents of the source path to the
      destination path. 
      

10)  Know Bugs.

    - In rare cases Mails send by Minkowsky contain corrupted data. Reason for
      that is still unknown.

    - Appointments and Task containing users no longer listed in 
      DATA_PATH/users, may cause a crash of the server.  The same applies to
      groups and rooms no longer listed.

      This bug should be fixed at most places by now. However, I am not 
      absolutely sure if I found any place this bug was present.
      Apart from this bug it seems to be advisable to keep any user, group
      or room listed to keep the information on older appointments etc.
      complete.

    - There might be some parts of the code where translations are incomplete,
      especially in the server code.

    - Don't use braces in any text you enter into Minkowsky. Although there is
      code in the client to suppress using braces in entry-widget and replace
      them in text(-area)-widgets there might be still some places missing this
      new code.

11) Future plans
    - Complete translation
    - PDA synchronization
    - several small things
    - ???    

Rüdiger Goetz
Last modified: Mon Oct 14 22:22:00 CEST 2002