Fossil

#
BCC = cc
BCCFLAGS = $(CFLAGS)

#### The suffix to add to final executable file.  When cross-compiling
#    to windows, make this ".exe".  Otherwise leave it blank.
#
E =

TCC = cc
TCCFLAGS = $(CFLAGS)

#### Tcl shell for use in running the fossil testsuite.  If you do not
#    care about testing the end result, this can be blank.
#
TCLSH = tclsh

# LIB =	  -lz
LIB = compat/zlib/libz.a
TCC +=	  -g -O0 -DHAVE_AUTOCONFIG_H
TCC += -Icompat/zlib
TCC += -DSQLITE_WITHOUT_ZONEMALLOC
TCC += -D_BSD_SOURCE=1
TCC += -DWITHOUT_ICONV
TCC += -Dsocklen_t=int
TCC += -DSQLITE_MAX_MMAP_SIZE=0
TCC += -DFOSSIL_ENABLE_LEGACY_MV_RM=1
INSTALLDIR = $(DESTDIR)/usr/local/bin
USE_SYSTEM_SQLITE =
USE_LINENOISE = 1
# FOSSIL_ENABLE_TCL = @FOSSIL_ENABLE_TCL@
FOSSIL_ENABLE_TCL = 0
FOSSIL_ENABLE_MINIZ = 0

include $(SRCDIR)/main.mk

distclean: clean
	rm -f autoconfig.h config.log Makefile

  $(SRCDIR)/comformat.c \
  $(SRCDIR)/configure.c \
  $(SRCDIR)/content.c \
  $(SRCDIR)/cookies.c \
  $(SRCDIR)/db.c \
  $(SRCDIR)/delta.c \
  $(SRCDIR)/deltacmd.c \
  $(SRCDIR)/deltafunc.c \
  $(SRCDIR)/descendants.c \
  $(SRCDIR)/diff.c \
  $(SRCDIR)/diffcmd.c \
  $(SRCDIR)/dispatch.c \
  $(SRCDIR)/doc.c \
  $(SRCDIR)/encode.c \
  $(SRCDIR)/etag.c \

  $(OBJDIR)/comformat_.c \
  $(OBJDIR)/configure_.c \
  $(OBJDIR)/content_.c \
  $(OBJDIR)/cookies_.c \
  $(OBJDIR)/db_.c \
  $(OBJDIR)/delta_.c \
  $(OBJDIR)/deltacmd_.c \
  $(OBJDIR)/deltafunc_.c \
  $(OBJDIR)/descendants_.c \
  $(OBJDIR)/diff_.c \
  $(OBJDIR)/diffcmd_.c \
  $(OBJDIR)/dispatch_.c \
  $(OBJDIR)/doc_.c \
  $(OBJDIR)/encode_.c \
  $(OBJDIR)/etag_.c \

 $(OBJDIR)/comformat.o \
 $(OBJDIR)/configure.o \
 $(OBJDIR)/content.o \
 $(OBJDIR)/cookies.o \
 $(OBJDIR)/db.o \
 $(OBJDIR)/delta.o \
 $(OBJDIR)/deltacmd.o \
 $(OBJDIR)/deltafunc.o \
 $(OBJDIR)/descendants.o \
 $(OBJDIR)/diff.o \
 $(OBJDIR)/diffcmd.o \
 $(OBJDIR)/dispatch.o \
 $(OBJDIR)/doc.o \
 $(OBJDIR)/encode.o \
 $(OBJDIR)/etag.o \

		$(OBJDIR)/comformat_.c:$(OBJDIR)/comformat.h \
		$(OBJDIR)/configure_.c:$(OBJDIR)/configure.h \
		$(OBJDIR)/content_.c:$(OBJDIR)/content.h \
		$(OBJDIR)/cookies_.c:$(OBJDIR)/cookies.h \
		$(OBJDIR)/db_.c:$(OBJDIR)/db.h \
		$(OBJDIR)/delta_.c:$(OBJDIR)/delta.h \
		$(OBJDIR)/deltacmd_.c:$(OBJDIR)/deltacmd.h \
		$(OBJDIR)/deltafunc_.c:$(OBJDIR)/deltafunc.h \
		$(OBJDIR)/descendants_.c:$(OBJDIR)/descendants.h \
		$(OBJDIR)/diff_.c:$(OBJDIR)/diff.h \
		$(OBJDIR)/diffcmd_.c:$(OBJDIR)/diffcmd.h \
		$(OBJDIR)/dispatch_.c:$(OBJDIR)/dispatch.h \
		$(OBJDIR)/doc_.c:$(OBJDIR)/doc.h \
		$(OBJDIR)/encode_.c:$(OBJDIR)/encode.h \
		$(OBJDIR)/etag_.c:$(OBJDIR)/etag.h \

