Shelf Server Configuration File

Many aspects of ShelfServer's behavior can be configured via its configuration file, shelfserver.properties. By default, this file is read from <current user's home>/.shelfserver/. When running ShelfServer as a "headless" service, it may be necessary to specify the path to this file as a startup parameter to ShelfServer. See ShelfServerParameters for info.

The shelfserver.properties file is a standard text-based Java properties file and follows all the usual rules. The file is essentially a set of name=value pairs, one per line. The file is read and rewritten each time ShelfServer runs, so comments are stripped each time.

Supported config keys currently include:

• shelf.name.# & shelf.path.# - These two items work as a pair to specify the display name and the complete filesystem path to each folder made available to iPhone clients. The # part should be an ascending integer, and the name and path with the same number are considered a pair. Numbers must start with one and be contiguous. The number is a base ten integer, and there is no set maximum.

• shelf.password - the password required to connect to this server. Just plain-text. In order to use no password, set this value to "PUBLIC" (all caps, remove the quotes).

• shelf.networkport - The network port on which ShelfServer will listen. If not set, an available port above 1024 will be randomly selected. The server will be advertised using ZeroConf? (Bonjour, mDNS, etc.).

• shelf.servername - free text name of the ShelfServer which will be displayed in the iPhone interface when the user connects. Avoid using any XML significant characters. Default is based on the system's "main" hostname which may or may not be sensible.

• shelf.hostname - The hostname or IP Address on which ShelfServer can be contacted. This value is included in the XML metadata sent to the client, and the client will use this value to connect back to the server on all subsequent connections. In most cases, this setting should NOT be included. The client will connect to the server on either the Bonjour-advertised IP/port or on whatever manually entered name it used to find the server in the first place. Setting this may be necessary if the server is to be accessed through a firewall or if the name/ip detected as the "main" interface isn't the one actually used by the server. ShelfServer has code which attempts to detect the listen IP/port when run in Tomcat, but this may or may not work in other application servers.

• shelf.userconfigclass - Specifies a Java class name used to implement custom user authentication. Contact support for more info if you require such functionality.

• shelf.servermode - Set this to true when running in a Java application server such as Tomcat.

• shelf.optionalpassword - The server password is optional, that is users should be allowed in without a password, but some content may not be available. Only useful with shelf.userconfigclass.

• shelf.request.log - Set to true to keep extremely verbose request logs. This is only good for debugging or burning disk space.

• shelf.compression.enabled - Set to false to disable gzip compression of server responses. Should be left enabled (the default) unless it causes problems with firewalls or proxies (which is rare).

• shelf.search.metadata - Set to true to search file metadata as well as file/path names when searching the shelf. This is disabled by default as it usually has a significant performance impact.

• plucker.conversion - One of "ALL", "SOME", or "NONE" (all caps, without the quotes). Controls which files are converted to Plucker format when downloaded. ALL does every file. SOME does formats which routinely have problems when not converted. NONE still converts certain multi-file formats (ePub for example) which contain multiple pages and images which aren't supported in their native format.

• plucker.split.tags - List (comma separated) of HTML tags which should be preceded by a page break when files are converted to Plucker format. Can be useful for splitting files on chapters based on a HR or other consistent delimiter tag.

• cleansing.fixhardbreaks - Set to try to attempt to remove superfluous line breaks from plain-text files. This can improve formatting for files that were originally sent via Usenet or email which were forcibly wrapped to some fixed width. It destroys formatting on poetry, song lyrics, or other texts which have no discernible paragraph structure.