Fossil

Check-in [08291fec]
Login

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

Overview
Comment:Merge in trunk latest developments.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | test-updates
Files: files | file ages | folders
SHA3-256: 08291fec9f6f215bee8acbbbf5a7c8e4b5ee49a98ed493dcb0809ceb49a76f8b
User & Date: andybradford 2019-08-31 16:23:00
Context
2019-09-03
20:36
Wiki test fixes. check-in: b40f1ac1 user: drh tags: trunk
2019-08-31
16:23
Merge in trunk latest developments. Closed-Leaf check-in: 08291fec user: andybradford tags: test-updates
2019-08-29
00:28
Updated comment about "6-character random hex password" at the top level of the new setup docs to track [23a9f9bac2]. check-in: f304ba31 user: wyoung tags: trunk
2019-08-21
14:46
Merge in recent developments on trunk. check-in: 70d091ea user: andybradford tags: test-updates
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to skins/default/header.txt.

15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
  upvar home home
  if {[string range $url 0 [string length $current]] eq "/$current"} {
    html "<a href='$home$url' class='active $cls'>$name</a>\n"
  } else {
    html "<a href='$home$url' class='$cls'>$name</a>\n"
  }
}
html "<a id='hbbtn' href='#'>&#9776;</a>"
menulink $index_page Home {}
if {[anycap jor]} {
  menulink /timeline Timeline {}
}
if {[hascap oh]} {
  menulink /dir?ci=tip Files desktoponly
}







|







15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
  upvar home home
  if {[string range $url 0 [string length $current]] eq "/$current"} {
    html "<a href='$home$url' class='active $cls'>$name</a>\n"
  } else {
    html "<a href='$home$url' class='$cls'>$name</a>\n"
  }
}
html "<a id='hbbtn' href='/sitemap'>&#9776;</a>"
menulink $index_page Home {}
if {[anycap jor]} {
  menulink /timeline Timeline {}
}
if {[hascap oh]} {
  menulink /dir?ci=tip Files desktoponly
}

Changes to src/checkin.c.

1937
1938
1939
1940
1941
1942
1943

1944
1945
1946
1947
1948
1949
1950
}

/*
** COMMAND: ci*
** COMMAND: commit
**
** Usage: %fossil commit ?OPTIONS? ?FILE...?

**
** Create a new version containing all of the changes in the current
** checkout.  You will be prompted to enter a check-in comment unless
** the comment has been specified on the command-line using "-m" or a
** file containing the comment using -M.  The editor defined in the
** "editor" fossil option (see %fossil help set) will be used, or from
** the "VISUAL" or "EDITOR" environment variables (in that order) if







>







1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
}

/*
** COMMAND: ci*
** COMMAND: commit
**
** Usage: %fossil commit ?OPTIONS? ?FILE...?
**    or: %fossil ci ?OPTIONS? ?FILE...?
**
** Create a new version containing all of the changes in the current
** checkout.  You will be prompted to enter a check-in comment unless
** the comment has been specified on the command-line using "-m" or a
** file containing the comment using -M.  The editor defined in the
** "editor" fossil option (see %fossil help set) will be used, or from
** the "VISUAL" or "EDITOR" environment variables (in that order) if

Changes to src/db.c.

115
116
117
118
119
120
121

122
123
124
125
126
127
128
...
797
798
799
800
801
802
803



804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
...
823
824
825
826
827
828
829

830



831
832
833
834
835
836
837
....
1766
1767
1768
1769
1770
1771
1772
1773
1774

1775
1776
1777
1778
1779
1780
1781
....
1800
1801
1802
1803
1804
1805
1806
1807





1808
1809
1810
1811
1812
1813
1814
....
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
} db = {0, 0, 0, 0, 0, 0, };

/*
** Arrange for the given file to be deleted on a failure.
*/
void db_delete_on_failure(const char *zFilename){
  assert( db.nDeleteOnFail<count(db.azDeleteOnFail) );

  db.azDeleteOnFail[db.nDeleteOnFail++] = fossil_strdup(zFilename);
}

/*
** Return the transaction nesting depth.  0 means we are currently
** not in a transaction.
*/
................................................................................
  db_finalize(&s);
  return z;
}

/*
** Initialize a new database file with the given schema.  If anything
** goes wrong, call db_err() to exit.



*/
void db_init_database(
  const char *zFileName,   /* Name of database file to create */
  const char *zSchema,     /* First part of schema */
  ...                      /* Additional SQL to run.  Terminate with NULL. */
){
  sqlite3 *db;
  int rc;
  const char *zSql;
  va_list ap;

  db = db_open(zFileName);
  sqlite3_exec(db, "BEGIN EXCLUSIVE", 0, 0, 0);
  rc = sqlite3_exec(db, zSchema, 0, 0, 0);
  if( rc!=SQLITE_OK ){
    db_err("%s", sqlite3_errmsg(db));
  }
  va_start(ap, zSchema);
  while( (zSql = va_arg(ap, const char*))!=0 ){
................................................................................
    rc = sqlite3_exec(db, zSql, 0, 0, 0);
    if( rc!=SQLITE_OK ){
      db_err("%s", sqlite3_errmsg(db));
    }
  }
  va_end(ap);
  sqlite3_exec(db, "COMMIT", 0, 0, 0);

  sqlite3_close(db);



}

/*
** Function to return the number of seconds since 1970.  This is
** the same as strftime('%s','now') but is more compact.
*/
void db_now_function(
................................................................................
  return g.iRepoDataVers != v;               
}

/*
** Flags for the db_find_and_open_repository() function.
*/
#if INTERFACE
#define OPEN_OK_NOT_FOUND    0x001      /* Do not error out if not found */
#define OPEN_ANY_SCHEMA      0x002      /* Do not error if schema is wrong */

#endif

/*
** Try to find the repository and open it.  Use the -R or --repository
** option to locate the repository.  If no such option is available, then
** use the repository of the open checkout if there is one.
**
................................................................................
  }
  db_open_repository(zRep);
  if( g.repositoryOpen ){
    if( (bFlags & OPEN_ANY_SCHEMA)==0 ) db_verify_schema();
    return;
  }
rep_not_found:
  if( (bFlags & OPEN_OK_NOT_FOUND)==0 ){





#ifdef FOSSIL_ENABLE_JSON
    g.json.resultCode = FSL_JSON_E_DB_NOT_FOUND;
#endif
    if( nArgUsed==0 ){
      fossil_fatal("use --repository or -R to specify the repository database");
    }else{
      fossil_fatal("specify the repository name as a command-line argument");
................................................................................
  if( zUser==0 ){
    zUser = "root";
  }
  db_multi_exec(
     "INSERT OR IGNORE INTO user(login, info) VALUES(%Q,'')", zUser
  );
  db_multi_exec(
     "UPDATE user SET cap='s', pw=lower(hex(randomblob(3)))"
     " WHERE login=%Q", zUser
  );
  if( !setupUserOnly ){
    db_multi_exec(
       "INSERT OR IGNORE INTO user(login,pw,cap,info)"
       "   VALUES('anonymous',hex(randomblob(8)),'hmnc','Anon');"
       "INSERT OR IGNORE INTO user(login,pw,cap,info)"
       "   VALUES('nobody','','gjorz','Nobody');"







>







 







>
>
>











|







 







>
|
>
>
>







 







|
|
>







 







|
>
>
>
>
>







 







|
|







115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
...
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
...
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
....
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
....
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
....
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
} db = {0, 0, 0, 0, 0, 0, };

/*
** Arrange for the given file to be deleted on a failure.
*/
void db_delete_on_failure(const char *zFilename){
  assert( db.nDeleteOnFail<count(db.azDeleteOnFail) );
  if( zFilename==0 ) return;
  db.azDeleteOnFail[db.nDeleteOnFail++] = fossil_strdup(zFilename);
}

/*
** Return the transaction nesting depth.  0 means we are currently
** not in a transaction.
*/
................................................................................
  db_finalize(&s);
  return z;
}

/*
** Initialize a new database file with the given schema.  If anything
** goes wrong, call db_err() to exit.
**
** If zFilename is NULL, then create an empty repository in an in-memory
** database.
*/
void db_init_database(
  const char *zFileName,   /* Name of database file to create */
  const char *zSchema,     /* First part of schema */
  ...                      /* Additional SQL to run.  Terminate with NULL. */
){
  sqlite3 *db;
  int rc;
  const char *zSql;
  va_list ap;

  db = db_open(zFileName ? zFileName : ":memory:");
  sqlite3_exec(db, "BEGIN EXCLUSIVE", 0, 0, 0);
  rc = sqlite3_exec(db, zSchema, 0, 0, 0);
  if( rc!=SQLITE_OK ){
    db_err("%s", sqlite3_errmsg(db));
  }
  va_start(ap, zSchema);
  while( (zSql = va_arg(ap, const char*))!=0 ){
................................................................................
    rc = sqlite3_exec(db, zSql, 0, 0, 0);
    if( rc!=SQLITE_OK ){
      db_err("%s", sqlite3_errmsg(db));
    }
  }
  va_end(ap);
  sqlite3_exec(db, "COMMIT", 0, 0, 0);
  if( zFileName || g.db!=0 ){
    sqlite3_close(db);
  }else{
    g.db = db;
  }
}

/*
** Function to return the number of seconds since 1970.  This is
** the same as strftime('%s','now') but is more compact.
*/
void db_now_function(
................................................................................
  return g.iRepoDataVers != v;               
}

/*
** Flags for the db_find_and_open_repository() function.
*/
#if INTERFACE
#define OPEN_OK_NOT_FOUND       0x001   /* Do not error out if not found */
#define OPEN_ANY_SCHEMA         0x002   /* Do not error if schema is wrong */
#define OPEN_SUBSTITUTE         0x004   /* Fake in-memory repo if not found */
#endif