$(OBJDIR)/deltacmd_.c:	$(SRCDIR)/deltacmd.c $(TRANSLATE)
	$(TRANSLATE) $(SRCDIR)/deltacmd.c >$@

$(OBJDIR)/deltacmd.o:	$(OBJDIR)/deltacmd_.c $(OBJDIR)/deltacmd.h $(SRCDIR)/config.h
	$(XTCC) -o $(OBJDIR)/deltacmd.o -c $(OBJDIR)/deltacmd_.c

$(OBJDIR)/deltacmd.h:	$(OBJDIR)/headers

$(OBJDIR)/deltafunc_.c:	$(SRCDIR)/deltafunc.c $(TRANSLATE)
	$(TRANSLATE) $(SRCDIR)/deltafunc.c >$@

$(OBJDIR)/deltafunc.o:	$(OBJDIR)/deltafunc_.c $(OBJDIR)/deltafunc.h $(SRCDIR)/config.h
	$(XTCC) -o $(OBJDIR)/deltafunc.o -c $(OBJDIR)/deltafunc_.c

$(OBJDIR)/deltafunc.h:	$(OBJDIR)/headers

$(OBJDIR)/descendants_.c:	$(SRCDIR)/descendants.c $(TRANSLATE)
	$(TRANSLATE) $(SRCDIR)/descendants.c >$@

$(OBJDIR)/descendants.o:	$(OBJDIR)/descendants_.c $(OBJDIR)/descendants.h $(SRCDIR)/config.h
	$(XTCC) -o $(OBJDIR)/descendants.o -c $(OBJDIR)/descendants_.c

# The Differences Between the Setup and Admin User Capabilities

Several of the Fossil user capabilities form a clear power hierarchy.
Mathematically speaking:

> *Setup > Admin > Moderator > User > Subscriber > Anonymous > Nobody*

This document explains the distinction between the first two. For the
others, see:

