"Fossies" - the Fresh Open Source Software Archive

Member "PURELIB/trac/wiki/default-pages/TracStandalone" (27 Aug 2019, 16915 Bytes) of package /windows/misc/Trac-1.4.win-amd64.exe:

As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the last Fossies "Diffs" side-by-side code changes report for "TracStandalone": 1.3.3_vs_1.3.4.

    1 = Tracd
    3 Tracd is a lightweight standalone Trac web server.
    4 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.
    6 == Pros
    8  * Fewer dependencies: You don't need to install apache or any other web-server.
    9  * Fast: Should be almost as fast as the [wiki:TracModPython mod_python] version (and much faster than the [wiki:TracCgi CGI]), even more so since version 0.12 where the HTTP/1.1 version of the protocol is enabled by default
   10  * 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).
   12 == Cons
   14  * Fewer features: Tracd implements a very simple web-server and is not as configurable or as scalable as Apache httpd.
   15  * No native HTTPS support: [http://www.rickk.com/sslwrap/ sslwrap] can be used instead,
   16    or [trac:wiki:STunnelTracd stunnel -- a tutorial on how to use stunnel with tracd] or Apache with mod_proxy.
   18 == Usage examples
   20 A single project on port 8080. (http://localhost:8080/)
   21 {{{#!sh
   22  $ tracd -p 8080 /path/to/project
   23 }}}
   24 Strictly speaking this will make your Trac accessible to everybody from your network rather than ''localhost only''. To truly limit it use the `--hostname` option.
   25 {{{#!sh
   26  $ tracd --hostname=localhost -p 8080 /path/to/project
   27 }}}
   28 With more than one project. (http://localhost:8080/project1/ and http://localhost:8080/project2/)
   29 {{{#!sh
   30  $ tracd -p 8080 /path/to/project1 /path/to/project2
   31 }}}
   33 You can't have the last portion of the path identical between the projects since Trac uses that name to keep the URLs of the
   34 different projects unique. So if you use `/project1/path/to` and `/project2/path/to`, you will only see the second project.
   36 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:
   37 {{{#!sh
   38  $ tracd -p 8080 -e /path/to
   39 }}}
   41 There is support for the HTTPS protocol (//Since 1.3.4//). Specify the path to the PEM certificate file and keyfile using the `--certfile` and `--keyfile` options. You can specify just the `--certfile` option if you have a [https://docs.python.org/2/library/ssl.html#combined-key-and-certificate combined key and certificate].
   43 To exit the server on Windows, be sure to use `CTRL-BREAK` -- using `CTRL-C` will leave a Python process running in the background.
   45 == Installing as a Windows Service
   47 === Option 1
   48 To install as a Windows service, get the [http://www.google.com/search?q=srvany.exe SRVANY] utility and run:
   49 {{{#!cmd
   50  C:\path\to\instsrv.exe tracd C:\path\to\srvany.exe
   51  reg add HKLM\SYSTEM\CurrentControlSet\Services\tracd\Parameters /v Application /d "\"C:\path\to\python.exe\" \"C:\path\to\python\scripts\tracd.exe\" <your tracd parameters>"
   52  net start tracd
   53 }}}
   55 {{{#!div style="border: 1pt dotted; margin: 1em;"
   56 **Attention:** Do not use `tracd.exe` directly.  Instead register `python.exe` directly with `tracd.exe` as a parameter.  If you use `tracd.exe`, it will spawn the python process without SRVANY's knowledge.  This python process will survive a `net stop tracd`.
   57 }}}
   59 If you want tracd to start automatically when you boot Windows, do:
   60 {{{#!cmd
   61  sc config tracd start= auto
   62 }}}
   64 The spacing here is important.
   66 {{{#!div
   67 Once the service is installed, it might be simpler to run the Registry Editor rather than use the `reg add` command documented above.  Navigate to:[[BR]]
   68 `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\tracd\Parameters`
   70 Three (string) parameters are provided:
   71 ||!AppDirectory ||C:\Python27\ ||
   72 ||Application ||python.exe ||
   73 ||!AppParameters ||scripts\tracd.exe -p 8080 ... ||
   75 Note that, if the !AppDirectory is set as above, the paths of the executable ''and'' of the script name and parameter values are relative to the directory.  This makes updating Python a little simpler because the change can be limited, here, to a single point.
   76 (This is true for the path to the .htpasswd file, as well, despite the documentation calling out the /full/path/to/htpasswd; however, you may not wish to store that file under the Python directory.)
   77 }}}
   79 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:
   80 {{{#!cmd
   81 "C:\path\to\winserv.exe" install tracd -displayname "tracd" -start auto "C:\path\to\python.exe" c:\path\to\python\scripts\tracd.exe <your tracd parameters>"
   82 net start tracd
   83 }}}
   85 === Option 2
   87 Use [http://trac-hacks.org/wiki/WindowsServiceScript WindowsServiceScript], available at [http://trac-hacks.org/ Trac Hacks]. Installs, removes, starts, stops, etc. your Trac service.
   89 === Option 3
   91 also cygwin's cygrunsrv.exe can be used:
   92 {{{#!sh
   93 $ cygrunsrv --install tracd --path /cygdrive/c/Python27/Scripts/tracd.exe --args '--port 8000 --env-parent-dir E:\IssueTrackers\Trac\Projects'
   94 $ net start tracd
   95 }}}
   97 == Using Authentication
   99 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)
  101 {{{#!div style="border: 1pt dotted; margin: 1em"
  102 **Attention:** 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, or HFS+ on OSX).
  103 }}}
  105 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.
  107 The general format for using authentication is:
  108 {{{#!sh
  109  $ tracd -p port --auth="base_project_dir,password_file_path,realm" project_path
  110 }}}
  111 where:
  112  * '''base_project_dir''': the base directory of the project specified as follows:
  113    * when serving multiple projects: ''relative'' to the `project_path`
  114    * when serving only a single project (`-s`): the name of the project directory
  115  Don't use an absolute path here as this won't work. ''Note:'' This parameter is case-sensitive even for environments on Windows.
  116  * '''password_file_path''': path to the password file
  117  * '''realm''': the realm name (can be anything)
  118  * '''project_path''': path of the project
  120  * **`--auth`** in the above means use Digest authentication, replace `--auth` with `--basic-auth` if you want to use Basic auth.  Although Basic authentication does not require a "realm", the command parser does, so the second comma is required, followed directly by the closing quote for an empty realm name.
  122 Examples:
  124 {{{#!sh
  125  $ tracd -p 8080 \
  126    --auth="project1,/path/to/passwordfile,mycompany.com" /path/to/project1
  127 }}}
  129 Of course, the password file can be be shared so that it is used for more than one project:
  130 {{{#!sh
  131  $ tracd -p 8080 \
  132    --auth="project1,/path/to/passwordfile,mycompany.com" \
  133    --auth="project2,/path/to/passwordfile,mycompany.com" \
  134    /path/to/project1 /path/to/project2
  135 }}}
  137 Another way to share the password file is to specify "*" for the project name:
  138 {{{#!sh
  139  $ tracd -p 8080 \
  140    --auth="*,/path/to/users.htdigest,mycompany.com" \
  141    /path/to/project1 /path/to/project2
  142 }}}
  144 === Basic Authorization: Using a htpasswd password file
  145 This section describes how to use `tracd` with Apache .htpasswd files.
  147   Note: On Windows It is necessary to install the [https://pypi.python.org/pypi/passlib passlib]
  148   package in order to decode some htpasswd formats. Only `SHA-1` passwords (since Trac 1.0)
  149   work without this module.
  151 To create a .htpasswd file use Apache's `htpasswd` command (see [#GeneratingPasswordsWithoutApache below] for a method to create these files without using Apache):
  152 {{{#!sh
  153  $ sudo htpasswd -c /path/to/env/.htpasswd username
  154 }}}
  155 then for additional users:
  156 {{{#!sh
  157  $ sudo htpasswd /path/to/env/.htpasswd username2
  158 }}}
  160 Then to start `tracd` run something like this:
  161 {{{#!sh
  162  $ tracd -p 8080 --basic-auth="project,/fullpath/environmentname/.htpasswd,realmname" /path/to/project
  163 }}}
  165 For example:
  166 {{{#!sh
  167  $ tracd -p 8080 --basic-auth="project,/srv/tracenv/testenv/.htpasswd,My Test Env" /path/to/project
  168 }}}
  169 ''Note:'' You might need to pass "-m" as a parameter to htpasswd on some platforms (OpenBSD).
  171 === Digest authentication: Using a htdigest password file
  173 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.
  175 Note that you can start tracd without the `--auth` argument, but if you click on the ''Login'' link you will get an error.
  177 === Generating Passwords Without Apache
  179 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.
  181 Trac also provides `htpasswd` and `htdigest` scripts in `contrib`:
  182 {{{#!sh
  183 $ ./contrib/htpasswd.py -cb htpasswd user1 user1
  184 $ ./contrib/htpasswd.py -b htpasswd user2 user2
  185 }}}
  187 {{{#!sh
  188 $ ./contrib/htdigest.py -cb htdigest trac user1 user1
  189 $ ./contrib/htdigest.py -b htdigest trac user2 user2
  190 }}}
  192 ==== Using `md5sum`
  193 It is possible to use `md5sum` utility to generate digest-password file:
  194 {{{#!sh
  195 user=
  196 realm=
  197 password=
  198 path_to_file=
  199 echo ${user}:${realm}:$(printf "${user}:${realm}:${password}" | md5sum - | sed -e 's/\s\+-//') > ${path_to_file}
  200 }}}
  202 == Reference
  204 Here's the online help, as a reminder (`tracd -h` or `tracd --help`):
  205 {{{
  206 usage: tracd [-h] [--version] [-e PARENTDIR | -s]
  207              [-a DIGESTAUTH | --basic-auth BASICAUTH] [-p PORT] [-b HOSTNAME]
  208              [--protocol {http,https,scgi,ajp,fcgi}] [--certfile CERTFILE]
  209              [--keyfile KEYFILE] [-q] [--base-path BASE_PATH]
  210              [--http10 | --http11] [-r | -d] [--pidfile PIDFILE]
  211              [--umask MASK] [--group GROUP] [--user USER]
  212              [envs [envs ...]]
  214 positional arguments:
  215   envs                  path of the project environment(s)
  217 optional arguments:
  218   -h, --help            show this help message and exit
  219   --version             show program's version number and exit
  220   -e PARENTDIR, --env-parent-dir PARENTDIR
  221                         parent directory of the project environments
  222   -s, --single-env      only serve a single project without the project list
  223   -a DIGESTAUTH, --auth DIGESTAUTH
  224                         [projectdir],[htdigest_file],[realm]
  225   --basic-auth BASICAUTH
  226                         [projectdir],[htpasswd_file],[realm]
  227   -p PORT, --port PORT  the port number to bind to
  228   -b HOSTNAME, --hostname HOSTNAME
  229                         the host name or IP address to bind to
  230   --protocol {http,https,scgi,ajp,fcgi}
  231                         the server protocol (default: http)
  232   --certfile CERTFILE   PEM certificate file for HTTPS
  233   --keyfile KEYFILE     PEM key file for HTTPS
  234   -q, --unquote         unquote PATH_INFO (may be needed when using the ajp
  235                         protocol)
  236   --base-path BASE_PATH
  237                         the initial portion of the request URL's "path"
  238   --http10              use HTTP/1.0 protocol instead of HTTP/1.1
  239   --http11              use HTTP/1.1 protocol (default)
  240   -r, --auto-reload     restart automatically when sources are modified
  241   -d, --daemonize       run in the background as a daemon
  242   --pidfile PIDFILE     file to write pid when daemonizing
  243   --umask MASK          when daemonizing, file mode creation mask to use, in
  244                         octal notation (default: 022)
  245   --group GROUP         the group to run as
  246   --user USER           the user to run as
  247 }}}
  249 Use the -d option so that tracd doesn't hang if you close the terminal window where tracd was started.
  251 == Tips
  253 === Serving static content
  255 If `tracd` is the only web server used for the project, 
  256 it can also be used to distribute static content 
  257 (tarballs, Doxygen documentation, etc.)
  259 This static content should be put in the `$TRAC_ENV/htdocs` folder,
  260 and is accessed by URLs like `<project_URL>/chrome/site/...`.
  262 Example: given a `$TRAC_ENV/htdocs/software-0.1.tar.gz` file,
  263 the corresponding relative URL would be `/<project_name>/chrome/site/software-0.1.tar.gz`, 
  264 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).
  266 === Using tracd behind a proxy
  268 In some situations when you choose to use tracd behind Apache or another web server.
  270 In this situation, you might experience issues with redirects, like being redirected to URLs with the wrong host or protocol. In this case (and only in this case), setting the `[trac] use_base_url_for_redirect` to `true` can help, as this will force Trac to use the value of `[trac] base_url` for doing the redirects.
  272 If you're using the AJP protocol to connect with `tracd` (which is possible if you have flup installed), then you might experience problems with double quoting. Consider adding the `--unquote` parameter.
  274 See also [trac:TracOnWindowsIisAjp], [trac:TracNginxRecipe].
  276 === Authentication for tracd behind a proxy
  277 It is convenient to provide central external authentication to your tracd instances, instead of using `--basic-auth`. There is some discussion about this in [trac:#9206].
  279 Below is example configuration based on Apache 2.2, mod_proxy, mod_authnz_ldap.
  281 First we bring tracd into Apache's location namespace.
  283 {{{#!apache
  284 <Location /project/proxified>
  285         Require ldap-group cn=somegroup, ou=Groups,dc=domain.com
  286         Require ldap-user somespecificusertoo
  287         ProxyPass http://localhost:8101/project/proxified/
  288         # Turns out we don't really need complicated RewriteRules here at all
  289         RequestHeader set REMOTE_USER %{REMOTE_USER}s
  290 </Location>
  291 }}}
  293 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:
  294 {{{#!python
  295 from trac.core import *
  296 from trac.config import BoolOption
  297 from trac.web.api import IAuthenticator
  299 class MyRemoteUserAuthenticator(Component):
  301     implements(IAuthenticator)
  303     obey_remote_user_header = BoolOption('trac', 'obey_remote_user_header', 'false', 
  304                """Whether the 'Remote-User:' HTTP header is to be trusted for user logins 
  305                 (''since ??.??').""") 
  307     def authenticate(self, req):
  308         if self.obey_remote_user_header and req.get_header('Remote-User'): 
  309             return req.get_header('Remote-User') 
  310         return None
  312 }}}
  314 Add this new parameter to your TracIni:
  315 {{{#!ini
  316 [trac]
  317 ...
  318 obey_remote_user_header = true
  319 ...
  320 }}}
  322 Run tracd:
  323 {{{#!sh
  324 tracd -p 8101 -s proxified --base-path=/project/proxified
  325 }}}
  327 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.
  329 Global config (e.g. `/srv/trac/conf/trac.ini`):
  330 {{{#!ini
  331 [components]
  332 remote-user-auth.* = enabled
  333 [inherit]
  334 plugins_dir = /srv/trac/plugins
  335 [trac]
  336 obey_remote_user_header = true
  337 }}}
  339 Environment config (e.g. `/srv/trac/envs/myenv`):
  340 {{{#!ini
  341 [inherit]
  342 file = /srv/trac/conf/trac.ini
  343 }}}
  345 === Serving a different base path than /
  346 Tracd supports serving projects with different base urls than /<project>. The parameter name to change this is
  347 {{{#!sh
  348  $ tracd --base-path=/some/path
  349 }}}
  351 ----
  352 See also: TracInstall, TracCgi, TracModPython, TracGuide, [trac:TracOnWindowsStandalone#RunningTracdasservice Running tracd.exe as a Windows service]