6. Configuration

Picroscopy reads its configuration files from the following locations, in the order presented (i.e. values found in later files override values found in earlier files):

  1. /etc/picroscopy.ini
  2. /usr/local/etc/picroscopy.ini
  3. ~/.picroscopy.ini (where ~ represents the current user’s home directory)

You can manually specify a configuration to load with the picroscopy -c option. In this case, the manually specified configuration will be read last, ensuring its values take precedence over any values read from the files listed above.

Picroscopy’s configuration format is based on the familiar INI-file format. The configuration file must have a [picroscopy] section (Picroscopy will ignore other sections within the file), which contains key=value entries on separate lines. Key names are case insensitive. Key names and values may have leading or trailing whitespace which will be ignored. Blank lines are ignored, as are comments which are whole lines prefixed with either # or ;.

An example configuration file is shown below:

[picroscopy]

; Blank lines are ignored, as is this line, which is a comment
# This is also a comment

; Spaces surrounding keys and values are ignored...
  listen = 127.0.0.1:8000
clients = 127.0.0.0/8

; Case is ignored for key names
IMAGES_DIR=/tmp/picroscopy_images
Thumbs_Dir=/tmp/picroscopy_thumbs

The key names which can appear in the configuration file are the same as the available “long-style” command line options, with the caveat that leading dashes are stripped and any dashes within the option are replaced by underscore. Hence the picroscopy --images-dir option becomes the images_dir key within the configuration file.

6.1. Example Configurations

Two example configuration files are shipped with Picroscopy’s source: picroscopy.ini which contains a configuration suitable for normal usage (all defaults), and development.ini which contains values suitable for development purposes. It is recommended that picroscopy.ini be placed in a suitable location where Picroscopy can find it automatically, e.g. /etc or /usr/local/etc.

6.2. Keys

The remainder of this document is a description of the available keys in a Picroscopy configuration file.

6.2.1. log_file

Log displayed messages to the given filename. The log file will be appended to if it already exists. Its format will include the timestamp that the message was displayed, and the severity of the message. Log files include all messages regardless of the verbosity of console output.

6.2.2. pdb

If true, run under PuDB (if available) or PDB. This launches Picroscopy within a Python debugger for development purposes.

6.2.3. listen

The address and port of the interface that Picroscopy will listen on. Defaults to 0.0.0.0:80 (when running as root) or 0.0.0.0:8000 (when running as a non-root user). 0.0.0.0 address means “listen on all available network interfaces”.

6.2.4. clients

The network that clients must belong to. Clients that do not belong to the specified network will be denied access to Picroscopy. Defaults to all valid addresses (0.0.0.0/0).

6.2.5. images_dir

The directory in which Picroscopy will store images captured by the camera. If not specified, this defaults to a temporary directory which is destroyed upon exit. If the specified directory does not exist, it will be created.

6.2.6. thumbs_dir

The directory in which Picroscopy will store thumbnails generated from the images taken by the camera. If not specified, defaults to a temporary directory which is destroyed upon exit. If the specified directory does not exist, it will be created. The thumbnails directory must be different to the images directory.

6.2.7. thumbs_size

The maximum size for generated thumbnails (the actual size may be smaller due to aspect ratio preservation). Defaults to 320 pixels square.

6.2.8. email_from

The address which Picroscopy will use as a From: address when sending e-mail. The default is picroscopy with no specific host. If a host is not specified, the configuration of the sending SMTP server will determine the host associated with the address.

6.2.9. sendmail

Use the specified sendmail binary to send e-mail. This is the preferred option for sending e-mail as it (usually) gracefully handles the case where the target SMTP server is unavailable. Defaults to /usr/sbin/sendmail.

6.2.10. smtp_server

Use the specified SMTP smarthost to send e-mail. This should only be used if you do not wish to configure a local sendmail binary. If this option is specified, it will always override any sendmail specification.