Fossil

Check-in [0769acd2]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Add documentation for settings, SSL usage, and change log.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | ben-testing
Files: files | file ages | folders
SHA1:0769acd2e0c5e04d171f14704eb0d597ac661f50
User & Date: ben 2011-08-12 09:21:28
Context
2011-08-12
09:26
Update documentation index. check-in: e764e8f3 user: ben tags: ben-testing
09:21
Add documentation for settings, SSL usage, and change log. check-in: 0769acd2 user: ben tags: ben-testing
2011-08-10
18:53
Display of pathnames relative to working directory for status, changes and extras commands now controlled by 'relative-paths' setting (default: off) and --abs-paths and --rel-paths options. check-in: cdd298f5 user: ben tags: ben-testing
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to www/changes.wiki.

1
2
3
4
5
6
7











8
9
10
11
12
13
14
<title>Change Log</title>

<h2>Changes For Version 1.19 (pending)</h2>

  *  Added a ./configure script based on autosetup.
  *  Added the "[/help/winsrv | fossil winsrv]" command
     for creating a Fossil service on windows systems.












<h2>Changes For Version 1.18 (2011-07-14)</h2>

  *  Added this Change Log
  *  Added sequential version numbering
  *  Added a optional configure script - the Makefile still works for most
     systems.







>
>
>
>
>
>
>
>
>
>
>







1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
<title>Change Log</title>

<h2>Changes For Version 1.19 (pending)</h2>

  *  Added a ./configure script based on autosetup.
  *  Added the "[/help/winsrv | fossil winsrv]" command
     for creating a Fossil service on windows systems.
  *  Added "versionable settings" where settings that affect
     the local tree can be stored in versioned files in the
     .fossil-settings directory.
  *  Added "relative-paths" setting and options for status,
     changes and extras commands to optionally show pathnames
     relative to the current working directory.
  *  Added "empty-dirs" versionable setting.
  *  Added support for client-side SSL certificates with "ssl-identity"
     setting and --ssl-identity option.
  *  Added "ssl-ca-location" setting to specify trusted root
     SSL certificates.

<h2>Changes For Version 1.18 (2011-07-14)</h2>

  *  Added this Change Log
  *  Added sequential version numbering
  *  Added a optional configure script - the Makefile still works for most
     systems.

Changes to www/index.wiki.

125
126
127
128
129
130
131


