imip-agent

Annotated docs/wiki/GettingStarted

1089:54e1af14f1a2 1112:692c89e110bb
1053:068aa85f0c45
1006:ead8eeb668ff
2016-02-08 Paul Boddie file changeset files shortlog Made the retraction operation a complete transaction. Tidied up the locking and unlocking function application.
paul@955 1 
= Getting Started =
paul@955 2 
 
 paul@955      3 
To get imip-agent running on your own system you will need the following:
 
 paul@955      4 
 
 paul@955      5 
 * The ability to install software and to configure the system
 
 paul@955      6 
 * A working mail configuration
 
 paul@955      7 
 
 paul@955      8 
It is possible to [[../Testing|test the agent programs]] without these
 
 paul@955      9 
abilities, but any difficulties in getting the software to work will be
 
 paul@955     10 
compounded by any problem or deficiency in either of these areas.
 
 paul@955     11 
 
 paul@1006     12 
<<TableOfContents(2,2)>>
 
 paul@1006     13 
 
 paul@1006     14 
== Obtaining the Software ==
 
 paul@1006     15 
 
 paul@1006     16 
To get started, the imip-agent software must be [[../Downloads|downloaded]]
 
 paul@1006     17 
and any [[../Prerequisites|prerequisites]] installed, the latter being
 
 paul@1006     18 
software that imip-agent needs to work with. The choice of prerequisites
 
 paul@1006     19 
will influence some of the activities described below.
 
 paul@1006     20 
 
 paul@955     21 
== Configuring System Users ==
 
 paul@955     22 
 
 paul@955     23 
The [[../SystemUsers|system users guide]] indicates the requirements for
 
 paul@955     24 
system user and group configuration.
 
 paul@955     25 
 
 paul@955     26 
If you are comfortable configuring your mail system, you may decide to
 
 paul@955     27 
choose the [[../MailIntegration/LocalSMTP|local SMTP delivery]] approach.
 
 paul@955     28 
 
 paul@955     29 
If you already use mail storage solutions that employ LMTP, you may decide
 
 paul@955     30 
to choose the [[../MailIntegration/LMTP|LMTP delivery]] approach.
 
 paul@955     31 
 
 paul@955     32 
== Installing the Software ==
 
 paul@955     33 
 
 paul@955     34 
Ideally, an operating system distribution package should be used to
 
 paul@955     35 
install the software. As a result, the software should already be suitably
 
 paul@955     36 
integrated and configured and guidance will be available to get everything
 
 paul@955     37 
working.
 
 paul@955     38 
 
 paul@955     39 
 1. In the absence of a suitable system package, the installation locations
 
 paul@955     40 
 and system user details must first be configured, as described above.
 
 paul@955     41 
 
 paul@955     42 
 1. Then, the `tools/install.sh` script should install the software in
 
 paul@955     43 
 appropriate locations. You may need to be `root` or use `sudo` to
 
 paul@955     44 
 successfully use this script.
 
 paul@955     45 
 
 paul@961     46 
{{{
 
 paul@961     47 
tools/install.sh
 
 paul@961     48 
}}}
 
 paul@961     49 
 
 paul@955     50 
See the [[../Prerequisites|prerequisites]] for other software that will be
 
 paul@955     51 
required for the software to function. 
 
 paul@955     52 
 
 paul@955     53 
== Initialising the Software ==
 
 paul@955     54 
 
 paul@955     55 
Once a suitable system user has been chosen, stored and published data is then
 
 paul@955     56 
initialised using the `tools/init.sh` script. The script employs the setgid
 
 paul@955     57 
flag on the directories initialised for stored and published data so that new
 
 paul@955     58 
files and directories have the appropriate group associated with them.
 
 paul@955     59 
 
 paul@955     60 
It should be possible to omit all arguments to the `init.sh` script, but it is
 
 paul@955     61 
also worth reading the help message:
 
 paul@955     62 
 
 paul@955     63 
{{{
 
 paul@955     64 
tools/init.sh --help
 
 paul@955     65 
}}}
 
 paul@955     66 
 
 paul@1006     67 
Fixing ownership can be done using the `tools/fix.sh` script, as described in
 
 paul@1006     68 
the [[../Administration|administration guide]] in case some form of modification
 
 paul@1006     69 
has altered the ownership or membership of the created files and directories.
 
 paul@955     70 
 
 paul@1006     71 
== Integrating with Other Software ==
 
 paul@955     72 
 
 paul@1006     73 
The `conf` directory in the imip-agent source code distribution contains
 
 paul@1006     74 
subdirectories for different systems:
 
 paul@955     75 
 
 paul@961     76 
{{{#!table
 
 paul@961     77 
'''Directory''' || '''Description''' || '''Guide'''
 
 paul@961     78 
==
 
 paul@961     79 
`apache`
 
 paul@961     80 
|| Apache 2 site configuration for publishing resources
 
 paul@961     81 
|| [[../WebServerIntegration|Web Server Integration]]
 
 paul@961     82 
==
 
 paul@961     83 
`cron`
 
 paul@961     84 
|| Cron command scheduling for free/busy updates
 
 paul@961     85 
|| [[../CronIntegration|Cron Task Scheduler Integration]]
 
 paul@961     86 
==
 
 paul@961     87 
`exim`
 
 paul@961     88 
|| Exim 4 routing and transport configuration
 
 paul@988     89 
|| [[../MailIntegration|E-Mail Integration]] and
 
 paul@988     90 
.. [[../MailboxIntegration|Mailbox Integration]]
 
 paul@961     91 
==
 
 paul@961     92 
`ldap`
 
 paul@961     93 
|| Some LDAP-related resources
 
 paul@961     94 
||
 
 paul@961     95 
==
 
 paul@961     96 
`postfix`
 
 paul@961     97 
|| Postfix routing and transport configuration
 
 paul@988     98 
|| [[../MailIntegration|E-Mail Integration]] and
 
 paul@988     99 
.. [[../MailboxIntegration|Mailbox Integration]]
 
 paul@961    100 
}}}
 
 paul@955    101 
 
 paul@961    102 
== Configuring the Software ==
 
 paul@955    103 
 
 paul@961    104 
The behaviour of the imip-agent software itself can be configured using
 
 paul@961    105 
mechanisms described in the [[../Configuration|configuration guide]].
 
 paul@988    106 
 
 paul@1006    107 
== Administering the Software ==
 
 paul@1006    108 
 
 paul@1006    109 
With the basic configuration performed, all that remains is to perform
 
 paul@1006    110 
any necessary [[../Administration|administration tasks]] to set the
 
 paul@1006    111 
software up for certain kinds of users or participants.
 
 paul@1006    112 
 
 paul@988    113 
== Using the Software ==
 
 paul@988    114 
 
 paul@1006    115 
With configuration and administration performed, it should be possible
 
 paul@1006    116 
to get started using the software. See the [[../Usage|usage guide]]
 
 paul@1006    117 
for details.