Meqaris - Administrator's manual

The command line

Meqaris is a command-line-driven application. You configure the system by issuing commands on the command-line and use the application by providing parameters on the command line and e-mail input through the standard input.

To get simple help on the command line, run

	meqaris --help

Meqaris uses an INI file to hold the primary configuration, like database access settings, and a PostgreSQL database to hold the meeting resources (rooms and equipment), the booked meetings/events and some of the configuration.

To override the default configuration file path, use the --conf parameter, passing the path to the configuration file:

	meqaris --conf /path/to/meqaris.ini

You can pass this parameter to each of the commands Meqaris supports.

To check if the configuration file is correct, you can run the

	meqaris --status

command. It should eventually display something similar to:

	Configuration file '/path/to/meqaris.ini': OK
	Data directory: '/path/to/meqaris/data': OK
	Database connection: OK
	Database version: OK

On ANSI-enabled terminals, the statuses will be shown in colour. You can set the environment variable ANSI_COLORS_DISABLED to disable this, e.g.

	ANSI_COLORS_DISABLED=1 meqaris --status

Each database modification action causes Meqaris to check if the database version is the version expected by the application. If not, the required database upgrade scripts are run. You can also perform the database upgrade manually by running the

	meqaris --upgrade-db

command and checking the status afterwards.

To begin booking meeting resources, you need to create those resources in the Meqaris system. To do that, use the --create parameter (and remember to properly quote or escape the parameters):

	meqaris --create 'Room 100' --description 'Room 100, first floor'
		--email 'room100@yourdomain'

	meqaris --create 'Projector HD 1' --description 'Mobile HD projector'
		--email 'hdproj1@yourdomain'

	meqaris --create 'Teleconference set X-2'
		--description 'Teleconference set: TV + speaker + microphone'
		--email 'telco_set_x2@yourdomain'

The name (after the --create parameter) is required. The description is optional and is just for users. The e-mail address is also required, otherwise the resource wouldn't "know" that the invitation is meant for it.

If you plan to have real operating system-level users for your resources, you can still bind them to Meqaris using the .forward file for Postfix, or the .procmailrc file for Procmail that should work for all incoming mail, to pass the mail to the Meqaris system.

Once resources are added, you can start booking them - just send your invitations with the resources' configured e-mail addresses just like you would send invitations to other meeting participants. See the User's manual on how to do that.

To later modify the resource, if needed, use the --update parameter, passing the name of the resource to modify and the new values:

	meqaris --update 'Teleconference set X-2'
		--name 'Teleconference set X-3'
		--description 'Teleconference set: HDTV + 2 speakers + mic'
		--email 'telco_set_x3@yourdomain'

To temporarily disable a resource from being booked, run

	meqaris --disable 'Room 100'

To re-enable a temporarily-disabled resource to be allowed to be booked again, run

	meqaris --enable 'Room 100'

To permanently delete a resource, run

	meqaris --delete 'Room 100'

After this, you need to re-create the resource in order to use it again. Resources which have meetings booked (even past) cannot be deleted right now.

To modify a setting in the Meqaris database, run

	meqaris --set <name> --value <new_value>

e.g.

	meqaris --set mail_server --value 127.0.0.1

To set the value to NULL (which is NOT the same as an empty string), run just

	meqaris --set <name>

To use CalDAV with Meqaris, you begin by adding CalDAV servers (calendar locations). To do that, use the --add-caldav-server parameter (and remember to properly quote or escape the parameters):

	meqaris --add-caldav-server 'http://some-url/some/calendar/location'
		--name 'Some CalDAV server'

The URL (after the --add-caldav-server parameter) and name are required. If the server requires authentication, you can pass the --user, --password and --realm (if needed) parameters:

	meqaris --add-caldav-server 'http://some-url'
		--name 'Some CalDAV server'
		--user some-user --password users-password

To later modify the server, if needed, use the --update-caldav-server parameter, passing the name of the server to modify and the new values:

	meqaris --update-caldav-server 'CalDAV1'
		--name 'CalDAV2'
		--url 'http://caldav2/some/calendar/location'
		--user caldav2-user
		--password 'caldav2-password'
		--realm caldav2

Once CalDAV servers are added, you can assign resources to them so that Meqaris knows which servers to notify when an invitation for a particular resource is processed.

To assign an existing resource to a CalDAV server, use the --add-caldav-resource parameter:

	meqaris --add-caldav-resource 'Some CalDAV server'
		--name 'Resource name'

You can assign multiple CalDAV servers to one resource and multiple resources to one CalDAV server.

To un-assign an existing resource from a CalDAV server, use the --delete-caldav-resource parameter:

	meqaris --delete-caldav-resource 'Some CalDAV server'
		--name 'Resource name'

To delete a CalDAV server and un-assign all existing resources from it, use the --delete-caldav-server parameter:

	meqaris --delete-caldav-server 'Some CalDAV server'

To completely delete the Meqaris data and database structures in the database, run

	meqaris --destroy-db

The database structures will be re-created by Meqaris upon receiving the first invitation or the first command that modifies the database (except --destroy-db), which includes running

	meqaris --upgrade-db

Finally,

	meqaris --license
	meqaris --licence

displays Meqaris license information, and

	meqaris --version