132
133
134
135
136
137
138
  *  A tutorial on [./branching.wiki | branching], what it means and how
     to do it using fossil.
  *  The [./selfcheck.wiki | automatic self-check] mechanism
     helps insure project integrity.
  *  Fossil contains a [./wikitheory.wiki | built-in wiki].
  *  An [./event.wiki | Event] is a special kind of wiki page associated
     with a point in time rather than a name.


  *  There is a
    [http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users | mailing list] (with publicly readable
     [http://www.mail-archive.com/fossil-users@lists.fossil-scm.org | archives]
     available for discussing fossil issues.
  *  [./stats.wiki | Performance statistics] taken from real-world projects
     hosted on fossil.
  *  How to [./shunning.wiki | delete content] from a fossil repository.







>
>







125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
  *  A tutorial on [./branching.wiki | branching], what it means and how
     to do it using fossil.
  *  The [./selfcheck.wiki | automatic self-check] mechanism
     helps insure project integrity.
  *  Fossil contains a [./wikitheory.wiki | built-in wiki].
  *  An [./event.wiki | Event] is a special kind of wiki page associated
     with a point in time rather than a name.
  *  [./settings.wiki | Settings] control the behaviour of fossil.
  *  [./ssl.wiki | Use SSL] to encrypt communication with the server.
  *  There is a
    [http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users | mailing list] (with publicly readable
     [http://www.mail-archive.com/fossil-users@lists.fossil-scm.org | archives]
     available for discussing fossil issues.
  *  [./stats.wiki | Performance statistics] taken from real-world projects
     hosted on fossil.
  *  How to [./shunning.wiki | delete content] from a fossil repository.

Added www/settings.wiki.































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
<title>Fossil Settings</title>

<h2>Using Fossil Settings</h2>

Settings control the behaviour of fossil. They are set with the <tt>fossil settings</tt> command, or through the web interface in the Settings page in the Admin section.

For a list of all settings, view the Settings page, or type <tt>fossil help settings</tt> from the command line.


<h3>Repository settings</h3>

Settings are set on a per-repository basis. When you clone a repository, a subset of settings are copied to your local repository.

If you make a change to a setting on your local repository, it is not synced back to the server when you <tt>push</tt> or <tt>sync</tt>. If you make a change on the server, you need to manually make the change on all repositories which are cloned from this repository.

You can also set a setting globally on your local machine. The value will be used for all repositories cloned to your machine, unless overridden explicitly in a particular repository. Global settings can be set by using the <tt>-global</tt> option on the <tt>fossil settings</tt> command.


<h3>"Versionable" settings</h3>

Most of the settings control the behaviour of fossil on your local machine, largely acting to reflect your preference on how you want to use Fossil, how you communicate with the server, or options for hosting a repository on the web. 

However, for historical reasons, some settings affect how you work with versioned files. These are <tt>binary-glob</tt>, <tt>crnl-glob</tt>, <tt>ignore-glob</tt>, <tt>empty-dirs</tt> and <tt>manifest</tt>. The most important is <tt>ignore-glob</tt> which specifies which files should be ignored when looking for unmanaged files with the <tt>extras</tt> command.

Because these options can change over time, and the inconvenience of replicating changes, these settings are "versionable". As well as being able to be set using the <tt>settings</tt> command or the web interface, you can created versioned files in the <tt>.fossil-settings</tt> directory named with the setting name. The contents of the file is the value of the setting, and these files are checked in, committed, merged, and so on, as with any other file.

Where a setting is a list of values, such as <tt>ignore-glob</tt>, you can also a newline as a separator as well as a comma.

For example, to set the list of ignored files, create a <tt>.fossil-settings/ignore-glob</tt> file where each line contains a glob for ignored files.

If you set the value of a setting using the <tt>settings</tt> command as well as a versioned file, the versioned setting will take precedence. A warning will be displayed.

Added www/ssl.wiki.









































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
<title>SSL and Fossil</title>

<h2>Using SSL with Fossil</h2>

If you are storing sensitive information in your repository, you should use SSL to encrypt all communications. This will protect the credentials used to access the server, as well preventing eavesdropping of the contents of your repository.

To host a repository with SSL, you need to use an web server which supports SSL in front of the Fossil server. You can host it using the CGI option or by proxying Fossil's built in HTTP server.

Your fossil client must be built with SSL support. The <tt>configure</tt> script will attempt to find OpenSSL on your system, but if necessary, you can specify the location with the <tt>--with-openssl</tt> option. Type <tt>./configure --help</tt> for details.

Make sure the URL you clone from uses the <tt>https:</tt> scheme to ensure you're using SSL. If your server is configured to serve the repository from http as well as https, it's easy to accidentally use unencrypted HTTP if you forget the all important 's'.


<h2>Certificates</h2>

To verify the identify of a server, SSL uses certificates. Fossil needs to know which certificates you trust.

If you are using a self-signed certificate, you'll be asked if you want to accept the certificate the first time you communicate with the server. Verify the certificate fingerprint is correct, then answer "always" to remember your decision.

If you are using a certificate signed by a certificate authority, you need to specify the certificates you trust with the <tt>ssl-ca-location</tt> setting. Set this globally with the <tt>-global</tt> option for convenience.

This should be set to the location of a file containing all the PEM encoded certificates you trust. You can obtain a certificate using a web browser, for example, Firefox, or just refer to your system's trusted CA roots which are usually stored somewhere in <tt>/etc</tt>.


<h2>Client side certificates</h2>

You can also use client side certificates to add an extra layer of authentication, over and above Fossil's built in user management. If you are particularly paranoid, you'll want to use this to remove the ability of anyone on the internet from making any request to Fossil. Without presenting a valid client side certificate, the web server won't invoke the fossil CGI handler.

Configure your server to request a client side certificate, and set up a certificate authority to sign your client certificates. For each person who needs to access the repository, create a private key and certificate signed with that CA.

The PEM encoded private key and certificate should be stored in a single file, simply by concatenating the key and certificate files. Specify the location of this file with the <tt>ssl-identity</tt> setting, or the <tt>--ssl-identity</tt> option to the <tt>clone</tt> command.

If you've password protected the private key, the password will be requested every time you connect to the server. This password is not stored by fossil, as doing so would defeat the purpose of having a password.

If you attempt to connect to a server which requests a client certificate, but don't provide one, fossil will show an error message which explains what to do to authenticate with the server.