Main Page | About | Installing the server | Installing the client | Using the server | Using the client |

About Butler

There are two parts to Butler: butler (lower case b) is a web app server companion to the desktop program Pooter; Butler, (capital B) is a Pooter module and client program to the server.

The server runs in a java app server, either on an internet connected machine or on a local network. It should be OS independant, but at the moment only the tomcat app server is supported. Contact me if you'd like to use it with an alternative to tomcat. It displays your Calendar, Contacts and Notes data in a browser. It also provides an easy way to sync your data between two machines on the same network and can also provide help monitoring the performance of the server machine. It bundles several additional technologies that it depends on, notably the stripes web framework, the groovy programming language and the jquery javascript library.

The client archives your data into a zip file, authenticates with the server and uploads. It can also download the archive and extract it to update your local data files.

Installing the server

Download and decompress the zip archive and copy the butler.war file to the tomcat webapps directory. If you're testing on the local machine with a standard tomcat setup, a login page is displayed at http://localhost:8080/butler. If you installed earlier versions of butler any config directory in your tomcat install (.butler or butler) must be removed first. If you intend to install the server on a machine outside your own local network, ie traffic is to pass over the internet, you should use the https protocol to ensure that user name and passwords cannot be sniffed. I'd recommend linking your tomcat with apache, which makes it easy to use a free letsencrypt certificate. This howto deals with such a setup and alternatives; it should be helpful reading although it's main purpose is not a butler setup.

Installing the client

Copy the Butler.jar file into your Pooter module directory and restart Pooter. If you installed an earlier version (prior to 2.0) you must delete first delete the butler.cfg file in the Pooter data directory. Settings in the Preference tab are those needed to communicate with a server running on the local machine with the default login credentials.

Using the server

The default credentials are Login Name admin and Password password; once you login for the first time you will be taken to the config page. If you're running over the public internet you should change these and also reflect these changes in the client program . The default page setting determines which of the five pages you see after logging in; you'll want to change this setting from config to one of monitor, calendar, contacts or notes.

The last three of these need little further explanation; butler reads the appropriate xml file and transforms it into html for display. The navigation bar at the top of the displays enables easy switching between the pages.

The default monitor page displays some information about the JVM and the app server, which currently must be a version of tomcat. It also explains how the monitoring information can be extended by creating a monitor.txt file on the server. Each line of this file should contain a single OS specific command, which butler will then execute and add its output when the page is reloaded. The location of the home directory is also displayed, it's here that the server creates its rotated log files.

In addition to the browsable pages already mentioned, butler offers REST style interfaces which the client Butler accesses to upload and download the pooter.zip archive. The upload interface will only accept a correctly named file. The POST request is only checked for the authorization parameters after the file has been received; if these are not correct, the file is deleted. If this results from incorrect configuration of your own Butler module client, it will have displayed an explanatory response from the server and you should check that details on butler's config page and Butler's preference tab are identical. The download interface will not offer the file unless authorization details in the GET request are correct.

The butler.log files in the home directory will largely contain info messages about access, file transfers and page views. Any warn lines are probably a result of unauthorized access attempts, either at the login page or to the REST interfaces. If these cannot be explained by typos or mistakes in configuration, you may want to consider some action against the offending ip addresses. As with any web-based service on a public network, it is good practise to monitor these logs; I suggest logwitch for help with this.

Using the client

There are three configuration options; the URL of server that you are going to exchange data with which must be running the butler web app, the server Login Name and the server Password. The protocol, such as http, must be specified as part of the server's url. The default settings are good for initial testing, with a tomcat instance running butler (the web app) on port 8080 of the local machine. Once you deploy the web app on a server, the url will have to be changed to suit. The login name and password must be changed for security reason both on the butler web app and the Butler module and they must continue to match.

Assuming you have connectivity with the running web app, press to create and send an archive of files to the server and to download the same archive from the server and overwrite existing calendar, contacts and notes data.

The server's http response code is displayed; generally a 200 is an indication of success unless the authorization settings are out of sync. A server response message is also displayed, which should make the situation clear.

If an upload is successful, the zip archive created on the desktop machine is immediately unzipped on the server and the information it displays is updated. Before attempting a download any existing archive is backed up to pooter-old.zip. Thus if you mistakenly overwrite more current data files, copies of the originals can be recovered.

Providing a browser has been set in Pooter's settings, you can directly log into the server with .