/*
** Try to find the repository and open it.  Use the -R or --repository
** option to locate the repository.  If no such option is available, then
** use the repository of the open checkout if there is one.
**
................................................................................
  }
  db_open_repository(zRep);
  if( g.repositoryOpen ){
    if( (bFlags & OPEN_ANY_SCHEMA)==0 ) db_verify_schema();
    return;
  }
rep_not_found:
  if( bFlags & OPEN_OK_NOT_FOUND ){
    /* No errors if the database is not found */
    if( bFlags & OPEN_SUBSTITUTE ){
      db_create_repository(0);
    }
  }else{
#ifdef FOSSIL_ENABLE_JSON
    g.json.resultCode = FSL_JSON_E_DB_NOT_FOUND;
#endif
    if( nArgUsed==0 ){
      fossil_fatal("use --repository or -R to specify the repository database");
    }else{
      fossil_fatal("specify the repository name as a command-line argument");
................................................................................
  if( zUser==0 ){
    zUser = "root";
  }
  db_multi_exec(
     "INSERT OR IGNORE INTO user(login, info) VALUES(%Q,'')", zUser
  );
  db_multi_exec(
     "UPDATE user SET cap='s', pw=%Q"
     " WHERE login=%Q", fossil_random_password(10), zUser
  );
  if( !setupUserOnly ){
    db_multi_exec(
       "INSERT OR IGNORE INTO user(login,pw,cap,info)"
       "   VALUES('anonymous',hex(randomblob(8)),'hmnc','Anon');"
       "INSERT OR IGNORE INTO user(login,pw,cap,info)"
       "   VALUES('nobody','','gjorz','Nobody');"

Changes to src/doc.c.

524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
  int n = blob_size(pIn);
  char *z = blob_buffer(pIn);
  for(base=0, i=7; i<n; i++){
    if( z[i]=='$'
     && strncmp(&z[i],"$ROOT/", 6)==0
     && (z[i-1]=='\'' || z[i-1]=='"')
     && i-base>=9
     && (fossil_strnicmp(&z[i-7]," href=", 6)==0 ||
           fossil_strnicmp(&z[i-9]," action=", 8)==0)
    ){
      blob_append(cgi_output_blob(), &z[base], i-base);
      blob_appendf(cgi_output_blob(), "%R");
      base = i+5;
    }
  }
  blob_append(cgi_output_blob(), &z[base], i-base);







|
|







524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
  int n = blob_size(pIn);
  char *z = blob_buffer(pIn);
  for(base=0, i=7; i<n; i++){
    if( z[i]=='$'
     && strncmp(&z[i],"$ROOT/", 6)==0
     && (z[i-1]=='\'' || z[i-1]=='"')
     && i-base>=9
     && ((fossil_strnicmp(&z[i-6],"href=",5)==0 && fossil_isspace(z[i-7])) ||
         (fossil_strnicmp(&z[i-8],"action=",7)==0 && fossil_isspace(z[i-9])) )
    ){
      blob_append(cgi_output_blob(), &z[base], i-base);
      blob_appendf(cgi_output_blob(), "%R");
      base = i+5;
    }
  }
  blob_append(cgi_output_blob(), &z[base], i-base);

Changes to src/fshell.c.

107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
      printf("could not fork a child process to handle the command\n");
      fflush(stdout);
      continue;
    }
    if( childPid==0 ){
      /* This is the child process */
      int main(int, char**);
      main(nArg, azArg);
      exit(0);
    }else{
      /* The parent process */
      int status;
      waitpid(childPid, &status, 0);
    }
  }
#endif
}







|









107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
      printf("could not fork a child process to handle the command\n");
      fflush(stdout);
      continue;
    }
    if( childPid==0 ){
      /* This is the child process */
      int main(int, char**);
      fossil_main(nArg, azArg);
      exit(0);
    }else{
      /* The parent process */
      int status;
      waitpid(childPid, &status, 0);
    }
  }
#endif
}

Changes to src/login.c.

