POV-Anywhere email communication module - Documentation

The POV-Anywhere email communication system is a separate module for exchanging data between the workspaces on different computers. The clients (the computers that render the jobs) have to register via email with a server (the computer that managers the projects and jobs) and the server distributes jobs in its local jobs directory to the idle clients which then render these in their local POV-Anywhere environment.

POV-Anywhere uses GPG so sign (and optionally encrypt) the email. In addition to gpg the following things are required:

• a correctly configured MTA (Mail transfer agent). This should not be a problem on a UNIX system. The incoming mail is read directly from a mbox file (either the standard /var/mail/username or a custom file generated by a mail program (so you can filter the mails). On Windows/Cygwin you can either install Exim which is available in the cygwin installer or use Ssmtp for sending the mails and a mail program that is capable of writing mbox files for reading.
• mutt is used for sending mails.
• UUDeview for decoding/encoding binaries in mails. On Windows make sure you get the command line version.
• A gpg key pair has to be generated for every computer. This key should be only used for POV-Anywhere since the passphrase is stored in clear text in the configuration file. The exchange of public keys can be done automatically.

How does it work?

The email communication module consists of two scripts:

• povany_email_client which runs on the client side (the computer that renders the jobs)
• povany_email_server which runs on the server side (the computer that distributes the jobs)

The server script looks for pending jobs in the local jobs directory that have not yet been started and distributes them to registered clients via email. It can be run together with local clients ( povany_client) that get their jobs via file system or other means of transport.

The clients script reads the incoming email and inserts the jobs into the local system so they can be rendered by a local client. It also searches for finished email jobs and sends the render results back to the server.

Right now the system does not support multiple servers for one client but you can circumvent this limitation by running several clients as several different users.

Installation

The install script includes a basic configuration of the email system. You might have to manually set up gpg afterwards. Operation without mail signing/encryption is not supported and some basic knowledge about gpg and public key cryptography is strongly recommended for safe operation.

Prior to installing you should take care of the following things:

• The required programs listed above are all installed.
• Email is correctly configured for the user who runs the POV-Anywhere email system. It is recommended to run it from a dedicated user account.

Running the email system

The email module scripts have to be run in addition to the standard POV-Anywhere scripts. Like these they can be run in loop mode or in single mode to be started by cron. So on the server side you will need to run both povany_pm and povany_email_server and on the client side povany_client and povany_email_client.

When the client has been correctly configured with the information of the server it should render for (email address and hostname) the rest will work automatically. Depending on the configuration you will have to confirm the client registration manually by replying the notification email. If registration is finished jobs inserted to the server workspace like described in the main documentation will be distributed to the clients and rendered automatically.

Description of the email related files

The information about the status of the email communication is stored in the POVANY_EMAIL_DIR directory which by default is $HOME/.povany/email/.

In this directory there might be the following files:

email_info

This file stores the position of the last email that has been read from the mbox file POVANY_EMAIL.

email_clients

This file only exists on the server side and contains a list of the known clients and their status. Each line in this file represents one clients and contains the following elements separated by space characters:

• The client hostname
• The client status, see the list of possible status codes.
• The client email address
• The GPG key-id of the client
• The time when the last communication with this client occurred.

register_info.hostname

For every client that registers such a file is written on the server that contains the information submitted in the registration mail.

register_gpg.hostname

This file contains the public gpg key of the client sent in the registration mail.

email_status

On the client this file contains the current status code.

email_servers

This file only exists on the client side and contains the information about the server the client is registered with. Currently only one server is supported. Each line in this file represents one server and contains the following elements separated by space characters:

• The server hostname
• The server status, see the list of possible status codes.
• The server email address
• The GPG key-id of the server

Status codes in the email related files

Some of the email related files described above contain status codes. These have the following meaning:

• 0: none (client removed)
• 1: registered, waiting for approval
• 2: registered and approved
• 3: idle, waiting for jobs
• 4: job offered
• 5: job accepted

Description of the email scripts

Here is a more detailed description of the way the client and server scripts operate. The communication process itself is described later on.

the email server povany_email_server

The purpose of this script is to answer to the clients' emails and to distribute render jobs to the clients.

When started without parameters it runs in loop mode, that means it runs in a loop until it is interrupted. The -c option can be used to turn this off. This feature is especially useful to run povany_email_server automatically with cron or similar tools.

Other available command line options are:
-h <hostname>: the hostname that is used to identify the node. (if not given this is the system hostname)
-v: verbose text output to stdout
-q: minimal text output to log
-s: stop mode - send a stop signal to all running email servers
-S: force stop mode - clear the stop and running signal files
-x: clear mode - remove all email related files and exit. This will remove the information about registered clients and any status information so it is a complete reset of the email system.
-m: message mode - issued a certain message to the email system and exits. This can be called while the script is also running in regular mode. The following command line option tells what message to send. The following messages are available:

• error: clear all email jobs with error status to be rendered again. This is useful when a job_error has been received and the problem has been fixed.
• clients_reset: Reset all registered clients by sending them a client_reset message. Use this if the system got completely screwed up.
• reset <client_hostname>: Reset client client_hostname by sending a client_reset message. If communication with a client got messed up somehow you can use this to start from scratch.

The email server first reads the new mail and acts according to it (see the communication description for details). Then offered jobs are checked for timeouts and new jobs available locally are distributed to the idle clients.

the email client povany_email_client

The purpose of this script is to answer to the server's mails and to insert jobs sent by the server into the local POVANY_JOBS_DIR directory so they can be rendered by the povany_client script.

When started without parameters it runs in loop mode, that means it runs in a loop until it is interrupted. The -c option can be used to turn this off. This feature is especially useful to run povany_email_client automatically with cron or similar tools.

Other available command line options are:
-h <hostname>: the hostname that is used to identify the node. (if not given this is the system hostname)
-v: verbose text output to stdout
-q: minimal text output to log
-s: stop mode - send a stop signal to all running email servers
-S: force stop mode - clear the stop and running signal files
-x: clear mode - remove all email related files and exit. This will remove the information about the client status and jobs so it is a complete reset of the email system.

When the client status is 0 the script sends a register mail to the server given in the configuration (POVANY_EMAIL_SERVER).

Then the script reads the new mail and acts according to it (see the communication description for details). When no jobs are currently running (either local jobs or email jobs) it then sends a client_idle mail to the server. If there are finished email jobs it sends a job_finished mail with the results and moves the local results to the POVANY_EMAIL_DIR directory for reference.

When the script receives a stop signal (by calling povany_email_client -s any currently running job is rejected (job_reject) and a client_busy mail is sent. This should be done prior to shutdown of the computer. To invoke this in non-loop mode use povany_email_client -s -c.

Details of the communication system

The information exchanged between server and client is in the subject lines and the body of the emails. The emails are signed with gpg and optionally encrypted to ensure secure communication.

The subject lines look like:

[povanywhere] hostname client_idle

[povanywhere] is an identifier that can be used to filter the mail. The next is the hostname of the machine that sends the mail. The third element is the message type.

The following types of messages are exchanged:

• register: client -> server, the clients signals that it wants to register with the server. If POVANY_EMAIL_REGISTER is set the registration is forwarded to this email address for approval, if not set the registration is done automatically. The client gpg key is included in the mail. To verify the gpg key is the task of the user.
• client_idle: client -> server, the clients signals that it is ready to accept jobs. The client needs to be registered before (status 2).
• client_busy: client -> server, the clients signals that it stops to be ready for jobs. This is sent when the client script is stopped.
• job_accept: client -> server, the clients signals that it accepts a job previously offered by the server. When the server receives this it changes the status of the client, otherwise the job offer will time out after POVANY_EMAIL_JOB_OFFER_TIMEOUT seconds.
• job_finished: client -> server, the clients signals that it has finished a job. The render result is included in the message. The status afterwards is set to 2 so the client needs to send a client_idle again.
• job_error: client -> server, the clients signals that a job resulted in an error. The POV-Ray output is included in the message so possible scene file errors can be identified. The client status is set to 3 (idle) afterwards so it can again receive jobs (which will lead to problems when the error is due to a client configuration problem. On the server the job is marked as error so it will not be rendered again.
• job_status: client -> server, the clients signals the status of a running job in regular intervals (POVANY_EMAIL_REPORT_INTERVAL seconds). The last two lines of the POV-Ray text output are included in the mail.
• job_reject: client -> server, the clients signals that it rejects a job offered by the server. This can happen both after the job has been accepted (job_accept) or before. The client status is set to 2 afterwards.
• register_confirm: server -> client, the server signals that the client registration has been approved. The client status is set to 2 then.
• registration: server -> POVANY_EMAIL_REGISTER, the server asks for a manual approval of a client registration when POVANY_EMAIL_REGISTER is set. The server accepts any reply to this mail as approval and there is no verification apart from an additional number code in the subject line (the current date/time) so POVANY_EMAIL_REGISTER should be a local mail address for safety reasons.
• job_offer: server -> client, the server offers a job to a client, the required files are included in the mail. When the job offer is correct and the client is ready to render it will send a job_accept. Job offers time out after POVANY_EMAIL_JOB_OFFER_TIMEOUT seconds.
• job_withdraw: server -> client, the server withdraws a job from the client, the client will no more send a job_finished then once the job has been finished. Job interruption has not yet been implemented.
• register_wait_approval: server -> client, the server signals that the client registration has been received and is waiting for manual approval. This right now is only a confirmation mail and has no real effect.
• client_idle_confirm, job_accept_confirm, job_reject_confirm, job_error_confirm, job_finished_confirm: server -> client. These right now are only confirmation mails and have no real effect.
• job_status_unknown_job, client_idle_reject_not_registered, client_idle_reject_unknown, client_idle_reject_wrong_gpg, client_idle_reject_wrong_status, job_accept_reject_not_registered, job_accept_reject_not_offered, job_accept_reject_unknown, job_accept_reject_wrong_gpg, job_finished_reject_not_registered, job_finished_reject_not_offered, job_finished_reject_unknown, job_finished_reject_wrong_gpg, job_finished_reject_no_data, job_reject_unknown_job, job_reject_reject_unknown, job_reject_reject_wrong_gpg, job_error_unknown_job, job_error_reject_unknown, job_error_reject_wrong_gpg: server -> client. These are error messages indicating something went wrong. None of these errors is handled automatically at the moment.
• client_reset: server -> client, this message completely resets the clients status, this is most useful when the system got screwed up and you want to start from scratch.