Meqaris - Installation instructions

Initial steps - most are one-time

  1. Install Perl, along with the following modules (available from CPAN / metacpan):

    with all their dependencies (the list may include but not be limited to: Module::Install, Test::NoWarnings, Test::LongString, Class::Accessor, DateTime, DateTime::TimeZone, Moo, Set::Infinite, Test::Requires, Class::Accessor-Chained, Class::ReturnValue, DateTime::Event::ICal, DateTime::Event::Recurrence, Params::Validate, Text::vFile::asData).

    Actual mail sending requires the Net::SMTP and Net::Domain Perl modules,

  2. A PostgreSQL database server, version 9.2 or newer, must be running.
    On a Linux system, you would do one of:
  3. A mail (SMTP) server must be running.
    On a Linux system with Postfix, you would do one of (as root): 
    	systemctl start postfix
    	service postfix start
  4. A database user must be created within the database server.
    With PostgreSQL, you would login to the system as the database user postgres and run: 
    	createuser -P meqaris
    It's advised for the user to be the owner of the database that will be created.
    It's easiest to create a user with the same name as the system user name and create the database as the system user.

  5. A logical database must be created within the database server.
    With PostgreSQL, you would login to the system as the database user postgres and run: 
    	createdb -O meqaris meqaris
    (for the specified user to be the database owner)
  6. NOTE for older database versions
    On PostgreSQL versions older than 13.0, you may need to perform one additional step before running Meqaris - install the btree_gist extension manually in the Meqaris database you've just created. Meqaris cannot do this, because only the database superuser (usually postgres) is allowed to do it. Substitute the hostname and port number where necessary and run this command to install the extension: 
    	psql -U postgres -h hostname -p port_number -d meqaris -c 'create extension if not exists btree_gist;'
  7. Database access rules must be created within the database server, unless you wish to leave the default rules.
    With PostgreSQL, you would do (as the database user postgres or root): 
    	cp /var/lib/pgsql/data/pg_hba.conf /var/lib/pgsql/data/pg_hba.conf-backup
	echo local meqaris meqaris scram-sha-256 >> /var/lib/pgsql/data/pg_hba.conf
	echo host all all 127.0.0.1/32 scram-sha-256 >> /var/lib/pgsql/data/pg_hba.conf
    (Note the double ">>" - it's CRUCIAL to use double ">>", a single ">" would OVERWRITE the target file).
    With older PostgreSQL versions, replace scram-sha-256 with md5.
    If you'll need to access the database from another computer:
  8. After changing the access rules for the database server, restart it.
    With Linux with PostgreSQL, you would do one of:

Installation

  1. Choose 4 paths:
  2. Copy bin/meqaris to BINDIR,
  3. Edit config/meqaris.ini to match your directories and database settings (see below),
  4. Edit config/meqaris-log4perl.cfg and choose your log file's location,
  5. Copy the whole sql directory and the config/meqaris-log4perl.cfg file to DATADIR/meqaris. The DATADIR/meqaris directory must be writable for your mail server,
  6. Copy config/meqaris.ini to CONFDIR,
  7. Copy config/meqaris.logrotate to a directory expected to contain logrotate configuration files (like CONFDIR/logrotate.d),
  8. Copy the manual to a place suitable for documentation, like /usr/share/doc.

Alternatively, if you have the make program and some common Linux utilities, you can run make install, passing the target directories. Examples:

	make install BINDIR=/usr/bin CONFDIR=/etc DATADIR=/var/lib DOCDIR=/usr/share/doc MANDIR=/usr/share/man
	make install BINDIR=$HOME/tools/meqaris/bin \
		CONFDIR=$HOME/tools/meqaris/etc \
		DATADIR=$HOME/tools/meqaris/data \
		DOCDIR=$HOME/tools/meqaris/doc \
		MANDIR=$HOME/tools/meqaris/man

All the above directories and their parent directories must be reachable by your mail server.

The log file (/var/log/meqaris.log by default) must be created writable for your mail server. Alternatively, the directory which would contain it must be writable by your mail server.

The necessary database structures will be automatically created by the application itself while operating, but to avoid concurrent database upgrades (all of which except one would fail), it is recommended to run the database installation/upgrade scripts manually by calling 

	meqaris --upgrade-db

Meqaris configuration

You need to edit the meqaris.ini file to set the proper values for database access in the [postgresql] section and your chosen application data files' directory in the [meqaris] section under: 

	[meqaris]
	dbtype=postgresql
	datadir=/path/to/meqaris/data
	log4perl_config_location=/path/to/meqaris/data/meqaris-log4perl.cfg
	lock_dir=/var/lock

	[postgresql]
	username=meqaris
	password=meqaris-pass
	dbname=meqaris
	host=127.0.0.1
	port=5432
	connect_timeout=30

Make sure that the datadir directory, the log4perl_config_location file and the actual log file have the right permissions so that Meqaris, which will run under the mail server's privileges, has the right access to all of those locations.

Mail server configuration

Consult your mail server manual about how to make it send e-mails addressed to your resources (rooms, etc.) to the Meqaris script and how to accept the replies.

For Postfix, you can edit the /etc/postfix/aliases file and add the right command there. It must begin with the "pipe" symbol - "|" - so that the Meqaris script receives the mail on the so-called "standard input".

Assuming you want a "room 1" alias and everything is installed in the default paths, the simplest entry in the /etc/postfix/aliases file could be: 

	room1: |"meqaris"

Assuming you want a "room 1" alias and everything is installed NOT in the default paths, the most complicated entry in the /etc/postfix/aliases file could be: 

	room1: |"SMTPHOSTS=smtp-host-name /path/to/perl -I /path/to/perl/modules /path/to/meqaris --conf /path/to/meqaris.ini"

By using just the cat command as the output instead of sending e-mails (see the Manual for administrators), you can pipe the reply from Meqaris to other commands, including the mail server's own commands and since you know e.g. the alias which is being processed, you can add it to the other command's options, like so: 

	room1: |"meqaris"| some-other-command "room1"

Meqaris itself can also pipe the reply to another program when you set the mail_command and mail_sending_method parameters. Read the Administrator's manual for more details.

For a password-less, local-only mail submission, add this to your /etc/postfix/main.cf file: 

	inet_interfaces = localhost
	inet_protocols = all
	mynetworks_style = host
	smtpd_relay_restrictions = permit_mynetworks permit_sasl_authenticated reject_unauth_destination
	smtp_sasl_auth_enable = no
	smtp_tls_security_level =
	smtpd_sasl_auth_enable = no
	smtpd_tls_security_level =

Restart the Postfix server (or reload its configuration) afterwards.

CalDAV configuration

Consult your CalDAV server manual about how to create users and their calendars.

For Cyrus IMAP, you add users and passwords to the authentication mechanism and then create mailboxes in Cyrus IMAP.

Start with reading the Cyrus IMAP installation procedure.

After Cyrus IMAP installation, begin by starting the authentication mechanism (as root): 

	systemctl start saslauthd

or

	saslauthd -a sasldb start

Assuming you want a "room1" alias and everything is installed in the default paths, you add the user and password (as root): 

	echo 'room1s-password' | saslpasswd2 -p -c room1

Next, make sure the httpmodules line in your imapd.conf file contains caldav, like this: 

	httpmodules: caldav carddav

Check that the SERVICES section in your cyrus.conf file contains at least an enabled http service (it can also contain https): 

	SERVICES {
		...
		http          cmd="httpd" listen="http" prefork=0

Non-standard paths require passing the location of the imapd.conf file: 

	SERVICES {
		...
		http          cmd="httpd -C /path/to/imapd.conf" listen="http" prefork=0

Start Cyrus IMAP by starting the appropriate service or by running just (as root): 

	master -d
(if you installed locally)

You may need to pass paths to the configuration files: 

	/path/to/master -C /path/to/imapd.conf -M /path/to/cyrus.conf -d

To create a user mailbox for the user "room1" in Cyrus IMAP, assuming default paths and that the Cyrus IMAP administration user is called cyrus (with the password "cyrus"), run (as root): 

	echo 'createmailbox user/room1@localhost' | cyradm -u cyrus -w cyrus localhost

The address of the user's calendar is http://localhost/dav/principals/user/room1@localhost/, which gets translated into http://localhost/dav/calendars/user/room1/Default/.
Unless configured otherwise, the calendar requires authentication - you can use the username and password passed to the saslpasswd2 command earlier, or use some other IMAP user.
After first access to the URL, the calendar should be created.
This is the URL you will be passing to Meqaris when creating a CalDAV server.

You can use your browser to create, manage and download the user's calendar by visiting http://localhost/dav/calendars/user/room1/ and authenticating as the user.

More information can be found on the Cyrus IMAP CalDAV page.

Uninstallation

To uninstall, if needed:

Alternatively, if you have the make program and some common Linux utilities, you can run make uninstall, passing the same directories that were used during installation. Examples: 

	make uninstall BINDIR=/usr/bin CONFDIR=/etc DATADIR=/var/lib \
		DOCDIR=/usr/share/doc MANDIR=/usr/share/man
	make uninstall BINDIR=$HOME/tools/meqaris/bin \
		CONFDIR=$HOME/tools/meqaris/etc \
		DATADIR=$HOME/tools/meqaris/data \
		DOCDIR=$HOME/tools/meqaris/doc \
		MANDIR=$HOME/tools/meqaris/man