Context Navigation

Changes between Version 1 and Version 2 of TracStandalone

Timestamp:: 02/19/15 14:27:32 (10 years ago)
Author:: trac
Comment:: --

Legend:

: Unmodified
: Added
: Removed
: Modified

TracStandalone

-                      v1
+                      v2
 = Tracd =
+= Tracd
 Tracd is a lightweight standalone Trac web server.
 It can be used in a variety of situations, from a test or development server to a multiprocess setup behind another web server used as a load balancer.
 == Pros ==
+== Pros
  * Fewer dependencies: You don't need to install apache or any other web-server.
 …
  * Automatic reloading: For development, Tracd can be used in ''auto_reload'' mode, which will automatically restart the server whenever you make a change to the code (in Trac itself or in a plugin).
 == Cons ==
+== Cons
  * Fewer features: Tracd implements a very simple web-server and is not as configurable or as scalable as Apache httpd.
  * No native HTTPS support: [http://www.rickk.com/sslwrap/ sslwrap] can be used instead,
    or [http://trac.edgewall.org/wiki/STunnelTracd stunnel -- a tutorial on how to use stunnel with tracd] or Apache with mod_proxy.
 == Usage examples ==
+   or [trac:wiki:STunnelTracd stunnel -- a tutorial on how to use stunnel with tracd] or Apache with mod_proxy.
+== Usage examples
 A single project on port 8080. (http://localhost:8080/)
 {{{
+{{{#!sh
  $ tracd -p 8080 /path/to/project
 }}}
 Stricly speaking this will make your Trac accessible to everybody from your network rather than ''localhost only''. To truly limit it use ''--hostname'' option.
 {{{
+Strictly speaking this will make your Trac accessible to everybody from your network rather than ''localhost only''. To truly limit it use ''--hostname'' option.
+{{{#!sh
  $ tracd --hostname=localhost -p 8080 /path/to/project
 }}}
 With more than one project. (http://localhost:8080/project1/ and http://localhost:8080/project2/)
 {{{
+{{{#!sh
  $ tracd -p 8080 /path/to/project1 /path/to/project2
 }}}
 …
 An alternative way to serve multiple projects is to specify a parent directory in which each subdirectory is a Trac project, using the `-e` option. The example above could be rewritten:
 {{{
+{{{#!sh
  $ tracd -p 8080 -e /path/to
 }}}
 To exit the server on Windows, be sure to use {{{CTRL-BREAK}}} -- using {{{CTRL-C}}} will leave a Python process running in the background.
 == Installing as a Windows Service ==
 === Option 1 ===
+To exit the server on Windows, be sure to use `CTRL-BREAK` -- using `CTRL-C` will leave a Python process running in the background.
+== Installing as a Windows Service
+=== Option 1
 To install as a Windows service, get the [http://www.google.com/search?q=srvany.exe SRVANY] utility and run:
 {{{
+{{{#!cmd
  C:\path\to\instsrv.exe tracd C:\path\to\srvany.exe
  reg add HKLM\SYSTEM\CurrentControlSet\Services\tracd\Parameters /v Application /d "\"C:\path\to\python.exe\" \"C:\path\to\python\scripts\tracd-script.py\" <your tracd parameters>"
 …
 If you want tracd to start automatically when you boot Windows, do:
 {{{
+{{{#!cmd
  sc config tracd start= auto
 }}}
 …
 For Windows 7 User, srvany.exe may not be an option, so you can use [http://www.google.com/search?q=winserv.exe WINSERV] utility and run:
 {{{
+{{{#!cmd
 "C:\path\to\winserv.exe" install tracd -displayname "tracd" -start auto "C:\path\to\python.exe" c:\path\to\python\scripts\tracd-script.py <your tracd parameters>"
 net start tracd
 }}}
 === Option 2 ===
+=== Option 2
 Use [http://trac-hacks.org/wiki/WindowsServiceScript WindowsServiceScript], available at [http://trac-hacks.org/ Trac Hacks]. Installs, removes, starts, stops, etc. your Trac service.
+== Using Authentication ==
+=== Option 3
+also cygwin's cygrunsrv.exe can be used:
+{{{#!sh
+$ cygrunsrv --install tracd --path /cygdrive/c/Python27/Scripts/tracd.exe --args '--port 8000 --env-parent-dir E:\IssueTrackers\Trac\Projects'
+$ net start tracd
+}}}
+== Using Authentication
+Tracd allows you to run Trac without the need for Apache, but you can take advantage of Apache's password tools (htpasswd and htdigest) to easily create a password file in the proper format for tracd to use in authentication. (It is also possible to create the password file without htpasswd or htdigest; see below for alternatives)
+Make sure you place the generated password files on a filesystem which supports sub-second timestamps, as Trac will monitor their modified time and changes happening on a filesystem with too coarse-grained timestamp resolution (like `ext2` or `ext3` on Linux) may go undetected.
 Tracd provides support for both Basic and Digest authentication. Digest is considered more secure. The examples below use Digest; to use Basic authentication, replace `--auth` with `--basic-auth` in the command line.
 The general format for using authentication is:
 {{{
+{{{#!sh
  $ tracd -p port --auth="base_project_dir,password_file_path,realm" project_path
 }}}
 …
 Examples:
 {{{
+{{{#!sh
  $ tracd -p 8080 \
    --auth="project1,/path/to/passwordfile,mycompany.com" /path/to/project1
 …
 Of course, the password file can be be shared so that it is used for more than one project:
 {{{
+{{{#!sh
  $ tracd -p 8080 \
    --auth="project1,/path/to/passwordfile,mycompany.com" \
 …
 Another way to share the password file is to specify "*" for the project name:
 {{{
+{{{#!sh
  $ tracd -p 8080 \
    --auth="*,/path/to/users.htdigest,mycompany.com" \
 …
 }}}
 === Basic Authorization: Using a htpasswd password file ===
+=== Basic Authorization: Using a htpasswd password file
 This section describes how to use `tracd` with Apache .htpasswd files.
+  Note: It is necessary (at least with Python 2.6) to install the fcrypt package in order to
+  decode some htpasswd formats.  Trac source code attempt an `import crypt` first, but there
+  is no such package for Python 2.6. Only `SHA-1` passwords (since Trac 1.0) work without this module.
 To create a .htpasswd file use Apache's `htpasswd` command (see [#GeneratingPasswordsWithoutApache below] for a method to create these files without using Apache):
 {{{
+{{{#!sh
  $ sudo htpasswd -c /path/to/env/.htpasswd username
 }}}
 then for additional users:
 {{{
+{{{#!sh
  $ sudo htpasswd /path/to/env/.htpasswd username2
 }}}
 Then to start `tracd` run something like this:
 {{{
+{{{#!sh
  $ tracd -p 8080 --basic-auth="projectdirname,/fullpath/environmentname/.htpasswd,realmname" /fullpath/environmentname
 }}}
 For example:
 {{{
+{{{#!sh
  $ tracd -p 8080 --basic-auth="testenv,/srv/tracenv/testenv/.htpasswd,My Test Env" /srv/tracenv/testenv
 }}}
 ''Note:'' You might need to pass "-m" as a parameter to htpasswd on some platforms (OpenBSD).
 === Digest authentication: Using a htdigest password file ===
+=== Digest authentication: Using a htdigest password file
 If you have Apache available, you can use the htdigest command to generate the password file. Type 'htdigest' to get some usage instructions, or read [http://httpd.apache.org/docs/2.0/programs/htdigest.html this page] from the Apache manual to get precise instructions.  You'll be prompted for a password to enter for each user that you create.  For the name of the password file, you can use whatever you like, but if you use something like `users.htdigest` it will remind you what the file contains. As a suggestion, put it in your <projectname>/conf folder along with the [TracIni trac.ini] file.
 Note that you can start tracd without the --auth argument, but if you click on the ''Login'' link you will get an error.
 === Generating Passwords Without Apache ===
 Basic Authorization can be accomplished via this [http://www.4webhelp.net/us/password.php online HTTP Password generator].  Copy the generated password-hash line to the .htpasswd file on your system.
+Note that you can start tracd without the `--auth` argument, but if you click on the ''Login'' link you will get an error.
+=== Generating Passwords Without Apache
+Basic Authorization can be accomplished via this [http://aspirine.org/htpasswd_en.html online HTTP Password generator] which also supports `SHA-1`.  Copy the generated password-hash line to the .htpasswd file on your system. Note that Windows Python lacks the "crypt" module that is the default hash type for htpasswd ; Windows Python can grok MD5 password hashes just fine and you should use MD5.
 You can use this simple Python script to generate a '''digest''' password file:
+{{{
+#!python
+{{{#!python
 from optparse import OptionParser
 # The md5 module is deprecated in Python 2.5
 …
 Note: If you use the above script you must set the realm in the `--auth` argument to '''`trac`'''. Example usage (assuming you saved the script as trac-digest.py):
 {{{
+{{{#!sh
  $ python trac-digest.py -u username -p password >> c:\digest.txt
  $ tracd --port 8000 --auth=proj_name,c:\digest.txt,trac c:\path\to\proj_name
 …
 It is possible to use `md5sum` utility to generate digest-password file:
 {{{
+ $ printf "${user}:trac:${password}" | md5sum - >>user.htdigest
+}}}
+and manually delete " -" from the end and add "${user}:trac:" to the start of line from 'to-file'.
+== Reference ==
+user=
+realm=
+password=
+path_to_file=
+echo ${user}:${realm}:$(printf "${user}:${realm}:${password}" | md5sum - | sed -e 's/\s\+-//') > ${path_to_file}
+}}}
+== Reference
 Here's the online help, as a reminder (`tracd --help`):
 …
   -b HOSTNAME, --hostname=HOSTNAME
                         the host name or IP address to bind to
   --protocol=PROTOCOL   http|scgi|ajp
+  --protocol=PROTOCOL   http|scgi|ajp|fcgi
   -q, --unquote         unquote PATH_INFO (may be needed when using ajp)
   --http10              use HTTP/1.0 protocol version (default)
   --http11              use HTTP/1.1 protocol version instead of HTTP/1.0
+  --http10              use HTTP/1.0 protocol version instead of HTTP/1.1
+  --http11              use HTTP/1.1 protocol version (default)
   -e PARENTDIR, --env-parent-dir=PARENTDIR
                         parent directory of the project environments
 …
   -r, --auto-reload     restart automatically when sources are modified
   -s, --single-env      only serve a single project without the project list
+}}}
+== Tips ==
+=== Serving static content ===
+  -d, --daemonize       run in the background as a daemon
+  --pidfile=PIDFILE     when daemonizing, file to which to write pid
+  --umask=MASK          when daemonizing, file mode creation mask to use, in
+                        octal notation (default 022)
+  --group=GROUP         the group to run as
+  --user=USER           the user to run as
+}}}
+Use the -d option so that tracd doesn't hang if you close the terminal window where tracd was started.
+== Tips
+=== Serving static content
 If `tracd` is the only web server used for the project,
 …
 Example: given a `$TRAC_ENV/htdocs/software-0.1.tar.gz` file,
 the corresponding relative URL would be `/<project_name>/chrome/site/software-0.1.tar.gz`,
+which in turn can be written as `htdocs:software-0.1.tar.gz` (TracLinks syntax) or `[/<project_name>/chrome/site/software-0.1.tar.gz]` (relative link syntax).
+ ''Support for `htdocs:` TracLinks syntax was added in version 0.10''
+which in turn can be written as `htdocs:software-0.1.tar.gz` (TracLinks syntax) or `[/<project_name>/chrome/site/software-0.1.tar.gz]` (relative link syntax).
 === Using tracd behind a proxy
 …
 See also [trac:TracOnWindowsIisAjp], [trac:TracNginxRecipe].
+=== Serving a different base path than / ===
+=== Authentication for tracd behind a proxy
+It is convenient to provide central external authentication to your tracd instances, instead of using `--basic-auth`. There is some discussion about this in #9206.
+Below is example configuration based on Apache 2.2, mod_proxy, mod_authnz_ldap.
+First we bring tracd into Apache's location namespace.
+{{{#!apache
+<Location /project/proxified>
+        Require ldap-group cn=somegroup, ou=Groups,dc=domain.com
+        Require ldap-user somespecificusertoo
+        ProxyPass http://localhost:8101/project/proxified/
+        # Turns out we don't really need complicated RewriteRules here at all
+        RequestHeader set REMOTE_USER %{REMOTE_USER}s
+</Location>
+}}}
+Then we need a single file plugin to recognize HTTP_REMOTE_USER header as valid authentication source. HTTP headers like '''HTTP_FOO_BAR''' will get converted to '''Foo-Bar''' during processing. Name it something like '''remote-user-auth.py''' and drop it into '''proxified/plugins''' directory:
+{{{#!python
+from trac.core import *
+from trac.config import BoolOption
+from trac.web.api import IAuthenticator
+class MyRemoteUserAuthenticator(Component):
+    implements(IAuthenticator)
+    obey_remote_user_header = BoolOption('trac', 'obey_remote_user_header', 'false',
+               """Whether the 'Remote-User:' HTTP header is to be trusted for user logins
+                (''since ??.??').""")
+    def authenticate(self, req):
+        if self.obey_remote_user_header and req.get_header('Remote-User'):
+            return req.get_header('Remote-User')
+        return None
+}}}
+Add this new parameter to your TracIni:
+{{{#!ini
+[trac]
+...
+obey_remote_user_header = true
+...
+}}}
+Run tracd:
+{{{#!sh
+tracd -p 8101 -r -s proxified --base-path=/project/proxified
+}}}
+Note that if you want to install this plugin for all projects, you have to put it in your [TracPlugins#Plugindiscovery global plugins_dir] and enable it in your global trac.ini.
+Global config (e.g. `/srv/trac/conf/trac.ini`):
+{{{#!ini
+[components]
+remote-user-auth.* = enabled
+[inherit]
+plugins_dir = /srv/trac/plugins
+[trac]
+obey_remote_user_header = true
+}}}
+Environment config (e.g. `/srv/trac/envs/myenv`):
+{{{#!ini
+[inherit]
+file = /srv/trac/conf/trac.ini
+}}}
+=== Serving a different base path than /
 Tracd supports serving projects with different base urls than /<project>. The parameter name to change this is
 {{{
+{{{#!sh
  $ tracd --base-path=/some/path
 }}}