2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
....
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
    nCmd = (int)strlen(zCmd);
    if( strncmp(zCmd,"join",nCmd)==0 && nCmd>=1 ){
      const char *zNewName = find_option("name",0,1);
      const char *zOther;
      char *zErr = 0;
      verify_all_options();
      if( g.argc!=4 ){
        fossil_fatal("unknown extra arguments to \"login-group add\"");
      }
      zOther = g.argv[3];
      login_group_leave(&zErr);
      sqlite3_free(zErr);
      zErr = 0;
      login_group_join(zOther,0,0,0,zNewName,&zErr);
      if( zErr ){
................................................................................
        char *zErr = 0;
        fossil_print("Leaving login-group \"%s\"\n", zLGName);
        login_group_leave(&zErr);
        if( zErr ) fossil_fatal("Oops: %s", zErr);
        return;
      }
    }else{
      fossil_fatal("unknown command \"%s\" - should be \"add\" or \"leave\"",
                   zCmd);
    }
  }
  /* Show the current login group information */
  zLGName = login_group_name();
  if( zLGName==0 ){
    fossil_print("Not currently a part of any login-group\n");







|







 







|







2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
....
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
    nCmd = (int)strlen(zCmd);
    if( strncmp(zCmd,"join",nCmd)==0 && nCmd>=1 ){
      const char *zNewName = find_option("name",0,1);
      const char *zOther;
      char *zErr = 0;
      verify_all_options();
      if( g.argc!=4 ){
        fossil_fatal("unknown extra arguments to \"login-group join\"");
      }
      zOther = g.argv[3];
      login_group_leave(&zErr);
      sqlite3_free(zErr);
      zErr = 0;
      login_group_join(zOther,0,0,0,zNewName,&zErr);
      if( zErr ){
................................................................................
        char *zErr = 0;
        fossil_print("Leaving login-group \"%s\"\n", zLGName);
        login_group_leave(&zErr);
        if( zErr ) fossil_fatal("Oops: %s", zErr);
        return;
      }
    }else{
      fossil_fatal("unknown command \"%s\" - should be \"join\" or \"leave\"",
                   zCmd);
    }
  }
  /* Show the current login group information */
  zLGName = login_group_name();
  if( zLGName==0 ){
    fossil_print("Not currently a part of any login-group\n");

Changes to src/main.c.

326
327
328
329
330
331
332


333
334
335
336
337
338
339
...
628
629
630
631
632
633
634









635
636
637
638
639
640
641
Global g;

/*
** atexit() handler which frees up "some" of the resources
** used by fossil.
*/
static void fossil_atexit(void) {


#if USE_SEE
  /*
  ** Zero, unlock, and free the saved database encryption key now.
  */
  db_unsave_encryption_key();
#endif
#if defined(_WIN32) || defined(__BIONIC__)
................................................................................
#else
#if defined(_WIN32)
int _CRT_glob = 0x0001; /* See MinGW bug #2062 */
#endif
int main(int argc, char **argv)
#endif
{









  const char *zCmdName = "unknown";
  const CmdOrPage *pCmd = 0;
  int rc;

#if !defined(_WIN32_WCE)
  if( fossil_getenv("FOSSIL_BREAK") ){
    if( isatty(0) && isatty(2) ){







>
>







 







>
>
>
>
>
>
>
>
>







326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
...
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
Global g;

/*
** atexit() handler which frees up "some" of the resources
** used by fossil.
*/
static void fossil_atexit(void) {
  static int once = 0;
  if( once++ ) return; /* Ensure that this routine only runs once */
#if USE_SEE
  /*
  ** Zero, unlock, and free the saved database encryption key now.
  */
  db_unsave_encryption_key();
#endif
#if defined(_WIN32) || defined(__BIONIC__)
................................................................................
#else
#if defined(_WIN32)
int _CRT_glob = 0x0001; /* See MinGW bug #2062 */
#endif
int main(int argc, char **argv)
#endif
{
  return fossil_main(argc, argv);
}

/* All the work of main() is done by a separate procedure "fossil_main()".
** We have to break this out, because fossil_main() is sometimes called
** separately (by the "shell" command) but we do not want atwait() handlers
** being called by separate invocations of fossil_main().
*/
int fossil_main(int argc, char **argv){
  const char *zCmdName = "unknown";
  const CmdOrPage *pCmd = 0;
  int rc;

#if !defined(_WIN32_WCE)
  if( fossil_getenv("FOSSIL_BREAK") ){
    if( isatty(0) && isatty(2) ){

Changes to src/markdown_html.c.

431
432
433
434
435
436
437




438
439
440
441
442
443
444
445
  char *zLink = blob_buffer(link);
  char *zTitle = title!=0 && blob_size(title)>0 ? blob_str(title) : 0;
  char zClose[20];

  if( zLink==0 || zLink[0]==0 ){
    zClose[0] = 0;
  }else{  




    wiki_resolve_hyperlink(ob, 0, zLink, zClose, sizeof(zClose), 0, zTitle);
  }
  if( blob_size(content)==0 ){
    if( link ) BLOB_APPEND_BLOB(ob, link);
  }else{
    BLOB_APPEND_BLOB(ob, content);
  }
  blob_append(ob, zClose, -1);







>
>
>
>
|







431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
  char *zLink = blob_buffer(link);
  char *zTitle = title!=0 && blob_size(title)>0 ? blob_str(title) : 0;
  char zClose[20];

  if( zLink==0 || zLink[0]==0 ){
    zClose[0] = 0;
  }else{  
    static const int flags = 
       WIKI_NOBADLINKS |
       WIKI_MARKDOWNLINKS
    ;
    wiki_resolve_hyperlink(ob, flags, zLink, zClose, sizeof(zClose), 0, zTitle);
  }
  if( blob_size(content)==0 ){
    if( link ) BLOB_APPEND_BLOB(ob, link);
  }else{
    BLOB_APPEND_BLOB(ob, content);
  }
  blob_append(ob, zClose, -1);

Changes to src/util.c.

523
524
525
526
527
528
529





















































void fossil_pledge(const char *promises){
  if( pledge(promises, 0) ){
    fossil_panic("pledge(\"%s\",NULL) fails with errno=%d",
      promises, (int)errno);
  }
}
#endif /* defined(HAVE_PLEDGE) */




























































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
void fossil_pledge(const char *promises){
  if( pledge(promises, 0) ){
    fossil_panic("pledge(\"%s\",NULL) fails with errno=%d",
      promises, (int)errno);
  }
}
#endif /* defined(HAVE_PLEDGE) */

/*
** Construct a random password and return it as a string.  N is the
** recommended number of characters for the password.
**
** Space to hold the returned string is obtained from fossil_malloc()
** and should be freed by the caller.
*/
char *fossil_random_password(int N){
  char zSrc[60];
  int nSrc;
  int i;
  char z[60];

  /* Source characters for the password.  Omit characters like "0", "O",
  ** "1" and "I"  that might be easily confused */
  static const char zAlphabet[] = 
           /*  0         1         2         3         4         5       */
           /*   123456789 123456789 123456789 123456789 123456789 123456 */
              "23456789abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ";

  if( N<8 ) N = 8;
  else if( N>sizeof(zAlphabet)-2 ) N = sizeof(zAlphabet)-2;
  nSrc = sizeof(zAlphabet) - 1;
  memcpy(zSrc, zAlphabet, nSrc);

  for(i=0; i<N; i++){
    unsigned r;
    sqlite3_randomness(sizeof(r), &r);
    r %= nSrc;
    z[i] = zSrc[r];
    zSrc[r] = zSrc[--nSrc];
  }
  z[i] = 0;
  return fossil_strdup(z);
}

/*
** COMMAND: test-random-password
**
** Usage: %fossil test-random-password ?N?
**
** Generate a random password string of approximately N characters in length.
** If N is omitted, use 10.  Values of N less than 8 are changed to 8
** and greater than 55 and changed to 55.
*/
void test_random_password(void){
  int N = 10;
  if( g.argc>=3 ){
    N = atoi(g.argv[2]);
  }
  fossil_print("%s\n", fossil_random_password(N));
}

Changes to src/wiki.c.

1627
1628
1629
1630
1631
1632
1633

1634
1635
1636
1637
1638
1639
1640
** Usage: %fossil test-markdown-render FILE
**
** Render markdown wiki from FILE to stdout.
**
*/
void test_markdown_render(void){
  Blob in, out;

  verify_all_options();
  if( g.argc!=3 ) usage("FILE");
  blob_zero(&out);
  blob_read_from_file(&in, g.argv[2], ExtFILE);
  markdown_to_html(&in, 0, &out);
  blob_write_to_file(&out, "-");
}







>







1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
** Usage: %fossil test-markdown-render FILE
**
** Render markdown wiki from FILE to stdout.
**
*/
void test_markdown_render(void){
  Blob in, out;
  db_find_and_open_repository(OPEN_OK_NOT_FOUND|OPEN_SUBSTITUTE,0);
  verify_all_options();
  if( g.argc!=3 ) usage("FILE");
  blob_zero(&out);
  blob_read_from_file(&in, g.argv[2], ExtFILE);
  markdown_to_html(&in, 0, &out);
  blob_write_to_file(&out, "-");
}

Changes to src/wikiformat.c.

28
29
30
31
32
33
34

35
36
37
38
39
40
41
....
1209
1210
1211
1212
1213
1214
1215
1216

1217
1218

1219
1220
1221
1222
1223
1224
1225

1226
1227
1228
1229
1230
1231
1232
....
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304

1305
1306
1307
1308
1309
1310









1311
1312




1313
1314

1315
1316
1317
1318
1319
1320
1321
....
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
....
1788
1789
1790
1791
1792
1793
1794

1795
1796
1797
1798
1799
1800
1801
#define WIKI_HTMLONLY       0x001  /* HTML markup only.  No wiki */
#define WIKI_INLINE         0x002  /* Do not surround with <p>..</p> */
#define WIKI_NOBLOCK        0x004  /* No block markup of any kind */
#define WIKI_BUTTONS        0x008  /* Allow sub-menu buttons */
#define WIKI_NOBADLINKS     0x010  /* Ignore broken hyperlinks */
#define WIKI_LINKSONLY      0x020  /* No markup.  Only decorate links */
#define WIKI_NEWLINE        0x040  /* Honor \n - break lines at each \n */

#endif


/*
** These are the only markup attributes allowed.
*/
enum allowed_attr_t {
................................................................................
** "History" permission.
**
**    [http://www.fossil-scm.org/]
**    [https://www.fossil-scm.org/]
**    [ftp://www.fossil-scm.org/]
**    [mailto:fossil-users@lists.fossil-scm.org]
**
**    [/path]

**
**    [./relpath]

**
**    [WikiPageName]
**    [wiki:WikiPageName]
**
**    [0123456789abcdef]
**
**    [#fragment]

**
**    [2010-02-27 07:13]
*/
void wiki_resolve_hyperlink(
  Blob *pOut,             /* Write the HTML output here */
  int mFlags,             /* Rendering option flags */
  const char *zTarget,    /* Hyperlink target; text within [...] */
................................................................................
      }
    }else if( g.perm.Hyperlink ){
      blob_appendf(pOut, "%z[",xhref(zExtraNS, "%R/info/%s", zTarget));
      zTerm = "]</a>";
    }else{
      zTerm = "";
    }
  }else if( strlen(zTarget)>=10 && fossil_isdigit(zTarget[0]) && zTarget[4]=='-'
            && db_int(0, "SELECT datetime(%Q) NOT NULL", zTarget) ){
    blob_appendf(pOut, "<a href=\"%R/timeline?c=%T\"%s>", zTarget, zExtra);
  }else if( (z = validWikiPageName(mFlags, zTarget))!=0 ){

    const char *zOverride = wiki_is_overridden(zTarget);
    if( zOverride ){
      blob_appendf(pOut, "<a href=\"%R/info/%S\"%s>", zOverride, zExtra);
    }else{
      blob_appendf(pOut, "<a href=\"%R/wiki?name=%T\"%s>", z, zExtra);
    }









  }else if( zOrig && zTarget>=&zOrig[2] && !fossil_isspace(zTarget[-2]) ){
    /* Probably an array subscript in code */




    zTerm = "";
  }else if( (mFlags & (WIKI_NOBADLINKS|WIKI_LINKSONLY))!=0 ){

    zTerm = "";
  }else{
    blob_appendf(pOut, "<span class=\"brokenlink\">[%h]", zTarget);
    zTerm = "</span>";
  }
  if( zExtra ) fossil_free(zExtra);
  assert( strlen(zTerm)<nClose );
................................................................................
  while( renderer.nStack ){
    popStack(&renderer);
  }
  blob_append(renderer.pOut, "\n", 1);
  free(renderer.aStack);
}

/*
** Send a string as wiki to CGI output.
*/
void wiki_write(const char *zIn, int flags){
  Blob in;
  blob_init(&in, zIn, -1);
  wiki_convert(&in, 0, flags);
  blob_reset(&in);
}

/*
** COMMAND: test-wiki-render
**
** Usage: %fossil test-wiki-render FILE [OPTIONS]
**
** Options:
**    --buttons        Set the WIKI_BUTTONS flag
................................................................................
  int flags = 0;
  if( find_option("buttons",0,0)!=0 ) flags |= WIKI_BUTTONS;
  if( find_option("htmlonly",0,0)!=0 ) flags |= WIKI_HTMLONLY;
  if( find_option("linksonly",0,0)!=0 ) flags |= WIKI_LINKSONLY;
  if( find_option("nobadlinks",0,0)!=0 ) flags |= WIKI_NOBADLINKS;
  if( find_option("inline",0,0)!=0 ) flags |= WIKI_INLINE;
  if( find_option("noblock",0,0)!=0 ) flags |= WIKI_NOBLOCK;

  verify_all_options();
  if( g.argc!=3 ) usage("FILE");
  blob_zero(&out);
  blob_read_from_file(&in, g.argv[2], ExtFILE);
  wiki_convert(&in, &out, flags);
  blob_write_to_file(&out, "-");
}







>







 







|
>


>

|
<



|
>







 







<
<
<

>






>
>
>
>
>
>
>
>
>
|
<
>
>
>
>


>







 







<
<
<
<
<
<
<
<
<
<







 







>







28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
....
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223

1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
....
1297
1298
1299
1300
1301
1302
1303



1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321

1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
....
1770
1771
1772
1773
1774
1775
1776










1777
1778
1779
1780
1781
1782
1783
....
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
#define WIKI_HTMLONLY       0x001  /* HTML markup only.  No wiki */
#define WIKI_INLINE         0x002  /* Do not surround with <p>..</p> */
#define WIKI_NOBLOCK        0x004  /* No block markup of any kind */
#define WIKI_BUTTONS        0x008  /* Allow sub-menu buttons */
#define WIKI_NOBADLINKS     0x010  /* Ignore broken hyperlinks */
#define WIKI_LINKSONLY      0x020  /* No markup.  Only decorate links */
#define WIKI_NEWLINE        0x040  /* Honor \n - break lines at each \n */
#define WIKI_MARKDOWNLINKS  0x080  /* Resolve hyperlinks as in markdown */
#endif


/*
** These are the only markup attributes allowed.
*/
enum allowed_attr_t {
................................................................................
** "History" permission.
**
**    [http://www.fossil-scm.org/]
**    [https://www.fossil-scm.org/]
**    [ftp://www.fossil-scm.org/]
**    [mailto:fossil-users@lists.fossil-scm.org]
**
**    [/path]        ->  Refers to the root of the Fossil hierarchy, not
**                       the root of the URI domain
**
**    [./relpath]
**    [../relpath]
**
**    [#fragment]

**
**    [0123456789abcdef]
**
**    [WikiPageName]
**    [wiki:WikiPageName]
**
**    [2010-02-27 07:13]
*/
void wiki_resolve_hyperlink(
  Blob *pOut,             /* Write the HTML output here */
  int mFlags,             /* Rendering option flags */
  const char *zTarget,    /* Hyperlink target; text within [...] */
................................................................................
      }
    }else if( g.perm.Hyperlink ){
      blob_appendf(pOut, "%z[",xhref(zExtraNS, "%R/info/%s", zTarget));
      zTerm = "]</a>";
    }else{
      zTerm = "";
    }



  }else if( (z = validWikiPageName(mFlags, zTarget))!=0 ){
    /* The link is to a valid wiki page name */
    const char *zOverride = wiki_is_overridden(zTarget);
    if( zOverride ){
      blob_appendf(pOut, "<a href=\"%R/info/%S\"%s>", zOverride, zExtra);
    }else{
      blob_appendf(pOut, "<a href=\"%R/wiki?name=%T\"%s>", z, zExtra);
    }
  }else if( strlen(zTarget)>=10 && fossil_isdigit(zTarget[0]) && zTarget[4]=='-'
            && db_int(0, "SELECT datetime(%Q) NOT NULL", zTarget) ){
    /* Dates or date-and-times in ISO8610 resolve to a link to the
    ** timeline for that date */
    blob_appendf(pOut, "<a href=\"%R/timeline?c=%T\"%s>", zTarget, zExtra);
  }else if( mFlags & WIKI_MARKDOWNLINKS ){
    /* If none of the above, and if rendering links for markdown, then
    ** create a link to the literal text of the target */
    blob_appendf(pOut, "<a href=\"%h\"%s>", zTarget, zExtra);
  }else if( zOrig && zTarget>=&zOrig[2]

        && zTarget[-1]=='[' && !fossil_isspace(zTarget[-2]) ){
    /* If the hyperlink markup is not preceded by whitespace, then it
    ** is probably a C-language subscript or similar, not really a
    ** hyperlink.  Just ignore it. */
    zTerm = "";
  }else if( (mFlags & (WIKI_NOBADLINKS|WIKI_LINKSONLY))!=0 ){
    /* Also ignore the link if various flags are set */
    zTerm = "";
  }else{
    blob_appendf(pOut, "<span class=\"brokenlink\">[%h]", zTarget);
    zTerm = "</span>";
  }
  if( zExtra ) fossil_free(zExtra);
  assert( strlen(zTerm)<nClose );
................................................................................
  while( renderer.nStack ){
    popStack(&renderer);
  }
  blob_append(renderer.pOut, "\n", 1);
  free(renderer.aStack);
}











/*
** COMMAND: test-wiki-render
**
** Usage: %fossil test-wiki-render FILE [OPTIONS]
**
** Options:
**    --buttons        Set the WIKI_BUTTONS flag
................................................................................
  int flags = 0;
  if( find_option("buttons",0,0)!=0 ) flags |= WIKI_BUTTONS;
  if( find_option("htmlonly",0,0)!=0 ) flags |= WIKI_HTMLONLY;
  if( find_option("linksonly",0,0)!=0 ) flags |= WIKI_LINKSONLY;
  if( find_option("nobadlinks",0,0)!=0 ) flags |= WIKI_NOBADLINKS;
  if( find_option("inline",0,0)!=0 ) flags |= WIKI_INLINE;
  if( find_option("noblock",0,0)!=0 ) flags |= WIKI_NOBLOCK;
  db_find_and_open_repository(OPEN_OK_NOT_FOUND|OPEN_SUBSTITUTE,0);
  verify_all_options();
  if( g.argc!=3 ) usage("FILE");
  blob_zero(&out);
  blob_read_from_file(&in, g.argv[2], ExtFILE);
  wiki_convert(&in, &out, flags);
  blob_write_to_file(&out, "-");
}

Changes to www/defcsp.md.

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
37
38
39
40
41
42
43
44
45
46
47



48
49
50
51
52
53
54
55
56
57
58

59
60
61




62
63





64
65
66



67


68
69
70






71
72
73
















74
75
76
77
78


79
80
81
82
83
84
85
86


87














88
89
90
91
92
93
94
95



96
97
98
99
100
101

































102
103
104
105
106
107
108
...
153
154
155
156
157
158
159

160
161
162
163
164
165
166
...
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
# The Default Content Security Policy (CSP)

When Fossil’s web interface generates an HTML page, it
normally includes a [Content Security Policy][csp] (CSP)
in the `<head>`.
The CSP tells the browser what types of content (HTML, image, CSS,
JavaScript...) the document may reference and from where the

content may be sourced.


CSP is a security measure designed to prevent [cross-site scripting][xss]
(XSS) and other similar code injection attacks.
The CSP defines a “white list” of content types and origins that
are considered safe.  Any references to resources that are not
on the white list are ignored.





If Fossil were perfect and bug-free and never allowed any kind of
code injection on the pages it generates, then the CSP would not
be useful.  The Fossil developers are not aware of any defects
in Fossil that allow code injection, and will promptly fix any defects 
that are brought to their attention.  Lots of eyeballs are looking at
Fossil to find problems in the code, and the Fossil build process uses
custom static analysis techniques to help identify code injection problems

at compile-time.  Nevertheless, problems do sometimes (rarely) slip
through.  The CSP serves as a final line of defense, preventing
code injection defects in Fossil from turning into actual
vulnerabilities.










Fossil site administrators can [modify the default CSP](#override), perhaps
to add trusted external sources for auxiliary content.  But for maximum
safety, site developers are encouraged to work within the restrictions
imposed by the default CSP and avoid the temptation to relax the CSP
unless they fully understand the security implications of what they are
doing.




## The Default Restrictions

The Fossil default CSP declares the following content restrictions:


### <a name="base"></a> default-src 'self' data:

This policy means mixed-origin content isn’t allowed, so you can’t refer to
resources (images, style-sheets, and scripts) on other web domains.
Hence the following Markdown for an inline
image hosted on another site will cause a CSP error:

         ![fancy 3D Fossil logotype](https://i.imgur.com/HalpMgt.png)




The default policy does allows inline `data:` URIs, which means you could
[data-encode][de] your image content and put it inline within the
document:

         ![small inline image](data:image/gif;base64,R0lGODlh...)

That method is best used for fairly small resources. Large `data:` URIs
are hard to read and edit. Keep in mind that if you put such a thing
into a Fossil forum post, anyone subscribed to email alerts will get a
copy of the raw URI text, which is really ugly.


For larger images in [embedded documentation](./embeddeddoc.wiki) you
store the image as a separate file in the Fossil repository and reference




it via a relative URI.






         ![large inline image](./inlineimage.jpg)

Any content from the same domain as the Fossil repository will work fine.



So if the Fossil repository is but one path in a larger website, it will


be able reference other static resources within that same website.  It
can also reference [unversioned content](./unvers.wiki).  However, as
unversioned content and content outside of the Fossil repository itself






will not be transferred by [sync](/help?cmd=sync), the references probably
will not work in clones of your repository.

















### <a name="style"></a> style-src 'self' 'unsafe-inline'

This policy allows CSS information to come from separate files in the
same domain of the Fossil server, or for CSS to be embedded inline within
the document text.



The `'unsafe-inline'` element means that an injection vulnerability in
Fossil would allow an attacker to modify the CSS for a Fossil-generated
page.  This is not ideal, but nor is it as dangerous as allowing
injected javascript to run, and Fossil uses of in-line CSS
for things like setting background colors in timelines and defining
line widths in bar graphs on the [Activity Reports](/reports) page, 
so it seems like in-line CSS is a necessary compromise at this time.

















### <a name="script"></a> script-src 'self' 'nonce-%s'

This policy disables in-line javascript and only allows `<script>`
elements if the `<script>` includes a `nonce=` attribute the
matches the %s section of the CSP.  Fossil provides a different
random nonce for every page it generates, and since an attacker has
no way of predicting what that nonce will be, the attacker is unable
to inject working javascript.




For documents generated by the [CGI extensions](./serverext.wiki), the
value of the nonce is accessible in the FOSSIL_NONCE environment variable.
TH1 scripts that run while generating the header or footer can access
the nonce in the $nonce variable.  The JavaScript section of a
[custom skin][cs] automatically includes the appropriate nonce.


































#### <a name="xss"></a>Cross-Site Scripting via Ordinary User Capabilities

We’re so restrictive about how we treat JavaScript because it can lead
to difficult-to-avoid scripting attacks. If we used the same CSP for
`<script>` tags [as for `<style>` tags](#style), anyone with check-in
rights on your repository could add a JavaScript file to your repository
................................................................................
JavaScript but not those allowed to file tickets, append to wiki
articles, etc., you might justify enabling TH1 docs on your repository,
since the only way to create or modify HTML-formatted embedded docs is
through check-ins.

[ed]:   ./embeddeddoc.wiki
[edtf]: ./embeddeddoc.wiki#th1

[fp]:   ./forum.wiki
[hfed]: ./embeddeddoc.wiki#html
[tkt]:  ./tickets.wiki
[tn]:   ./event.wiki
[wiki]: ./wikitheory.wiki

## <a name="override"></a>Replacing the Default CSP
................................................................................
instead as described in the custom skinning guide. Alternately, you can
[make use of `$default_csp`](#th1).

This then tells you one way to override Fossil’s default CSP: provide
your own HTML header in a custom skin.

A useful combination is to entirely override the default CSP in the skin
but then provide a new CSP [in the front-end proxy layer](./server/)
using any of the many reverse proxy servers that can define custom HTTP
headers.


------------


**Asides and Digressions:**

1.  There is actually a third context that can correctly insert this
    nonce attribute: [a CGI server extension](./serverext.wiki), by use of
    the `FOSSIL_NONCE` variable sent to the CGI by Fossil.

2.  The stock Bootstrap skin does actually include a `<head>` tag, but
    from Fossil 2.7 through Fossil 2.9, it just repeated the same CSP
    text that Fossil’s C code inserts into the HTML header for all other
    stock skins. With Fossil 2.10, the stock Bootstrap skin uses
    `$default_csp` instead, so you can [override it as above](#th1).


[cs]:    ./customskin.md
[csp]:   https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP
[de]:    https://dopiaza.org/tools/datauri/index.php
[xss]:   https://en.wikipedia.org/wiki/Cross-site_scripting
[xssci]: https://fossil-scm.org/forum/forumpost/e7c386b21f


|
|
<
|
|
>
|
>

<
|
|
|
|
>
>
>
>

<
<
<
<
|
|
<
>
|
|
|
|
>
>

>
>
>
>
>
>
>






>
>
>








|
|
|
<


>
>
>








|
|
|
>

<
|
>
>
>
>
|

>
>
>
>
>


<
>
>
>
|
>
>
|
<
<
>
>
>
>
>
>
|
<

>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>


|
<
<
>
>

<
<
<
<
<
<
<
>
>

>
>
>
>
>
>
>
>
>
>
>
>
>
>


|
|
<
<
<
<
>
>
>

<
<
<
<
<
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







 







>







 







|









|
|
|












<
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
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74

75
76
77
78
79
80
81
82
83
84
85
86
87
88

89
90
91
92
93
94
95


96
97
98
99
100
101
102

103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122


123
124
125







126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146




147
148
149
150





151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
...
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
...
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332

# The Default Content Security Policy (CSP)

When Fossil’s web interface generates an HTML page, it normally includes
a [Content Security Policy][csp] (CSP) in the `<head>`.  The CSP defines

a “white list” to tell the browser what types of content (HTML, images,
CSS, JavaScript...) the document may reference and the sources the
browser is allowed to pull such content from. The aim is to prevent
certain classes of [cross-site scripting][xss] (XSS) and code injection
attacks.  The browser will not pull content types disallowed by the CSP.


Fossil has built-in server-side content filtering logic. For example, it
purposely breaks `<script>` tags when it finds them in Markdown and
Fossil Wiki documents. (But not in [HTML-formatted embedded
docs][hfed]!) We also back that with multiple levels of analysis and
checks to find and fix content security problems: compile-time static
analysis, run-time dynamic analysis, and manual code inspection. Fossil
is open source software, so it benefits from the “[many
eyeballs][llaw],” limited by the size of its developer community.





However, there is a practical limit to the power of server-side
filtering and code quality practices.


First, there is an endless battle between those looking for clever paths
around such barriers and those erecting the barriers. The developers of
Fossil are committed to holding up our end of that fight, but this is,
to some extent, a reactive posture. It is cold comfort if Fossil’s
developers react quickly to a report of code injection — as we do! — if
the bad guys learn of it and start exploiting it first.

Second, Fossil has purposefully powerful features that are inherently
difficult to police from the server side: HTML [in wiki](/wiki_rules)
and [in Markdown](/md_rules) docs, [TH1 docs](./th1.md), etc.

Fossil’s strong default CSP adds client-side filtering to backstop our
server-side measures.

Fossil site administrators can [modify the default CSP](#override), perhaps
to add trusted external sources for auxiliary content.  But for maximum
safety, site developers are encouraged to work within the restrictions
imposed by the default CSP and avoid the temptation to relax the CSP
unless they fully understand the security implications of what they are
doing.

[llaw]: https://en.wikipedia.org/wiki/Linus%27s_Law


## The Default Restrictions

The Fossil default CSP declares the following content restrictions:


### <a name="base"></a> default-src 'self' data:

This policy means mixed-origin content isn’t allowed, so you can’t refer
to resources on other web domains. Browsers will ignore a link like the
one in the following Markdown under our default CSP:


         ![fancy 3D Fossil logotype](https://i.imgur.com/HalpMgt.png)

If you look in the browser’s developer console, you should see a CSP
error when attempting to render such a page.

The default policy does allows inline `data:` URIs, which means you could
[data-encode][de] your image content and put it inline within the
document:

         ![small inline image](data:image/gif;base64,R0lGODlh...)

That method is best used for fairly small resources. Large `data:` URIs
are hard to read and edit. There are secondary problems as well: if you
put a large image into a Fossil forum post this way, anyone subscribed
to email alerts will get a copy of the raw URI text, which can amount to
pages and pages of [ugly Base64-encoded text][b64].


Fossil offers several alternatives for serving large content resources
from within the repository:

*   **versioned content** via [`/raw`](/help?cmd=/raw)
*   **[unversioned content](./unvers.wiki)** via [`/uv`](/help?cmd=/uv)
*   **relative links**

Only the first two options work in [wiki articles][wiki],
[tickets][tkt], [forum posts][fp], and [tech notes][tn].  The last
option is a much simpler alternative, but it only works within [embedded
documentation][ed]:

         ![large inline image](./inlineimage.jpg)


Because all of these methods pull content from within the Fossil
repository, they all count as “self” for the purposes of the CSP.

This rule also works when the Fossil repository is but one path in a
larger website. The browser can’t distinguish Fossil-served content from
that served by the rest of the same web domain, so your repository can
refer to other resources within that same web site, whether they are


static files served by [an HTTP proxy in front of Fossil][svr], by
another Fossil repository served under that same domain, or dynamic
content served by, say, a PHP app on that same site.

Beware that there are a number of problems that come up with using such
out-of-repository resources, which all stem from the fact that they
aren’t included in a [sync](/help?cmd=sync):


1.  Relative links break in `fossil ui` when run on a clone.

2.  Absolute links break under certain types of failover and
    load-balancing schemes.

3.  Absolute links fail when one’s purpose in using a clone is to
    recover from the loss of a project web site by standing that clone
    up [as a server][svr] elsewhere.

You can avoid all of these problems by referring to in-repo resources
exclusively.

[b64]: https://en.wikipedia.org/wiki/Base64
[svr]: ./server/


### <a name="style"></a> style-src 'self' 'unsafe-inline'

This policy allows CSS information to come from separate files hosted


under the Fossil repo server’s Internet domain, or for CSS to be
embedded within `<style>` tags within the document text.








The `'unsafe-inline'` declaration excludes CSS within individual HTML
elements:

        <p style="margin-left: 4em">Indented text.</p>

Because this policy is weaker than [our default for script
elements](#script), there is the potential for an atacker to modify a
Fossil-generated page via CSS. While such page modifications are not as
dangerous as injected JavaScript, the real reason we allow it is that
Fossil still emits in-page `<style>` blocks in a few places. Over time,
we may work out ways to avoid each of these, which will eventually allow
us to tighten this CSP rule down to match the `script` rule. We
recommend that you do your own CSS modifications [via the skin][cs]
rather than depend on the ability to insert `<script>` blocks into
individual pages.


### <a name="script"></a> script-src 'self' 'nonce-%s'

This policy disables in-line JavaScript and only allows `<script>`
elements if the `<script>` includes a `nonce` attribute that matches the




one declared by the CSP. That nonce is a large random number, unique for
each HTTP page generated by Fossil, so an attacker cannot guess the
value, so the browser will ignore an attacker’s injected JavaScript.






That nonce can only come from one of three sources, all of which should
be protected at the system administration level on the Fossil server:

*   **Fossil server C code:** All code paths in Fossil that emit
    `<script>` elements include the `nonce` attribute. There are several
    cases, such as the “JavaScript” section of a [custom skin][cs].
    That text is currently inserted into each HTML page generated by
    Fossil,¹ which means it needs to include a `nonce` attribute to
    allow it to run under this default CSP.  We consider JavaScript
    emitted via these paths to be safe because it’s audited by the
    Fossil developers. We assume that you got your Fossil server’s code
    from a trustworthy source and that an attacker cannot replace your
    Fossil server binary.

*   **TH1 code:** The Fossil TH1 interpreter pre-defines the [`$nonce`
    variable](./th1.md#nonce) for use in [custom skins][cs].  For
    example, some of the stock skins that ship with Fossil include a
    wall clock feature up in the corner that updates once a minute.
    These paths are safe in the default Fossil configuration because
    only the [all-powerful Setup user][su] can write TH1 code that
    executes in the server’s running context.

    There is, however, [a default-disabled path](#xss) to beware of,
    covered in the next section.

*   **[CGI server extensions][ext]:** Fossil exports the nonce to the
    CGI in the `FOSSIL_NONCE` environment variable, which it can then
    use in `<script>` elements it generates. Because these extensions
    can only be installed by the Fossil server’s system administrator,
    this path is also considered safe.

[su]: ./admin-v-setup.md


#### <a name="xss"></a>Cross-Site Scripting via Ordinary User Capabilities

We’re so restrictive about how we treat JavaScript because it can lead
to difficult-to-avoid scripting attacks. If we used the same CSP for
`<script>` tags [as for `<style>` tags](#style), anyone with check-in
rights on your repository could add a JavaScript file to your repository
................................................................................
JavaScript but not those allowed to file tickets, append to wiki
articles, etc., you might justify enabling TH1 docs on your repository,
since the only way to create or modify HTML-formatted embedded docs is
through check-ins.

[ed]:   ./embeddeddoc.wiki
[edtf]: ./embeddeddoc.wiki#th1
[ext]:  ./serverext.wiki
[fp]:   ./forum.wiki
[hfed]: ./embeddeddoc.wiki#html
[tkt]:  ./tickets.wiki
[tn]:   ./event.wiki
[wiki]: ./wikitheory.wiki

## <a name="override"></a>Replacing the Default CSP
................................................................................
instead as described in the custom skinning guide. Alternately, you can
[make use of `$default_csp`](#th1).

This then tells you one way to override Fossil’s default CSP: provide
your own HTML header in a custom skin.

A useful combination is to entirely override the default CSP in the skin
but then provide a new CSP [in the front-end proxy layer][svr]
using any of the many reverse proxy servers that can define custom HTTP
headers.


------------


**Asides and Digressions:**

1.  Fossil might someday switch to serving the “JavaScript” section of a
    custom skin as a virtual text file, allowing it to be cached by the
    browser, reducing page load times.

2.  The stock Bootstrap skin does actually include a `<head>` tag, but
    from Fossil 2.7 through Fossil 2.9, it just repeated the same CSP
    text that Fossil’s C code inserts into the HTML header for all other
    stock skins. With Fossil 2.10, the stock Bootstrap skin uses
    `$default_csp` instead, so you can [override it as above](#th1).


[cs]:    ./customskin.md
[csp]:   https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP
[de]:    https://dopiaza.org/tools/datauri/index.php
[xss]:   https://en.wikipedia.org/wiki/Cross-site_scripting

Changes to www/server/any/althttpd.md.

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
37

# Serving via althttpd

The public SQLite and Fossil web sites are not purely served by Fossil
for two reasons:

1.  We want access to these sites to be secured with TLS, which we do
    [via `stunnel`](./stunnel.md).

2.  Parts of these web sites are static, stored as plain files on disk,
    not as Fossil artifacts. We serve such files using a separate web
    server called [`althttpd`][ah], written by the primary author of
    both SQLite and Fossil, D. Richard Hipp. `althttpd` is a lightweight
    HTTP-only web server. It handles the static HTTP hits on
    <tt>sqlite.org</tt> and <tt>fossil-scm.org</tt>, delegating HTTPS
    hits to `stunnel` and dynamic content hits to Fossil [via
    CGI][cgi].

The largest single chunk of static content served directly by `althttpd`
rather than via Fossil is the [SQLite documentation][sd], which is built
[from source files][ds]. We don’t want those output files stored in
Fossil; we already keep that process’s *input* files in Fossil. Thus the
choice to serve the output statically.

In addition to the [server’s documentation page][ah], there is a large,
helpful header comment in the server’s [single-file C
implementation][ac]. Between that and the generic [Serving via CGI][cgi]
docs, you should be able to figure out how to serve Fossil via
`althttpd`.









*[Return to the top-level Fossil server article.](../)*


[ac]:  https://sqlite.org/docsrc/file/misc/althttpd.c
[ah]:  https://sqlite.org/docsrc/doc/trunk/misc/althttpd.md
[cgi]: ./cgi.md
[ds]:  https://sqlite.org/docsrc/
[sd]:  https://sqlite.org/docs.html



|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
>
>
>
>
>
>
>
>




<
|
<
<
<
>
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
37
38
39
40

41



42
# Serving via althttpd

[Althttpd][althttpd]
is a light-weight web server that has been used to implement the SQLite and
Fossil websites for well over a decade. Althttpd strives for simplicity,
security, ease of configuration, and low resource usage.

To set up a Fossil server as CGI on a host running the althttpd web
server, follow these steps.
<ol>
<li<p>Get the althttpd webserver running on the host.  This is easily
done by following the [althttpd documentation][althttpd].

<li><p>Create a CGI script for your Fossil respository.  The script will
be typically be two lines of code that look something like this:

~~~
    #!/usr/bin/fossil
    repository: /home/yourlogin/fossils/project.fossil
~~~

Modify the filenames to conform to your system, of course.  The
CGI script accepts [other options][cgi] besides the
repository:" line.  You can add in other options as you desire,
but the single "repository:" line is normally all that is needed
to get started.

<li><p>Make the CGI script executable.

<li><p>Verify that the fossil repository file and the directory that contains
the repository are both writable by whatever user the web server is
running and.
</ol>

And you are done.  Visit the URL that corresponds to the CGI script
you created to start using your Fossil server.

*[Return to the top-level Fossil server article.](../)*



[althttpd]:  https://sqlite.org/docsrc/doc/trunk/misc/althttpd.md



[cgi]:       ../../cgi.wiki

Changes to www/server/any/scgi.md.

7
8
9
10
11
12
13
14
15

16
17
18
19
20

21






22




23
24
25
26
27
28
29
30
..
32
33
34
35
36
37
38
39
40
41
42
43

44
45
46
47

48
49


50

51
52
53
54
55
56


server will speak the SCGI protocol rather than raw HTTP.

This can be used with a web server such as [nginx](http://nginx.org)
which does not support [Fossil’s CGI mode](./cgi.md).

A basic nginx configuration to support SCGI with Fossil looks like this:

        location /example/ {
            include scgi_params;

            scgi_pass localhost:9000;
            scgi_param SCRIPT_NAME "/example";
            scgi_param HTTPS "on";
        }


Start Fossil so that it will respond to nginx’s SCGI calls like this:











        fossil server /path/to/repo.fossil --scgi --localhost --port 9000

The `--scgi` option switches Fossil into SCGI mode from its default,
which is [stand-alone HTTP server mode](./none.md). All of the other
options discussed in that linked document — such as the ability to serve
a directory full of Fossil repositories rather than just a single
repository — work the same way in SCGI mode.

................................................................................
expose Fossil service to the outside world, so there is no good reason
to allow outsiders to contact this Fossil SCGI server directly.

Giving an explicit non-default TCP port number via `--port` is a good
idea to avoid conflicts with use of Fossil’s default TCP service port,
8080, which may conflict with local uses of `fossil ui` and such.

Fossil requires the `SCRIPT_NAME` environment variable in order to
function properly, but nginx does not provide this variable by default,
so it is necessary to provide it in the configuration.  Failure to do
this will cause Fossil to return an error.


The [example `fslsrv` script](/file/tools/fslsrv) shows off these same
concepts in a more complicated setting. You might want to mine that
script for ideas.


You might want to next read one of the platform-specific versions of this
document, which goes into more detail:




*   [Debian/Ubuntu](../debian/nginx.md)

There is a [separate article](../../tls-nginx.md) showing how to add TLS
encryption to this basic SCGI + nginx setup.

*[Return to the top-level Fossil server article.](../)*









|

>

<
<


>
|
>
>
>
>
>
>

>
>
>
>
|







 







|
|
|
|
<
>
|
|
<

>
|
|
>
>

>
|
<
|
|


>
>
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
37
38
39
40
..
42
43
44
45
46
47
48
49
50
51
52

53
54
55

56
57
58
59
60
61
62
63
64

65
66
67
68
69
70
server will speak the SCGI protocol rather than raw HTTP.

This can be used with a web server such as [nginx](http://nginx.org)
which does not support [Fossil’s CGI mode](./cgi.md).

A basic nginx configuration to support SCGI with Fossil looks like this:

        location /code/ {
            include scgi_params;
            scgi_param SCRIPT_NAME "/code";
            scgi_pass localhost:9000;


        }

The `scgi_params` file comes with nginx, and it simply translates nginx
internal variables to `scgi_param` directives to create SCGI environment
variables for the proxied program; in this case, Fossil. Our explicit
`scgi_param` call to define `SCRIPT_NAME` adds one more variable to this
set, which is necessary for this configuration to work properly, because
our repo isn’t at the root of the URL hierarchy. Without it, when Fossil
generates absolute URLs, they’ll be missing the `/code` part at the
start, which will typically cause [404 errors][404].

The final directive simply tells nginx to proxy all calls to URLs under
`/code` down to an SCGI program on TCP port 9000. We can temporarily
set Fossil up as a server on that port like so:

        $ fossil server /path/to/repo.fossil --scgi --localhost --port 9000 &

The `--scgi` option switches Fossil into SCGI mode from its default,
which is [stand-alone HTTP server mode](./none.md). All of the other
options discussed in that linked document — such as the ability to serve
a directory full of Fossil repositories rather than just a single
repository — work the same way in SCGI mode.

................................................................................
expose Fossil service to the outside world, so there is no good reason
to allow outsiders to contact this Fossil SCGI server directly.

Giving an explicit non-default TCP port number via `--port` is a good
idea to avoid conflicts with use of Fossil’s default TCP service port,
8080, which may conflict with local uses of `fossil ui` and such.

We characterized the SCGI service start command above as “temporary”
because running Fossil in the background like that means it won’t start
back up on a reboot of the server. A simple solution to that is to add
that command to `/etc/rc.local` on systems that have it. However, you

might want to consider setting Fossil up as an OS service instead, so
that you get the benefits of the platform’s service management
framework:


*   [Linux (systemd)](../debian/service.md)
*   [Windows service](../windows/service.md)
*   [macOS (launchd)](../macos/service.md)
*   [xinetd](../any/xinetd.md)
*   [inetd](../any/inetd.md)

We go into more detail on nginx service setup with Fossil in our
[Debian/Ubuntu specific guide](../debian/nginx.md). Then in [a later

article](../../tls-nginx.md) that builds upon that, we show how to add
TLS encryption to this basic SCGI + nginx setup on Debian type OSes.

*[Return to the top-level Fossil server article.](../)*

[404]: https://en.wikipedia.org/wiki/HTTP_404

Changes to www/server/debian/nginx.md.

64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
...
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122

123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184





185
186
187
188
189
190
191
192
193
194
195
196
197

198
199
200
201
202
203
204
205
206
207
208
209
210
211
...
219
220
221
222
223
224
225
226
227
228
229
























230

## <a name="modes"></a>Fossil Service Modes

Fossil provides four major ways to access a repository it’s serving
remotely, three of which are straightforward to use with nginx:

*   **HTTP** — Fossil has a built-in HTTP server: [`fossil
    server`](/help/server).  While this method is efficient and it’s
    possible to use nginx to 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.
................................................................................
your server, then say:

       $ sudo apt install fossil nginx


## <a name="scgi"></a>Running Fossil in SCGI Mode

I run my Fossil SCGI server instances with a variant of [the `fslsrv`
shell script](/file/tools/fslsrv) currently hosted in the Fossil source
code repository. You’ll want to download that and make a copy of it, so
you can customize it to your particular needs.

This script allows running multiple Fossil SCGI servers, one per
repository, each bound to a different high-numbered `localhost` port, so
that only nginx can see and proxy them out to the public.  The
“`example`” repo is on TCP port localhost:12345, and the “`foo`” repo is
on localhost:12346.


As written, the `fslsrv` script expects repositories to be stored in the
calling user’s home directory under `~/museum`, because where else do
you keep Fossils?

That home directory also needs to have a directory to hold log files,
`~/log/fossil/*.log`. Fossil doesn’t put out much logging, but when it
does, it’s better to have it captured than to need to re-create the
problem after the fact.

The use of `--baseurl` in this script lets us have each Fossil
repository mounted in a different location in the URL scheme.  Here, for
example, we’re saying that the “`example`” repository is hosted under
the `/code` URI on its domains, but that the “`foo`” repo is hosted at
the top level of its domain.  You’ll want to do something like the
former for a Fossil repo that’s just one piece of a larger site, but the
latter for a repo that is basically the whole point of the site.

You might also want another script to automate the update, build, and
deployment steps for new Fossil versions:

       #!/bin/sh
       cd $HOME/src/fossil/trunk
       fossil up
       make -j11
       killall fossil
       sudo make install
       fslsrv

The `killall fossil` step is needed only on OSes that refuse to let you
replace a running binary on disk.

As written, the `fslsrv` script assumes a Linux environment.  It expects
`/bin/bash` to exist, and it depends on non-POSIX tools like `pgrep`.
It should not be difficult to port to systems like macOS or the BSDs.


## <a name="config"></a>Configuration

On Debian and Ubuntu systems the primary user-level configuration file
for nginx is `/etc/nginx/sites-enabled/default`. I recommend that this
file contain only a list of include statements, one for each site that
server hosts:

      include local/example
      include local/foo

Those files then each define one domain’s configuration.  Here,
`/etc/nginx/local/example` contains the configuration for
`*.example.com` and `*.example.net`; and `local/foo` contains the
configuration for `*.foo.net`.

The configuration for our `foo.net` web site, stored in
`/etc/nginx/sites-enabled/local/foo` is:

      server {
          server_name .foo.net;
          include local/generic;

          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 "";
          }
      }

As you can see, this is a simple extension of [the basic nginx service
configuration for SCGI][scgii], showing off a few ideas you might want to
try on your own site, such as static asset proxying.

The `local/generic` file referenced above helps us reduce unnecessary
repetition among the multiple sites this configuration hosts:

      root /var/www/$host;
................................................................................
variables into, citing performance considerations, so there is a limit
to how much repetition you can squeeze out this way. One such example is
the `access_log` and `error_log` directives, which follow an obvious
pattern from one host to the next. Sadly, you must tolerate some
repetition across `server { }` blocks when setting up multiple domains
on a single server.

The configuration for `example.com` and `example.net` is similar.

See [the nginx docs](http://nginx.org/en/docs/) for more ideas.

























*[Return to the top-level Fossil server article.](../)*







|
|
|
|
|







 







|
|
|
|

|
|
|
|
<

>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<









|
|


|
|
|

|
|


|


|
|

|
>
>
>
>
>
|
|









|

>

<
<



|







 







|



>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>

64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
...
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120

121
122
123

































124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171


172
173
174
175
176
177
178
179
180
181
182
...
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225

## <a name="modes"></a>Fossil Service Modes

Fossil provides four major ways to access a repository it’s serving
remotely, three of which are straightforward to use with nginx:

*   **HTTP** — Fossil has a built-in HTTP server: [`fossil
    server`](../any/none.md).  While this method is efficient and it’s
    possible to use nginx to proxy access to another HTTP server, we
    don’t see any particularly good reason to make nginx reinterpret
    Fossil’s own implementation of HTTP when we have a better option.
    (But see [below](#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.
................................................................................
your server, then say:

       $ sudo apt install fossil nginx


## <a name="scgi"></a>Running Fossil in SCGI Mode

For the following nginx configuration to work, it needs to contact a
Fossil instance speaking the SCGI protocol. There are [many ways](../)
to set that up. For Debian type systems, we primarily recommend
following [our systemd user service guide](service.md).

Another option would be to customize [the `fslsrv` shell
script](/file/tools/fslsrv) that ships with Fossil as an example of
launching multiple Fossil instances in the background to serve multiple
URLs.


However you do it, you need to match up the TCP port numbers between it
and those in the nginx configuration below.



































## <a name="config"></a>Configuration

On Debian and Ubuntu systems the primary user-level configuration file
for nginx is `/etc/nginx/sites-enabled/default`. I recommend that this
file contain only a list of include statements, one for each site that
server hosts:

      include local/example.com
      include local/foo.net

Those files then each define one domain’s configuration.  Here,
`/etc/nginx/local/example.com` contains the configuration for
`*.example.com` and its alias `*.example.net`; and `local/foo.net`
contains the configuration for `*.foo.net`.

The configuration for our `example.com` web site, stored in
`/etc/nginx/sites-enabled/local/example.com` is:

      server {
          server_name .example.com .example.net "";
          include local/generic;

          access_log /var/log/nginx/example.com-https-access.log;
           error_log /var/log/nginx/example.com-https-error.log;

          # Bypass Fossil for the static documentation generated from
          # our source code by Doxygen, so it merges into the embedded
          # doc URL hierarchy at Fossil’s $ROOT/doc without requiring that
          # these generated files actually be stored in the repo.  This
          # also lets us set aggressive caching on these docs, since
          # they rarely change.
          location /code/doc/html {
              root /var/www/example.com/code/doc/html;

              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 /code {
              include scgi_params;
              scgi_param SCRIPT_NAME "/code";
              scgi_pass 127.0.0.1:12345;


          }
      }

As you can see, this is a pure extension of [the basic nginx service
configuration for SCGI][scgii], showing off a few ideas you might want to
try on your own site, such as static asset proxying.

The `local/generic` file referenced above helps us reduce unnecessary
repetition among the multiple sites this configuration hosts:

      root /var/www/$host;
................................................................................
variables into, citing performance considerations, so there is a limit
to how much repetition you can squeeze out this way. One such example is
the `access_log` and `error_log` directives, which follow an obvious
pattern from one host to the next. Sadly, you must tolerate some
repetition across `server { }` blocks when setting up multiple domains
on a single server.

The configuration for `foo.net` is similar.

See [the nginx docs](http://nginx.org/en/docs/) for more ideas.


## <a name="http"></a>Proxying HTTP Anyway

[Above](#modes), we argued that proxying SCGI is a better option than
making nginx reinterpret Fossil’s own implementation of HTTP.  If you
want Fossil to speak HTTP, just [set Fossil up as a standalone
server](../any/none.md). And if you want nginx to [provide TLS
encryption for Fossil][tls], proxying HTTP instead of SCGI provides no
benefit.

However, it is still worth showing the proper method of proxying
Fossil’s HTTP server through nginx if only to make reading nginx
documentation on other sites easier:

        location /code {
            rewrite ^/code(/.*) $1 break;
            proxy_pass http://127.0.0.1:12345;
        }

The most common thing people get wrong when hand-rolling a configuration
like this is to get the slashes wrong. Fossil is senstitive to this. For
instance, Fossil will not collapse double slashes down to a single
slash, as some other HTTP servers will.

*[Return to the top-level Fossil server article.](../)*

Changes to www/server/index.html.

1
2
3
4
5
6
7




8
9
10
11
12
13
14
..
50
51
52
53
54
55
56
57





58
59
60
61
62
63
































64
65
66
67
68
69
70
71

72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93

94
95
96
97
98
99


















100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131



132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
...
219
220
221
222
223
224
225








































226
227
228
229
230
231

232
233
234
235
236
237
238
<div class='fossil-doc' data-title="How To Configure A Fossil Server">

<style type="text/css">
  p {
    margin-left: 4em;
    margin-right: 3em;
  }





  h2 {
    margin-left: 1em;
  }

  h3 {
    margin-left: 3em;
................................................................................
  }
</style>


<h2>No Server Required</h2>

<p>Fossil does not require a central server, but <a
href="whyuseaserver.wiki">a server can be very useful</a>.</p>






<p>This article is a quick-reference guide for setting up your own
Fossil server, with links to more detailed instructions specific to
particular systems, should you want extra help.</p>


































<h2 id="methods">Methods</h2>

<p>There are basically four ways to set up a Fossil server:</p>

<ol>
  <li><a id="cgi"        href="any/cgi.md">CGI</a>
  <li><a id="standalone" href="any/none.md">Stand-alone HTTP server</a>
  <li>Socket listener

  <li><a id="scgi"       href="any/scgi.md">SCGI</a>
</ol>

<p>All of these methods can serve either a single repository or a
directory containing repositories named "<tt>*.fossil</tt>".</p>

<p>You are not restricted to using a single method. The same Fossil
repository can be served using two or more of the above techniques at
the same time. These methods use clean, well-defined, standard
interfaces (CGI, SCGI, and HTTP) which allow you to easily migrate from
one method to another to accommodate changes in hosting providers or
administrator preferences.</p>

<h3>CGI</h3>

<p>Most ordinary web servers can <a href="any/cgi.md">run Fossil as a
CGI script</a>. This method is known to work with Apache,
<tt>lighttpd</tt>, and <a
href="any/althttpd.md"><tt>althttpd</tt></a>.  The Fossil server
administrator places a <a href="/help?cmd=cgi">short CGI script</a> in
the web server's document hierarchy, and when a client requests the
appropriate URL, that script runs Fossil to generate the response.</p>


<p>CGI is a good choice for merging Fossil into an existing web site,
particularly on hosts that have CGI set up for you already and won't let
you modify the web server configuration further. The Fossil <a
href="../selfhost.wiki">self-hosting repositories</a> are implemented
with CGI underneath <tt>althttpd</tt>.</p>



















<h3>Stand-alone HTTP Server</h3>

<p>This is the <a href="any/none.md">easiest method</a>.
A stand-alone server uses the <a
href="/help?cmd=server"><tt>fossil server</tt></a> command to run a
process that listens for incoming HTTP requests on a socket and then
dispatches a copy of itself to deal with each incoming request. You can
expose Fossil directly to the clients in this way or you can interpose a
<a href="https://en.wikipedia.org/wiki/Reverse_proxy">reverse proxy</a>
layer between the clients and Fossil.</p>

<h3>Socket Listener</h3>

<p>Only slightly more complicated is the socket listener method.
Instead of letting Fossil run in the background continuously to handle
HTTP requests from clients, you configure a socket listener daemon to
run a <a href="/help?cmd=http"><tt>fossil http</tt></a> command on each
HTTP hit.  That Fossil instance handles only that one hit and then shuts
back down, letting the socket listener go back to waiting for the next
hit.  This scheme is known to work with <a id="inetd"
href="any/inetd.md"><tt>inetd</tt></a>, <a id="xinetd"
href="any/xinetd.md"><tt>xinetd</tt></a>, <a id="stunnel"
href="any/stunnel.md"><tt>stunnel</tt></a>, <a
href="macos/service.md"><tt>launchd</tt></a>, and <a
href="debian/service.md"><tt>systemd</tt></a>.</p>

<h3>SCGI</h3>

<p>The Fossil standalone server can also run <a href="any/scgi.md">in
SCGI mode</a> — <a href="/help/server"><tt>fossil server --scgi</tt></a>
— instead of <a href="any/none.md">HTTP mode</a>, which allows it to



respond to requests from web servers <a href="debian/nginx.md">such as
nginx</a> that don't support CGI. SCGI is a simpler protocol to proxy
than HTTP, since the HTTP doesn't have to be re-interpreted in terms of
the proxy's existing HTTP implementation, but it's more complex to set
up because you also have to set up an SCGI-to-HTTP proxy for it. It is
worth taking on this difficulty only when you need to integrate Fossil
into an existing web site already being served by an SCGI-capable web
server.</p>

<h2 id="matrix">Setup Tutorials</h2>

<p>We've broken the configuration for each method out into a series of
sub-articles. Some of these are generic, while others depend on
particular operating systems or front-end software:</p>

<div id="tutpick" class="show"></div>

................................................................................
Fossil's built-in HTTP server: <a href="debian/nginx.md">nginx</a>, <a
href="windows/iis.md">IIS</a>, Apache, etc.</p>

<p>We welcome <a href="../contribute.wiki">contributions</a> to fill gaps
(<font size="-2">❌</font>) in the table above.</p>
</noscript>










































<h2 id="more">Further Details</h2>

<ul>
  <li><a id="chroot"   href="../chroot.md"     >The Server Chroot Jail</a>
  <li><a id="loadmgmt" href="../loadmgmt.md"   >Managing Server Load</a>

  <li><a id="tls"      href="../ssl.wiki"      >Securing a Repository with TLS</a>
  <li><a id="ext"      href="../serverext.wiki">CGI Server Extensions</a>
  <li><a id="about"    href="../aboutcgi.wiki" >How CGI Works In Fossil</a>
  <li><a id="sync"     href="../sync.wiki"     >The Fossil Sync Protocol</a>
</ul>

</div>







>
>
>
>







 







|
>
>
>
>
>






>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|

|



<

>




|

|



|








|
|
|
>


|
<
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>




|
|






<
<
<
<
<
<
<
<
<
<
<
<
<
<
<


|
<
<
>
>
>









|







 







>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>






>







1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
..
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110

111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138

139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170















171
172
173


174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
...
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
<div class='fossil-doc' data-title="How To Configure A Fossil Server">

<style type="text/css">
  p {
    margin-left: 4em;
    margin-right: 3em;
  }

  li p {
    margin-left: 0;
  }

  h2 {
    margin-left: 1em;
  }

  h3 {
    margin-left: 3em;
................................................................................
  }
</style>


<h2>No Server Required</h2>

<p>Fossil does not require a central server, but <a
href="whyuseaserver.wiki">a server can be useful</a>.</p>

<p>A Fossil server does not require much memory, CPU, or disk space
and can run comfortably on a generic $5/month virtual host 
or on a small device like a Raspberry Pi, or it can co-exist 
on a host running other services without getting in the way.

<p>This article is a quick-reference guide for setting up your own
Fossil server, with links to more detailed instructions specific to
particular systems, should you want extra help.</p>


<h2 id="prep">Repository Prep</h2>

<p>Prior to serving a Fossil repository to others, consider running <a
href="$ROOT/help?cmd=ui"><tt>fossil ui</tt></a> locally and taking these
minimum recommended preparation steps:</p>

<ol>
  <li><p>Fossil creates only one user in a <a
  href="$ROOT/help?cmd=new">new repository</a> and gives it the <a
  href="../admin-v-setup.md">all-powerful Setup capability</a>.  (“s”)
  The 10-digit random password generated for that user is fairly strong
  against remote attack, even without explicit password guess rate
  limiting, but because that user has so much power, you may want to
  give it a much stronger password under Admin → Users.</a></li>

  <li><p>Run the Admin → Security-Audit tool to verify that other
  security-related permissions and settings are as you want them.
  Consider clicking the “Take it private” link on that page to lock down
  the security on that site to a level appropriate to a private
  repository, even if you will eventually want some public service. It's
  better to start from a secure position and open up service
  feature-by-feature as necessary than it is to start from a fully open
  position and lock down features one by one to achieve a secure
  stance.</p></li>
</ol>

<p>With the repository secured, it is safe to upload a copy of the
repository file to your server and proceed with server setup, below.
Further configuration steps can wait until <a href="#postsetup">after
the server is running</a>.</p>


<h2 id="methods">Activation Methods</h2>

<p>There are basically four ways to run a Fossil server:</p>

<ol>
  <li><a id="cgi"        href="any/cgi.md">CGI</a>

  <li>Socket listener
  <li><a id="standalone" href="any/none.md">Stand-alone HTTP server</a>
  <li><a id="scgi"       href="any/scgi.md">SCGI</a>
</ol>

<p>All of these methods can serve either a single repository or a
directory hierarchy containing mulitiple repositories.</p>

<p>You are not restricted to a single server setup. The same Fossil
repository can be served using two or more of the above techniques at
the same time. These methods use clean, well-defined, standard
interfaces (CGI, SCGI, and HTTP) which allow you to easily migrate from
one method to another in response to changes in hosting providers or
administrator preferences.</p>

<h3>CGI</h3>

<p>Most ordinary web servers can <a href="any/cgi.md">run Fossil as a
CGI script</a>. This method is known to work with Apache,
<tt>lighttpd</tt>, and <a
href="any/althttpd.md"><tt>althttpd</tt></a>.  The Fossil server
administrator places a <a href="$ROOT/help?cmd=cgi">short CGI script</a> in
the web server's document hierarchy and when a client requests the URL
that corresponds to that script, Fossil runs and generates the
response.</p>

<p>CGI is a good choice for merging Fossil into an existing web site,
particularly on hosts that have CGI set up and working.

The Fossil <a href="../selfhost.wiki">self-hosting repositories</a> are
implemented with CGI underneath <tt>althttpd</tt>.</p>

<h3>Socket Listener</h3>

<p>Socket listener daemons such as
<a id="inetd" href="any/inetd.md"><tt>inetd</tt></a>, <a id="xinetd"
href="any/xinetd.md"><tt>xinetd</tt></a>, <a id="stunnel"
href="any/stunnel.md"><tt>stunnel</tt></a>, <a
href="macos/service.md"><tt>launchd</tt></a>, and <a
href="debian/service.md"><tt>systemd</tt></a>
can be configured to invoke the the
<a href="$ROOT/help?cmd=http"><tt>fossil http</tt></a> command to handle
each incoming HTTP request.  The "<tt>fossil http</tt>" command reads
the HTTP request off of standard input, computes an appropriate
reply, and writes the reply on standard output.  There is a separate
invocation of the "<tt>fossil http</tt>" command for each HTTP request.
The socket listener daemon takes care of relaying content to and from
the client, and (in the case of <a href="any/stunnel.md">stunnel</a>) 
handling TLS decryption and encryption.

<h3>Stand-alone HTTP Server</h3>

<p>This is the <a href="any/none.md">easiest method</a>.
A stand-alone server uses the
<a href="$ROOT/help?cmd=server"><tt>fossil server</tt></a> command to run a
process that listens for incoming HTTP requests on a socket and then
dispatches a copy of itself to deal with each incoming request. You can
expose Fossil directly to the clients in this way or you can interpose a
<a href="https://en.wikipedia.org/wiki/Reverse_proxy">reverse proxy</a>
layer between the clients and Fossil.</p>
















<h3>SCGI</h3>

<p>The Fossil standalone server can also handle <a href="any/scgi.md">SCGI</a>.


When the <a href="$ROOT/help?cmd=server"><tt>fossil server</tt></a> command is
run with the extra <tt>--scgi</tt> option, it listens for incoming
SCGI requests rather than HTTP requests. This allows Fossil to
respond to requests from web servers <a href="debian/nginx.md">such as
nginx</a> that don't support CGI. SCGI is a simpler protocol to proxy
than HTTP, since the HTTP doesn't have to be re-interpreted in terms of
the proxy's existing HTTP implementation, but it's more complex to set
up because you also have to set up an SCGI-to-HTTP proxy for it. It is
worth taking on this difficulty only when you need to integrate Fossil
into an existing web site already being served by an SCGI-capable web
server.</p>

<h2 id="matrix">Activation Tutorials</h2>

<p>We've broken the configuration for each method out into a series of
sub-articles. Some of these are generic, while others depend on
particular operating systems or front-end software:</p>

<div id="tutpick" class="show"></div>

................................................................................
Fossil's built-in HTTP server: <a href="debian/nginx.md">nginx</a>, <a
href="windows/iis.md">IIS</a>, Apache, etc.</p>

<p>We welcome <a href="../contribute.wiki">contributions</a> to fill gaps
(<font size="-2">❌</font>) in the table above.</p>
</noscript>


<h2 id="postsetup">Post-Activation Configuration</h2>

<p>After the server is up and running, log into it as the Setup user and
visit the Admin menu to finish configuring that repository for
service:</p>

<ol>
  <li><p>Add user accounts for your other team members. Use the
  pre-defined user capabilities to define access policies rather than
  give out those same set of capabilities redundantly to each
  user.</p></li>

  <li><p>Test access to the repository from each category of non-Setup
  user that you created. You may have to give your user categories some
  overlooked capabilities, particularly if you followed <a
  href="#prep">our earlier advice</a> to take the repository private
  prior to setting up the server.</p></li>

  <li><p>Modify the repository's look and feel by <a
  href="../customskin.md">customizing the skin</a>.</p></li>

  <li><p>If the repository includes <a
  href="../embeddeddoc.wiki">embedded documentation</a>, consider
  activating the search feature (Admin → Search) so that visitors can do
  full-text search on your documentation.</p></li>

  <li><p>Now that others can be making changes to the repository,
  consider monitoring them via <a href="../alerts.md">email alerts</a>
  or the <a href="$ROOT/help?cmd=/timeline.rss">timeline RSS
  feed</a>.</p></li>

  <li><p>Turn on the various logging features.</p></li>
</ol>

<p>Reload the Admin → Security-Audit page occasionally during this
process to double check that you have not mistakenly configured the
server in a way that might expose information that you want to keep
private.</p>


<h2 id="more">Further Details</h2>

<ul>
  <li><a id="chroot"   href="../chroot.md"     >The Server Chroot Jail</a>
  <li><a id="loadmgmt" href="../loadmgmt.md"   >Managing Server Load</a>
  <li><a id="bkofc"    href="../backoffice.md" >The Backoffice</a>
  <li><a id="tls"      href="../ssl.wiki"      >Securing a Repository with TLS</a>
  <li><a id="ext"      href="../serverext.wiki">CGI Server Extensions</a>
  <li><a id="about"    href="../aboutcgi.wiki" >How CGI Works In Fossil</a>
  <li><a id="sync"     href="../sync.wiki"     >The Fossil Sync Protocol</a>
</ul>

</div>

Changes to www/server/whyuseaserver.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
37
38
39
40
41
42
43
44
<title>Benefits Of A Fossil Server</title>

<h2>No Server Required</h2>

Fossil does <em>not</em> require a central server.
Data sharing and synchronization can be entirely peer-to-peer.
Fossil uses 
[https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type|conflict-free replicated data types]
to ensure that (in the limit) all participating peers see the same content.

<h2>But, A Server Can Be Useful</h2>

Fossil does not require a server, but a server can be very useful.
Here are a few reasons to set up a Fossil server for your project:










  1.  <b>A server gives developers a common point of rendezvous for
      syncing their work.</b><p>
      It is possible for developers to synchronous peer-to-peer but
      that requires the developers coordinate the sync, which in turn
      requires that the developers both want to sync at the same moment.
      A server aleviates this time dependency by allowing each developer
      to sync whenever it is convenient (for example, automatically syncing
      after each commit and before each update).  Developers all stay
      in sync with each other, without having to interrupt each other
      constantly to set up a peer-to-peer sync.

  2.  <b>A server works as a project website for non-developers.</b><p>
      Fossil does more than just version control.  It also supports
      trouble-tickets, and wiki, and a forum.  It shows the status
      of the project.  And the embedded documentation feature provides
      a great mechanism for providing only instructions.

  3.  <b>A server provides project leaders with up-to-date status.</b><p>
      Project coordinators and BDFLs can click on a link or two at the
      central Fossil server for a project, and quickly tell what is
      going on.  They can do this from anywhere, even from their phones,
      without needing to actually sync to the device they are using.

  4.  <b>A server provides automatic off-site backups.</b><p>
      A Fossil server is an automatic remote backup for all the work
      going into a project.  You can even set up multiple servers, at
      multiple sites, with automatic synchronization between them, for
      added redundancy.  Such a set up means that no work is lost due
      to a single machine failure.




|










>
>
>
>
>
>
>
>
>
|

|








<
<
<
<
<
<











|
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
37
38
39
40
41
42
43
44
45
46
47
<title>Benefits Of A Fossil Server</title>

<h2>No Server Required</h2>

Fossil does not require a central server.
Data sharing and synchronization can be entirely peer-to-peer.
Fossil uses 
[https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type|conflict-free replicated data types]
to ensure that (in the limit) all participating peers see the same content.

<h2>But, A Server Can Be Useful</h2>

Fossil does not require a server, but a server can be very useful.
Here are a few reasons to set up a Fossil server for your project:

  1.  <b>A server works as a complete project website.</b><p>
      Fossil does more than just version control.  It also supports
      [../tickets.wiki|trouble-tickets], 
      [../wikitheory.wiki|wiki], and a [../forum.wiki|forum].
      The [../embeddeddoc.wiki|embedded documentation]
      feature provides  a great mechanism for providing project documentation.
      The [../unvers.wiki|unversioned files] feature is a convenient way
      to host builds and downloads on the project website.

  2.  <b>A server gives developers a common point of rendezvous for
      syncing their work.</b><p>
      It is possible for developers to synchronize peer-to-peer but
      that requires the developers coordinate the sync, which in turn
      requires that the developers both want to sync at the same moment.
      A server aleviates this time dependency by allowing each developer
      to sync whenever it is convenient (for example, automatically syncing
      after each commit and before each update).  Developers all stay
      in sync with each other, without having to interrupt each other
      constantly to set up a peer-to-peer sync.







  3.  <b>A server provides project leaders with up-to-date status.</b><p>
      Project coordinators and BDFLs can click on a link or two at the
      central Fossil server for a project, and quickly tell what is
      going on.  They can do this from anywhere, even from their phones,
      without needing to actually sync to the device they are using.

  4.  <b>A server provides automatic off-site backups.</b><p>
      A Fossil server is an automatic remote backup for all the work
      going into a project.  You can even set up multiple servers, at
      multiple sites, with automatic synchronization between them, for
      added redundancy.  Such a set up means that no work is lost due
      to a single machine failur