imip-agent

Annotated docs/wiki/FilesystemUsage

1192:00d37da98920
1158:1a4f01ff7336
1089:54e1af14f1a2
2016-04-22 Paul Boddie file changeset files shortlog Build the translation files when installing if they are absent.
paul@988 1 
= Filesystem Usage =
paul@988 2 
 
 paul@988      3 
The behaviour and operation of imip-agent is controlled by resources stored
 
 paul@988      4 
in the filesystem on the host on which the software is running. These resources
 
 paul@988      5 
are organised as follows:
 
 paul@988      6 
 
 paul@988      7 
{{{#!table
 
 paul@988      8 
'''Resource''' || '''Default Location''' || '''Purpose'''
 
 paul@988      9 
==
 
 paul@1039     10 
Free/busy || `/var/www/imip-agent/static`
 
 paul@1039     11 
|| Per-user directories containing [[../FreeBusyPublishing|free/busy resources]]
 
 paul@1039     12 
.. for publication over the Web
 
 paul@1039     13 
==
 
 paul@1039     14 
Journal || `/var/lib/imip-agent/journal`
 
 paul@1039     15 
|| Per-quota directories containing journal information recording
 
 paul@1039     16 
.. [[../Resources|resource]] usage
 
 paul@988     17 
==
 
 paul@988     18 
Preferences || `/var/lib/imip-agent/preferences`
 
 paul@988     19 
|| Per-user directories containing [[../Preferences|preferences]] controlling
 
 paul@988     20 
.. each user's experience of the software
 
 paul@988     21 
==
 
 paul@1039     22 
Store || `/var/lib/imip-agent/store`
 
 paul@1039     23 
|| Per-user directories containing calendar objects and scheduling information
 
 paul@988     24 
}}}
 
 paul@988     25 
 
 paul@988     26 
Note that the free/busy resources are located in `/var/www` as opposed to
 
 paul@1039     27 
`/var/lib` since they are intended to be published on the Web.
 
 paul@1039     28 
 
 paul@1089     29 
Meanwhile, the journal and store resources are only present in the filesystem
 
 paul@1089     30 
if the [[../FileStore|file store]] is in use. Where a
 
 paul@1089     31 
[[../DatabaseStore|database store]] is being used instead, such resources are
 
 paul@1089     32 
located in a database system.
 
 paul@1089     33 
 
 paul@1039     34 
== Journal Structure ==
 
 paul@1039     35 
 
 paul@1039     36 
Within the journal directory are a collection of subdirectories, each of which
 
 paul@1039     37 
represent a distinct quota group for one or more resources. When a user attempts
 
 paul@1039     38 
to reserve a resource in such a group, their ability to schedule that resource
 
 paul@1039     39 
will depend on how much they are using the other resources in that group.
 
 paul@1039     40 
 
 paul@1039     41 
The directory for each quota group contains the following entries:
 
 paul@1039     42 
 
 paul@1039     43 
{{{{#!table
 
 paul@1039     44 
'''Entry''' || '''Purpose'''
 
 paul@1039     45 
==
 
 paul@1039     46 
`freebusy`
 
 paul@1039     47 
|| A directory containing files, one per user, each containing period descriptions
 
 paul@1039     48 
.. for reservations made by that user, in chronological order, structured
 
 paul@1039     49 
.. similarly to the `freebusy` file found in each user's own store; the record is
 
 paul@1039     50 
.. consolidated for all resources in a quota group, but it is not consolidated for
 
 paul@1039     51 
.. groups of users
 
 paul@1039     52 
{{{
 
 paul@1039     53 
freebusy/USER
 
 paul@1039     54 
}}}
 
 paul@1039     55 
==
 
 paul@1039     56 
`groups`
 
 paul@1039     57 
|| A mapping from user identities to group identifiers indicating the sharing
 
 paul@1039     58 
.. of a quota across a number of users
 
 paul@1039     59 
==
 
 paul@1039     60 
`journal`
 
 paul@1059     61 
|| A directory containing consolidated schedules, one per user or user group,
 
 paul@1059     62 
.. describing reservations for resources sharing a quota made by the indicated
 
 paul@1059     63 
.. user or group, structured similarly to the `freebusy` file found in each
 
 paul@1059     64 
.. resource's own store
 
 paul@1039     65 
{{{
 
 paul@1039     66 
journal/GROUP
 
 paul@1039     67 
journal/USER
 
 paul@1039     68 
}}}
 
 paul@1039     69 
==
 
 paul@1039     70 
`limits`
 
 paul@1039     71 
|| A mapping from user identities or group identifiers to quota limits
 
 paul@1039     72 
}}}}
 
 paul@988     73 
 
 paul@988     74 
== Store Structure ==
 
 paul@988     75 
 
 paul@1039     76 
