Jefferson Lab Electronic Logbook

The only two fields which are required to make a logentry are a logbook (--logbook or -l) and a title (--title or -t). Make sure to put quotation marks around your title. To send an entry to multiple logbooks, repeat the logbook option.

There are two ways to specify a body of a log entry via the command line. For the first way, the body option (--body or -b) is followed by the path to a text or html file whose contents will become the body of the log entry. The second way is to use a single dash ("-") following the option in which case the body will be read from Standard Input -- this is a convenient way to pipe the output of a program into a log entry. See the examples section below for illustrations of both usages.

By default, the body of a log entry is treated as plain text. If the body of your entry contains HTML markup and you want it to rendered as such to viewers of the logbook, you must specify the html flag (--html) on the command line.

Note: The character set encoding for non-ascii characters in the body will be assumed to be UTF-8.

The attachment option (--attachment or -a) allows you to include image or document files with a log entry. Multiple attachments may be included by repeating the attachment option. The total size of a single logentry when it is sent to the server must not exceed 64MB. Because the files you attach must be base-64-encoded by the software before transmission to the server and this encoding process increases their size by up to 15%, it is best to keep the total size of the original files you attach to 50MB or less per log entry.

You may attach captions for the files you attach by using the caption option (--caption or -c). You may specify multiple captions by repeating the option. The captions are assigned to the attachments by matching their order of occurrence. The first caption you specify will be assigned to the first attachment, the second to the second, and so on.

Unless you specify otherwise, the software will attempt to submit your entry immediately to the server. If the server can be contacted and returns a response, you will be given a message indicating either the lognumber that was assigned to the entry, or an error message indicating that it was rejected and why. Should the server not respond or fail to issue a valid response, the software will attempt to queue your entry to a file system location (/group/elogbooks/logentryq/new) for later processing attempts when the server is available again. In either the case of the entry being committed and assigned a lognumber or being successfully queued, the program will exit with a status code of 0, indicating success. If you want the program to return an error (non-zero exit status) if immediate submission fails without failing over to the queue mechanism, you must specify the noqueue option (--noqueue).

If for some reason you do not want your logentry submitted to the server at all, you can use the nosubmit flag (--nosubmit) and the entry will be neither submitted nor queued. The --nosubmit option is probably most typically useful when paired with the xml flag (--xml) which prints to standard output the encoded content of the logentry that would have been sent. The xml flag does not have to be used with the nosubmit flag: it will happily print to standard out the same contents that it will send to the server if used by itself.

In order for the program to submit an entry to the server for immediate insertion, it must have access to your logbook SSL client certificate. By default, it looks for this certificate in a file in your home directory named ".elogcert" (the dot at the front of the name makes it a hidden file on unix systems). If you wish to use a logbook client certificate from a different file, you must specify it using the certificate option (--cert). A user with a valid Jefferson Lab username and password can download his or her personal Logbook client certificate using the instructions on this page., however users of Accelerator (ACE) unix systems should find that their System Administrators have already placed their certificate in their home directory.

It is possible to use the command line tool with a compatible logbooks server other than logbooks.jlab.org by using the --config option to specify an alternate configuration file. Below is an example configuration file.