displays Meqaris version information.

You can use the provided scripts/mkdump.sh script to make a database backup, which can later be restored using the scripts/restoredb.sh script.

The configuration file

Meqaris uses an INI file to hold the primary configuration. The file's default syntax is

	[meqaris]
	dbtype=postgresql
	datadir=/var/lib/meqaris
	log4perl_config_location=/var/lib/meqaris/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

The dbtype parameter in the [meqaris] section holds the type of the database and the name of the database settings' section.

The datadir parameter in the [meqaris] section tells where the Meqaris' data files (SQL files) are.

The log4perl_config_location parameter in the [meqaris] section gives the location of the configuration file for Log::Log4perl.

The lock_dir parameter in the [meqaris] section gives the location of the directory to put lock files in. Lock files prevent two or more Meqaris processes from accessing crucial code at the same time, to avoid e.g. running two database upgrades at the same time (one of which is bound to fail).
The directory must be writable by your mail server's user (and its parent directories must be traversable by your mail server's user).

The username parameter in the [postgresql] section gives the database username for the database.

The password parameter in the [postgresql] section gives the database password for the provided username for the database.

The dbname parameter in the [postgresql] section gives the name of the database to connect to.

The host parameter in the [postgresql] section gives the hostname or an IP address of the database to connect to. It can also be the path to the directory containing the local PostgreSQL socket for local connections, e.g. /run/postgresql/ in some versions, /tmp in other.

The port parameter in the [postgresql] section gives the port number of the database to connect to.

The connect_timeout parameter in the [postgresql] section specifies the database connection timeout, in seconds.

Configuration in the database

Meqaris uses also a database table to hold some of its configuration.

To modify a setting in the Meqaris database, use the --set command, along with --value (if needed), as described above.

Currently, the following user-modifiable parameters are supported:

mail_server: The address of the mail server to use (the default value is NULL meaning to use the default mail server guessing by the Mail::Internet Perl module).
The setting is used only when mail_sending_method is NOT set to mail_command.
mail_server_port: The port on the mail server to use (the default value is NULL meaning to use the default mail server port by the Mail::Internet Perl module).
The setting is used only when mail_sending_method is NOT set to mail_command.
mail_sending_method: The method to use to send mail. The default value is NULL meaning to use the default method used by the Mail::Internet Perl module. Other possible values: the word default, Mail::Internet and mail_command.
mail_command: The command to pipe the outgoing mail replies into instead of sending the replies using a mail server. The default value is NULL, which silently drops the responses.
The setting is used only when mail_sending_method = "mail_command".
To gather replies in a file (on Linux), use something like
```
	cat >> /path/to/your_file
```
and make sure that the file is writable (and all the directories on the path are traversable) by the mail server's user.
To send replies to standard output, use just
```
	cat
```
Meqaris will substitute the following strings in the command you set in the mail_command parameter:
- %from% gets substituted by the value of the From header in the response (which is the resource's name and e-mail address),
- %to% gets substituted by the value of the To header in the response (which usually is the meeting Organizer),
- %cc% gets substituted by the value of the CC header in the response (which usually is the address of the sender of the invitation, which can be different from the Organizer),
- %subject% gets substituted by the subject of the response e-mail,
- %action% gets substituted by the action Meqaris took - Accepted or Declined.
This way, you can pipe your responses to another mailing mechanism, e.g.:
```
	meqaris --set mail_command --value 'some_mail_program --from "%from%" --to "%to%"'
	meqaris --set mail_sending_method --value mail_command
```
parser_tmp_dir: The path to a temporary directory for files with message parts. Default = /tmp. NULL means use the default.
reply_detail_level: An integer saying how much detailed will the replies be. 0 = the default.

Troubleshooting

If you get errors similar to:
```
	Can't locate X in @INC (you may need to install the X module)
```
then make sure that all the required Perl modules and their dependencies are installed. If you installed them in non-standard locations, you may need to run Meqaris by using the perl command and pass the required paths in the -I parameter, e.g.
```
    perl -I /path/to/perl/modules /path/to/meqaris --conf /path/to/meqaris.ini
```

If the --status command displays something like:

	Configuration file '/path/to/meqaris.ini': OK
	Data directory: '/path/to/meqaris/data': OK
	Database connection: ERROR: cannot connect: connection to server at
	 "127.0.0.1", port 5432 failed: Connection refused
         Is the server running on that host and accepting TCP/IP connections?

then check:

if the database connection parameters in the INI file are correct,
if the database is actually running.

If you send e-mail invitation to Meqaris, but don't get a response, then:
- check your mail server configuration if the invitations are properly passed to Meqaris,
- check your mail server logs if the invitations were in fact sent to Meqaris
- save your e-mail to a text file, send it to Meqaris by hand:
```
	meqaris --conf /path/to/meqaris.ini < your_mail.eml
```
  and examine the output,
- check the Meqaris' logs for more information. Increase the logging level if necessary.
Excluding more than one date in CalDAV doesn't work.
Unfortunately, even though Meqaris tries to keep all EXDATE values in one line, at least Cyrus IMAP translates them into multiple, separate entries.
Unfortunately, despite the RFC saying that multiple EXDATE entries are allowed, not all clients support this.