Minimal server
The bare minimum configuration needed to get a server to start
is as follows:
The configuration file will:
With this configuration file (server.conf), and
assuming that all referenced directories have been created, the server can be
started with the included
io7m-jfprop-server-0.3.0-main.jar:
The server does not fork into the background, allowing it to be safely
monitored by process supervision programs such as
daemontools.
Authentication
The
io7m-jfprop server implements
a simple authentication system. In order to use the administration interface, clients
must provide the
admin password. This is passed
as an ordinary HTTP request parameter called
admin_password. As an example, using the
ubiquitous
curl command
line tool (with individual HTTP parameters passed with the
-d option):
The server replies with a simple text/plain
UTF-8 body. Without the admin password, access is denied (and a
403 HTTP status code is returned):
Clients wanting to send notifications of commits and tickets to the server must
also be authenticated. First, assuming a client with a user name
client0, a user
must first be created:
The server says nothing and returns a standard
200 HTTP status code
if the operation is successful.
A single user may have many different workstations, and for reasons of
security, each workstation should be uniquely authenticated. For
example, if a developer loses their laptop to theft, that laptop should no
longer have any kind of access to the server. The server allows this kind
of control by requiring user accounts to have
keys. In order to generate a new key for
client0, use the
user-generate-key command:
The keys for any user account can be listed:
Keys can also be revoked at any time:
Clients must present valid user names and keys in order to use the
server interface. The list command
(on the server interface, not the administration interface) will list
all repositories in any subdirectory of the configured repository
directory. Assuming that the directory contains
example0.fossil,
example1.fossil, and
example2.fossil:
Without a correct user name and key, access is denied:
Mass synchronization
In the
original example,
one of the issues was that if developers make changes on an external mirror
repository, then those changes don't make it back into a canonical repository
until something causes the canonical repository to synchronize. The
io7m-jfprop server can periodically
synchronize sets of repositories. Administrators provide
time specifications
(such as "any day, on hours divisible by 2, at 30 minutes past the hour") and
regular expressions
(such as
"/x/.*\.fossil"),
and the server synchronizes matching repositories at matching times. As an
example, to synchronize all repositories with names containing the word "example"
at
14:25 every day:
To synchronize all repositories at the start of all even hours:
The server provides a test command,
mass-sync-test-pattern, that adminstrators
can use to check if a given pattern will match a given repository:
Mass synchronization is not enabled by default, and must be explicitly
enabled in the configuration file:
This is intended as a safety feature in emergencies: If a misconfigured
mass synchronization is causing repository syncs at an alarming rate, the
administrator can stop the server, disable the synchronizer, restart the
server, and then not have to rush to fix the misconfigured mass synchronization
in the administration interface before more synchronizations occur.
TLS
Clearly, sending user names, keys, and passwords in cleartext over
hostile networks is a bad idea. The
io7m-jfprop server can
be configured to use the
TLS
protocol to secure all communications between clients and the server.
Familiarity with Java
keystores
and
truststores is assumed, and the
configuration of these is outside of the scope of this documentation.
The following configuration file enables TLS for both the administration
and server interfaces:
The configuration file will:
Note that the configuration file does not enable the plain HTTP interfaces,
so all clients must speak TLS in order to be
able to communicate with the server. This is optional: The
io7m-jfprop server supports
any combination of HTTP and HTTPS interfaces running on any given addresses.
Remotes
The
io7m-jfprop server
is capable of calling the
on-commit command
on other
io7m-jfprop servers.
This allows notifications to propagate to other servers automatically,
triggering chains of synchronizations .
Essentially, administrators add
remotes
and then associate those remotes with repositories. These are distinct
from Fossil's concept of remotes. When a client calls the
on-commit
command for a repository
r, the
server calls the
on-commit
command on all remotes associated with
r. The server appears to be an
ordinary client to the remotes (and must therefore have a configured
user name and key). Adding a remote is simple:
Remotes are referred to by server-generated integer identifiers. In
the above example, the initially created remote has an identifier of
1.
Remotes can be associated with individual repositories, or can be associated
with all repositories globally. The latter case is intended to save administrators
the burden of configuring hundreds of repositories.
Mail
The
io7m-jfprop server is
capable of notifying an administrator when certain classes of problems
occur. Specifically, when a synchronization error occurs for a repository,
and when notifying a
remote fails.
The following configuration file enables mail notifications for an
administrator, setting the mail server, recipient, and sender:
If the mail server requires a username and password for authentication,
these can be specified separately:
Configuring Fossil
In order to actually make use of the
io7m-jfprop system,
the Fossil tool must be configured to send HTTP(S) requests
when commits and ticket changes occur. Note that a version of
Fossil built more recently than
2013-12-20
is required.
Using the fossil ui web interface,
navigate to Admin → Transfers.
Then, assuming the
io7m-jfprop server is
at http://fsl.iw.example.com:10080,
the repository in question is /example0.fossil,
the desired user name is someone, and
the desired key is f6925a1f7d8bb47376ec1d89291a9e5d9b6ca1a55932d853610c67b34a9ed785,
the following TH1 script added to the
Commit and
Ticket sections will cause Fossil
to notify the server when commits or ticket changes occur:
Note that by default, Fossil will only allow connections to
servers with names that are matched by the pattern specified
in the th1-uri-regexp setting.
By default, the value of this setting is empty and so all connection
attempts will be denied. To allow connections to
http://fsl.iw.example.com:10080,
set the th1-uri-regexp setting
to a pattern that matches the URI:
This can be tested by navigating to the
Admin → TH1 section in the
web interface and manually executing http -async
commands at the command prompt - URIs that are not allowed by the current regular
expression will raise errors.