Within the store directory are a collection of user-specific subdirectories
 
 paul@1039     77 
acting as each user's own store directory containing various files and further
 
 paul@1039     78 
subdirectories.
 
 paul@1039     79 
 
 paul@988     80 
The store directory for each user is considered in isolation from all other
 
 paul@1039     81 
users' directories: imip-agent ''does not'' go looking for information belonging
 
 paul@1039     82 
to other users when processing information on behalf of a particular user.
 
 paul@988     83 
 
 paul@1039     84 
The following entries are defined within a user's own store directory:
 
 paul@988     85 
 
 paul@988     86 
{{{{#!table
 
 paul@1039     87 
'''Entry''' || '''Purpose'''
 
 paul@988     88 
==
 
 paul@988     89 
`cancellations`
 
 paul@988     90 
|| Retains cancelled event details in `objects` and `recurrences` structures
 
 paul@988     91 
.. corresponding to those at the top level of the store from which the
 
 paul@988     92 
.. cancelled events originate:
 
 paul@988     93 
{{{
 
 paul@988     94 
cancellations/objects/UID
 
 paul@988     95 
cancellations/recurrences/UID/RECURRENCE-ID
 
 paul@988     96 
}}}
 
 paul@988     97 
==
 
 paul@988     98 
`counters`
 
 paul@988     99 
|| Retains counter-proposals for events in `objects` and `recurrences`
 
 paul@988    100 
.. structures corresponding to those at the top level of the store for which
 
 paul@988    101 
.. the counter-proposals are received, with a counter-proposal for each
 
 paul@988    102 
.. respondent being held for each object or recurrence involved:
 
 paul@988    103 
{{{
 
 paul@988    104 
counters/objects/UID/ATTENDEE
 
 paul@988    105 
counters/recurrences/UID/RECURRENCE-ID/ATTENDEE
 
 paul@988    106 
}}}
 
 paul@988    107 
==
 
 paul@988    108 
`freebusy`
 
 paul@988    109 
|| A file containing period descriptions in chronological order, one per line,
 
 paul@988    110 
.. indicating start and end datetimes (in UTC), unique identifier (`UID`),
 
 paul@988    111 
.. transparency, summary and organiser
 
 paul@988    112 
==
 
 paul@988    113 
`freebusy-offers`
 
 paul@988    114 
|| A file containing period descriptions in chronological order for
 
 paul@988    115 
.. scheduling offers made by counter-proposals sent by the user
 
 paul@988    116 
==
 
 paul@988    117 
`freebusy-other`
 
 paul@988    118 
|| A collection of files, one per user, each containing period descriptions
 
 paul@988    119 
.. received or deduced for that user in chronological order, structured similarly
 
 paul@988    120 
.. to the store user's own `freebusy` file
 
 paul@1039    121 
{{{
 
 paul@1039    122 
freebusy-other/USER
 
 paul@1039    123 
}}}
 
 paul@988    124 
==
 
 paul@988    125 
`freebusy-providers`
 
 paul@988    126 
|| A file containing details of [[../EventRecurrences|recurring events]] for which
 
 paul@988    127 
.. new free/busy records must be [[../CronIntegration|periodically generated]]
 
 paul@988    128 
.. because these events recur indefinitely
 
 paul@988    129 
==
 
 paul@988    130 
`objects`
 
 paul@988    131 
|| A collection of files, one per event, each bearing as its name the unique
 
 paul@988    132 
.. identifier (`UID`) of the event, with each file containing the event data:
 
 paul@988    133 
{{{
 
 paul@988    134 
objects/UID
 
 paul@988    135 
}}}
 
 paul@988    136 
==
 
 paul@988    137 
`recurrences`
 
 paul@988    138 
|| A collection of directories, one per "parent" event, each bearing as its name
 
 paul@988    139 
.. the unique identifier (`UID`) of the event, with each directory containing a
 
 paul@988    140 
.. collection of files, one per event recurrence, each bearing as its name the
 
 paul@988    141 
.. normalised recurrence identifier (`RECURRENCE-ID`) of the recurrence, with each
 
 paul@988    142 
.. file containing the data of the event recurrence:
 
 paul@988    143 
{{{
 
 paul@988    144 
recurrences/UID/RECURRENCE-ID
 
 paul@988    145 
}}}
 
 paul@988    146 
==
 
 paul@988    147 
`requests`
 
 paul@988    148 
|| A list of records, one per line, each consisting of a unique identifier (`UID`),
 
 paul@988    149 
.. normalised recurrence identifier (`RECURRENCE-ID`) if appropriate, and
 
 paul@988    150 
.. (optionally) a scheduling method, indicating the availability of an incoming
 
 paul@988    151 
.. scheduling request for handling by a user
 
 paul@988    152 
}}}}