* [How Moderation Works](./forum.wiki#moderation)

* [Users vs Subscribers](./alerts.md#uvs)

        to 0 to Setup only while allowing Admin-only users to change it
        from 0 to 1. Fossil doesn't currently allow that.</p>

    *   <p><b>Risky</b>: The <tt>https-login</tt> setting falls under
        the "Security" section above, but it should probably never be
        adjusted by Admin-only users. Sites that want it on will never
        want it to be disabled without a very good reason.</p>

        <p>There is also an inverse risk: if the site has a front-end
        HTTPS proxy that uses HTTP to communicate over localhost to
        Fossil, enabling this setting will create an infinite redirect
        loop! (Ask me how I know.)</p>

    *   <p><b>Dangerous</b>: The <tt>email-send-command</tt> setting
        could allow a rogue Admin to run arbitrary commands on the host

Backoffice
==========

This is technical documentation about the internal workings of Fossil.
Ordinary Fossil users do not need to know about anything covered by this
document.  The information here is intended for people who want to enhance
or extend the Fossil code, or who just want a deeper understanding of
the internal workings of Fossil.

What Is The Backoffice
----------------------

The backoffice is a mechanism used by a
[Fossil server](/doc/trunk/www/server.wiki) to do low-priority
background work that is not directly related to the user interface.  Here
are some examples of the kinds of work that backoffice performs:

  1.  Sending email alerts and notifications
  2.  Sending out daily digests of email notifications
  3.  Other background email handling chores

request.

The backoffice is not a daemon.  Each backoffice process runs for a short
while and then exits.  This helps keep Fossil easy to manage, since there
are no daemons to start and stop.  To upgrade Fossil to a new version,
you simply replace the older "fossil" executable with the newer one, and
the backoffice processes will (within a minute or so) start using the new
one.  (Upgrading the executable on Windows is more complicated, since on
Windows it is not possible to replace an executable file that is in active
use.  But Windows users probably already know this.)

The backoffice is serialized and rate limited.  No more than a single
backoffice process will be running at once, and backoffice runs will not
occur more frequently than once every 60 seconds.

If a Fossil server is idle, then no backoffice processes will be running.
That means there are no extra processes sitting around taking up memory
and process table slots for seldom accessed repositories.
The backoffice is an on-demand system.
A busy repository will usually have a backoffice
running at all times.  But an infrequently accessed repository will only have
backoffice processes running for a minute or two following the most recent
access.

>  fossil test-backoffice-lease -R _REPOSITORY_

If a system has been idle for a long time, then there will be no
backoffice processes.  (Either the process id entries in the lease
will be zero, or there will exist no process associated with the
process id.) When a new web request comes in, the system
sees that no backoffice process is active and so it kicks off a separate
process to run backoffice.

The new backoffice process becomes the "current" process.  It sets a
lease expiration time for itself to be 60 seconds in the future.
Then it does the backoffice processing and exits.  Note that usually
the backoffice process will exit long before its lease expires.  That
is ok.  The lease is there to limit the rate at which backoffice processes
run.

If a new backoffice process starts up and sees that the "current" lease has

can be fixed.  The "backoffice-logfile" setting is the name of a log
file onto which is appended a short message everything a backoffice
process actually starts to do the backoffice work.  This log file can
be used to verify that backoffice really is running, if there is any
doubt.  The "backoffice-disable" setting prevents automatic backoffice
processing, if true.  Use this to completely disable backoffice processing
that occurs automatically after each HTTP request.  The "backoffice-disable"
setting does not affect the operation of the manual
"fossil backoffice" command.
Most installations should leave "backoffice-nodelay" and "backoffice-disable"
set to their default values of off and
leave "backoffice-logfile" unset or set to an empty string.

Some people have come to associate blockchain with cryptocurrency, however,
and since Fossil has nothing to do with cryptocurrency, the claim that
Fossil is build around blockchain is met with skepticism.  The key thing
to note here is that cryptocurrency implementations like BitCoin are
built around blockchain, but they are not synonymous with blockchain.
Blockchain is a much broader concept.  Blockchain is a mechanism for
constructed a distributed ledger of transactions.
Yes, you can use a distributed
ledger to implement a cryptocurrency, but you can also use a distributed
ledger to implement a version control system, and probably many other kinds
of applications as well.  Blockchain is a much broader idea than
cryptocurrency.

[(1)]: https://en.wikipedia.org/wiki/Blockchain

<title>Change Log</title>

<a name='v2_9'></a>
<h2>Changes for Version 2.9 (pending)</h2>

  *  Improved handling of relative hyperlinks on the
     [/help?cmd=/artifact|/artifact] pages for wiki. For example,
     hyperlinks and the lizard &lt;img&gt; now work correctly
     for both [/artifact/2ff24ab0887cf522] and
     [/doc/0d7ac90d575004c2415/www/index.wiki].
  *  For the "[/help?cmd=update|fossil update]" and
     "[/help?cmd=checkout|fossil checkout]" commands, if a
     managed file is removed because it is no longer part of the target
     check-in and the directory containing the file is empty after the
     file is removed and the directory is not the current working
     directory and is not on the [/help?cmd=empty-dirs|empty-dirs]
     list, then also remove the directory.
  *  Update internal Unicode character tables, used in regular expression
     handling, from version 11.0 to 12.0.
  *  In "[/help?cmd=regexp|fossil regexp]", "[/help?cmd=grep|fossil grep]"
     and the TH1 "regexp" command, the -nocase option now removes multiple
     diacritics from the same character (derived from SQLite's
     remove_diacritics=2)

<a name='v2_8'></a>
<h2>Changes for Version 2.8 (2019-02-20)</h2>

  *  Show cherry-pick merges as dotted lines on the timeline graph.
     &rarr; The "fossil rebuild" command must be run to create and
     populate the new "cherrypick" table in the repository in order
     for this feature to operate.
  *  Add the ability to associate branches, check-ins, and tags with
     specially-named Wiki pages. This gives the ability to better
     document branches and tags, and provide more documentation on
     check-ins beyond the check-in comment.  The associated Wiki is
     automatically displayed on /info pages for check-ins, and on
     /timeline?r=BRANCH and /timeline?t=TAG pages for branches and
     tags. This feature is on by default, but can be disabled in on
     the Admin/Wiki page.
  *  Enhance the repository list page (shown for example by
     "fossil all ui") so that it shows the name and last check-in
     time for each project.  The implementation of the repository
     list page is now broken out into a separate source file (repolist.c).
  *  Allow users with Forum Supervisor permission ('6') to add Forum

     version of the Wiki page named in the timeline, not to the latest
     version.
  *  Enhancements to the "amend", "tag", and "reparent" commands, including
     adding options --override-date, --override-user, and --dry-run.
  *  Add the global --comment-format command-line option and the
     comment-format setting to control the display of the command-line
     timeline.
  *  Change the "fossil reparent" command so that it only works from
     within an active checkout.
  *  On the /setup_ucap_list, show administrators how many users have
     each capability.  The counts are a hyperlink to the /setup_ulist
     page showing the subset of users that have that capability.
  *  Provide the ability to redirect all HTTP pages to HTTPS.  Formerly
     one could cause this to occur for the /login page only.  That option
     still exists, but the redirect can now also be done for all pages.

     Formerly, user capabilities were letters from [a-z], but with the
     enhancements, the supply of lower case letters was exhausted.
     User capabilities are now letters in [a-zA-Z0-9].
  *  The built-in skins are now responsive, providing better layout on
     small screens, including mobile devices.
  *  The default skin now includes a hamburger menu that is generated
     by the [/sitemap] page.
  *  All of the built-in skins now use a
     [https://en.wikipedia.org/wiki/Content_Security_Policy|Content Security Policy (CSP)]
     to help prevent cross-site injection and forgery attacks.  There are no known
     vulnerabilities in Fossil.  The added CSP does not fix anything; it merely adds
     another layer of defense.
  *  The [/sitemap] and other list pages show as multiple columns if
     the viewing window is wide enough.
  *  There is an optional "js" file for each skin that can be used to

global setting should be used to force the case sensitivity to the
most sensible condition.

`--chdir DIRECTORY`: Change to the named directory before processing
any commands.


`--comfmtflags NUMBER`
`--comment-format NUMBER`: Specify flags that control how check-in comments
and certain other text outputs are formatted for display. The flags are
individual bits in `NUMBER`, which must be specified in base 10:

  * _0_ — Uses the revised algorithm with no special handling.

  * _1_ — Uses the legacy algorithm, other flags are ignored.

[#wikichng | wiki artifact].

The <b>Z</b> card is the required checksum over the rest of the artifact.

<a name="forum"></a>
<h3>2.8 Forum Posts</h3>

Forum posts are intended as a mechanism for users and developers to
discuss a project.  Forum posts are like messages on a mailing list.

The following cards are allowed on an forum post artifact:

<blockquote>
<b>D</b> <i>time-and-date-stamp</i><br />
<b>G</b> <i>thread-root</i><br />
<b>H</b> <i>thread-title</i><br />
<b>I</b> <i>in-reply-to</i><br />
<b>N</b> <i>mimetype</i><br />
<b>P</b> <i>parent-artifact-id</i><br />
<b>U</b> <i>user-name</i><br />
<b>W</b> <i>size</i> <b>\n</b> <i>text</i> <b>\n</b><br />
<b>Z</b> <i>checksum</i>
</blockquote>

Every forum post must have either one <b>I</b> card and one <b>G</b> card
or one <b>H</b> card.
Forum posts are organized into topic threads.  The initial
post for a thread (the root post) has an <b>H</b> card giving the title or
subject for that thread.  The argument to the <b>H</b> card is a string
in the same format as a comment string in a <b>C</b> card.
All follow-up posts have an <b>I</b> card that
indicates which prior post in the same thread the current forum
post is replying to, and a <b>G</b> card specifying the root post for

     nearest wifi router or cellular data tower.

  *  <b>Interlink with Other Fossil-Managed Artifacts:</b> Because forum
     posts are normal Fossil artifacts, you can interlink them with
     other Fossil artifacts using short internal links: link to forum
     threads from a [./tickets.wiki | ticket], link to a wiki document
     from a forum post, etc.

  *  <b>Durable Links:</b> Once you create a valid internal artifact
     link in Fossil, it <em>remains</em> valid, durably. With
     third-party forum software and mailing list search engines, your
     links are only valid until the third-party component changes its
     URL scheme or disappears from the web.

  *  <b>Role-Based Access Control:</b> The forum uses the same

all of the makefiles for all targets will be rebuild.

There is an option code verification step implemented using

  15.  [/file/src/codecheck1.c | codecheck1.c]

This file implements a small utility program ("codecheck1")
that scans other Fossil source files looking for errors in printf-style
format strings.
The codecheck1 utility detects missing or surplus arguments on
printf-like functions and dangerous uses of "%s" that might
permit SQL injection or cross-site scripting attacks.  This code
check step is run automatically on each build of Fossil, and can
also be run separately by typing "make codecheck".  Note that the
built-in printf format checking of GCC does not function for Fossil
since Fossil implements its own printf (in the
[/file/src/printf.c | printf.c] source file) that includes special

    proxy access to another HTTP server, this option is overkill for our
    purposes.  nginx is itself a fully featured HTTP server, so we will
    choose in this guide not to make nginx reinterpret Fossil’s
    implementation of HTTP.

*   **CGI** — This method is simple but inefficient, because it launches
    a separate Fossil instance on every HTTP hit.

    Since Fossil is a relatively small self-contained program, and it’s
    designed to start up quickly, this method can work well in a
    surprisingly large number of cases.

    Nevertheless, we will avoid this option in this document because
    we’re already buying into a certain amount of complexity here in
    order to gain power.  There’s no sense in throwing away any of that

`*.example.com` and `*.example.net`; and `local/foo` contains the
configuration for `*.foo.net`.

Here’s an example configuration:

      server {
          server_name .foo.net;

          include local/tls-common;

          charset utf-8;

          access_log /var/log/nginx/foo.net-https-access.log;
           error_log /var/log/nginx/foo.net-https-error.log;

          # Bypass Fossil for the static Doxygen docs
          location /doc/html {
              root /var/www/foo.net;

              location ~* \.(html|ico|css|js|gif|jpg|png)$ {
                  expires 7d;
                  add_header Vary Accept-Encoding;
                  access_log off;
              }
          }

          # Redirect everything else to the Fossil instance
          location / {
              include scgi_params;
              scgi_pass 127.0.0.1:12345;
              scgi_param HTTPS "on";
              scgi_param SCRIPT_NAME "";
          }

The first line tells nginx to accept TLS-encrypted HTTP connections on
the standard HTTPS port. It is the same as `listen 443; ssl on;` in
older versions of nginx.

Since all of those domains share a single TLS certificate, we reference
the same `example.com/*.pem` files written out by Certbot with the
`ssl_certificate*` lines.

The `ssl_dhparam` directive isn’t strictly required, but without it, the
server becomes vulnerable to the [Logjam attack][lja] because some of
the cryptography steps are precomputed, making the attacker’s job much
easier. The parameter file this directive references should be
generated automatically by the Let’s Encrypt package upon installation,
making those parameters unique to your server and thus unguessable. If

    where it can speak HTTPS safely again.

So, from the second `service { }` block, we include this file to set up
the minimal HTTP service we reqiure, `local/http-certbot-only`:

      listen 80;
      listen [::]:80;

      # This is expressed as a rewrite rule instead of an "if" because
      # http://wiki.nginx.org/IfIsEvil
      #rewrite ^(/.well-known/acme-challenge/.*) $1 break;

      # Force everything else to HTTPS with a permanent redirect.
      #return 301 https://$host$request_uri;

As written above, this configuration does nothing other than to tell
nginx that it’s allowed to serve content via HTTP on port 80 as well.

We’ll uncomment the `rewrite` and `return` directives below, when we’re