Changeset 40226


Ignore:
Timestamp:
03/10/17 20:22:13 (7 years ago)
Author:
obi
Message:

reset wiki 40200

Location:
wiki/pages
Files:
341 edited

Legend:

Unmodified
Added
Removed

  • wiki/pages/Plugins-Full

    r40221 r40226  
     1----
     2'''10 Plugins''' [=#point10] ([wiki:German-Wiki#point0.1 Inhaltsverzeichnis])
     3----
     4----
     5'''10.1 Bildschirmschoner''' [=#point10.1] ([WikiStart#point0 Inhaltsverzeichnis])
     6----
     7[[Image(source:/ipk/source/screensaver_default_1_0/preview/prev.png)]]
     8[[Image(source:/ipk/source/screensaver_animation.kidds_1.0/preview/prev.png)]]
     9[[Image(source:/ipk/source/screensaver_beach_1.0/preview/prev.png)]]
     10[[Image(source:/ipk/source/screensaver_bikes.motorcycles_1.0/preview/prev.png)]]
     11[[Image(source:/ipk/source/screensaver_brands.logos_1.0/preview/prev.png)]]
     12[[Image(source:/ipk/source/screensaver_cars_1.0/preview/prev.png)]]
     13[[Image(source:/ipk/source/screensaver_celebrations_1.0/preview/prev.png)]]
     14[[Image(source:/ipk/source/screensaver_celebrities_1.0/preview/prev.png)]]
     15[[Image(source:/ipk/source/screensaver_christmas_1.0/preview/prev.png)]]
     16[[Image(source:/ipk/source/screensaver_creative.graphics_1.0/preview/prev.png)]]
     17[[Image(source:/ipk/source/screensaver_cute_1.0/preview/prev.png)]]
     18[[Image(source:/ipk/source/screensaver_digital.universe_1.0/preview/prev.png)]]
     19[[Image(source:/ipk/source/screensaver_dreamy.fantasy_1.0/preview/prev.png)]]
     20[[Image(source:/ipk/source/screensaver_eisriesenwelt_1_0/preview/prev.png)]]
     21[[Image(source:/ipk/source/screensaver_fantasy.girls_1.0/preview/prev.png)]]
     22[[Image(source:/ipk/source/screensaver_fcbayern_1_0/preview/prev.png)]]
     23[[Image(source:/ipk/source/screensaver_flowers_1.0/preview/prev.png)]]
     24[[Image(source:/ipk/source/screensaver_games_1.0/preview/prev.png)]]
     25[[Image(source:/ipk/source/screensaver_HDR-Pictures_1.0/preview/prev.png)]]
     26[[Image(source:/ipk/source/screensaver_hotgirls_1_0/preview/prev.png)]]
     27[[Image(source:/ipk/source/screensaver_hotgirls_2.0/preview/prev.png)]]
     28[[Image(source:/ipk/source/screensaver_inspirational_1.0/preview/prev.png)]]
     29[[Image(source:/ipk/source/screensaver_love_1.0/preview/prev.png)]]
     30[[Image(source:/ipk/source/screensaver_movies_1.0/preview/prev.png)]]
     31[[Image(source:/ipk/source/screensaver_nature.landscape_1.0/preview/prev.png)]]
     32[[Image(source:/ipk/source/screensaver_others_1.0/preview/prev.png)]]
     33[[Image(source:/ipk/source/screensaver_photography_1.0/preview/prev.png)]]
     34[[Image(source:/ipk/source/screensaver_planes_1.0/preview/prev.png)]]
     35[[Image(source:/ipk/source/screensaver_radio_1.0/preview/prev.png)]]
     36[[Image(source:/ipk/source/screensaver_sports_1.0/preview/prev.png)]]
     37[[Image(source:/ipk/source/screensaver_travel.world_1.0/preview/prev.png)]]
     38----
     39'''10.2 Bootlogos''' [=#point10.2] ([WikiStart#point0 Inhaltsverzeichnis])
     40----
     41[[Image(source:/ipk/source/bootlogos_bikergirl_0_1/preview/prev.png)]]
     42[[Image(source:/ipk/source/bootlogos_blueskull_0_1/preview/prev.png)]]
     43[[Image(source:/ipk/source/bootlogos_cityflash_0_1/preview/prev.png)]]
     44[[Image(source:/ipk/source/bootlogos_enigmalinux_0_1/preview/prev.png)]]
     45[[Image(source:/ipk/source/bootlogos_fantasygirl2_0_1/preview/prev.png)]]
     46[[Image(source:/ipk/source/bootlogos_fantasygirl_0_1/preview/prev.png)]]
     47[[Image(source:/ipk/source/bootlogos_firelady_0_1/preview/prev.png)]]
     48[[Image(source:/ipk/source/bootlogos_fireskull_0_1/preview/prev.png)]]
     49[[Image(source:/ipk/source/bootlogos_footballgirls_0_1/preview/prev.png)]]
     50[[Image(source:/ipk/source/bootlogos_ghostrider_0_1/preview/prev.png)]]
     51[[Image(source:/ipk/source/bootlogos_giantgirl_0_1/preview/prev.png)]]
     52[[Image(source:/ipk/source/bootlogos_iceage2scrapufs910_0_1/preview/prev.png)]]
     53[[Image(source:/ipk/source/bootlogos_linuxgirl_0_1/preview/prev.png)]]
     54[[Image(source:/ipk/source/bootlogos_planets_0_1/preview/prev.png)]]
     55[[Image(source:/ipk/source/bootlogos_thegrimreaper_0_1/preview/prev.png)]]
     56[[Image(source:/ipk/source/bootlogos_zombie_0_1/preview/prev.png)]]
     57[[Image(source:/ipk/source/bootlogos_TitanNit_0_1/preview/prev.png)]]
     58[[Image(source:/ipk/source/bootlogos_TitanNit_0_2/preview/prev.png)]]
     59[[Image(source:/ipk/source/bootlogos_TitanNit_0_3/preview/prev.png)]]
     60[[Image(source:/ipk/source/bootlogos_TitanNit_0_4/preview/prev.png)]]
     61----
     62'''10.3 Browser''' [=#point10.3] ([WikiStart#point0 Inhaltsverzeichnis])
     63----
     64[[Image(source:/ipk/source.sh4/browser_netsurf/preview/prev.png)]]
     65----
     66'''10.4 Emus''' [=#point10.4] ([WikiStart#point0 Inhaltsverzeichnis])
     67----
     68[[Image(source:/ipk/source.sh4/emus_camd3_3_902/preview/prev.png)]]
     69[[Image(source:/ipk/source.sh4/emus_gbox_800/preview/prev.png)]]
     70[[Image(source:/ipk/source.sh4/emus_gbox_806/preview/prev.png)]]
     71[[Image(source:/ipk/source.sh4/emus_incubus_1_22/preview/prev.png)]]
     72[[Image(source:/ipk/source.sh4/emus_mbox0.6_0010/preview/prev.png)]]
     73[[Image(source:/ipk/source.sh4/emus_mgcamd_1_35/preview/prev.png)]]
     74[[Image(source:/ipk/source.sh4/emus_mgcamd_1_38a/preview/prev.png)]]
     75[[Image(source:/ipk/source.sh4/emus_newcs/preview/prev.png)]]
     76[[Image(source:/ipk/source.sh4/emus_oscam_4736v13/preview/prev.png)]]
     77[[Image(source:/ipk/source.sh4/emus_oscam_7209/preview/prev.png)]]
     78[[Image(source:/ipk/source.sh4/emus_oscam_8755/preview/prev.png)]]
     79[[Image(source:/ipk/source.sh4/emus_oscam_8755small/preview/prev.png)]]
     80[[Image(source:/ipk/source.sh4/emus_oscam_8933/preview/prev.png)]]
     81[[Image(source:/ipk/source.sh4/emus_oscam_nightly/preview/prev.png)]]
     82[[Image(source:/ipk/source.sh4/emus_oscam_spezial/preview/prev.png)]]
     83----
     84'''10.5 Infos''' [=#point10.5] ([WikiStart#point0 Inhaltsverzeichnis])
     85----
     86[[Image(source:/ipk/source.sh4/infos_imdb/preview/prev.png)]]
     87[[Image(source:/ipk/source.sh4/infos_imdbapi/preview/prev.png)]]
     88[[Image(source:/ipk/source.sh4/infos_news/preview/prev.png)]]
     89[[Image(source:/ipk/source.sh4/infos_stock/preview/prev.png)]]
     90[[Image(source:/ipk/source.sh4/infos_streaminfo/preview/prev.png)]]
     91[[Image(source:/ipk/source.sh4/infos_tmdb/preview/prev.png)]]
     92[[Image(source:/ipk/source.sh4/infos_weather/preview/prev.png)]]
     93----
     94'''10.6 Kanallisten''' [=#point10.6] ([WikiStart#point0 Inhaltsverzeichnis])
     95----
     96[[Image(source:/ipk/source/settings_default_cable_1_0/preview/prev.png)]]
     97[[Image(source:/ipk/source/settings_default_matze70_sat_1_0/preview/prev.png)]]
     98[[Image(source:/ipk/source/settings_default_sat_1_0/preview/prev.png)]]
     99[[Image(source:/ipk/source/settings_matze70neueDesign_sat19_1_0/preview/prev.png)]]
     100[[Image(source:/ipk/source/settings_sofa_cableBW_1_0/preview/prev.png)]]
     101[[Image(source:/ipk/source/settings_uljanow_1sat_1_0/preview/prev.png)]]
     102[[Image(source:/ipk/source/settings_unitymedia_cable_1_0/preview/prev.png)]]
     103[[Image(source:/ipk/source/settings_bulldog_3xSat_1_0/preview/prev.png)]]
     104----
     105'''10.7 Keymaps''' [=#point10.7] ([WikiStart#point0 Inhaltsverzeichnis])
     106----
     107[[Image(source:/ipk/source.sh4/keymaps_neutrino/preview/prev.png)]]
     108[[Image(source:/ipk/source.sh4/keymaps_neutrino/preview/prev.png)]]
     109----
     110'''10.8 LCD Pearl Skins''' [=#point10.8] ([WikiStart#point0 Inhaltsverzeichnis])
     111----
     112[[Image(source:/ipk/source/lcdpearlskins_atemio_style/preview/prev.png)]]
     113[[Image(source:/ipk/source/lcdpearlskins_blau_mit_picons/preview/prev.png)]]
     114[[Image(source:/ipk/source/lcdpearlskins_mrp/preview/prev.png)]]
     115[[Image(source:/ipk/source/lcdpearlskins_only_picon/preview/prev.png)]]
     116[[Image(source:/ipk/source/lcdpearlskins_picon_gross_schwarz/preview/prev.png)]]
     117[[Image(source:/ipk/source/lcdpearlskins_schwarz_ohne_picons/preview/prev.png)]]
     118
     119----
     120'''10.9 LCD Samsung Skins''' [=#point10.9] ([WikiStart#point0 Inhaltsverzeichnis])
     121----
     122[[Image(source:/ipk/source/lcdsamsungskins_channel_Analoguhr/preview/prev.png)]]
     123[[Image(source:/ipk/source/lcdsamsungskins_channel_Digitaluhr_gelb/preview/prev.png)]]
     124[[Image(source:/ipk/source/lcdsamsungskins_channel_Digitaluhr_Trikots/preview/prev.png)]]
     125[[Image(source:/ipk/source/lcdsamsungskins_Digitaluhr_blau/preview/prev.png)]]
     126[[Image(source:/ipk/source/lcdsamsungskins_Holzuhr_Standby/preview/prev.png)]]
     127[[Image(source:/ipk/source/lcdsamsungskins_PICONS_320x240/preview/prev.png)]]
     128----
     129'''10.10 Netzwerk''' [=#point10.10] ([WikiStart#point0 Inhaltsverzeichnis])
     130----
     131[[Image(source:/ipk/source.sh4/network_dlna/preview/prev.png)]]
     132[[Image(source:/ipk/source.sh4/network_facebook/preview/prev.png)]]
     133[[Image(source:/ipk/source.sh4/networklib_e2webserv/preview/prev.png)]]
     134[[Image(source:/ipk/source.sh4/networklib_libpack/preview/prev.png)]]
     135[[Image(source:/ipk/source.sh4/networklib_libsmbclient_3_0_28b/preview/prev.png)]]
     136[[Image(source:/ipk/source.sh4/network_openvpn/preview/prev.png)]]
     137[[Image(source:/ipk/source.sh4/network_networkbrowser/preview/prev.png)]]
     138[[Image(source:/ipk/source.sh4/network_samba/preview/prev.png)]]
     139----
     140'''10.11 Player''' [=#point10.11] ([WikiStart#point0 Inhaltsverzeichnis])
     141----
     142[[Image(source:/ipk/source.sh4/playersnp_codecpack/preview/prev.png)]]
     143[[Image(source:/ipk/source.sh4/playersnp_dtsdownmix/preview/prev.png)]]
     144[[Image(source:/ipk/source.sh4/playersnp_dvdplayer/preview/prev.png)]]
     145[[Image(source:/ipk/source.sh4/players_gmediarender/preview/prev.png)]]
     146[[Image(source:/ipk/source.sh4/playersnp_hbbtv/preview/prev.png)]]
     147[[Image(source:/ipk/source.sh4/players_mc/preview/prev.png)]]
     148[[Image(source:/ipk/source.sh4/players_tithek/preview/prev.png)]]
     149[[Image(source:/ipk/source.sh4/players_tmc/preview/prev.png)]]
     150[[Image(source:/ipk/source/players_foldericons_1_0/preview/prev.png)]]
     151----
     152'''10.12 Schriftarten''' [=#point10.12] ([WikiStart#point0 Inhaltsverzeichnis])
     153----
     154[[Image(source:/ipk/source/fonts_actionmanitalic_1_0/preview/prev.png)]]
     155[[Image(source:/ipk/source/fonts_alpharomanieg_1_0/preview/prev.png)]]
     156[[Image(source:/ipk/source/fonts_croissant_1_0/preview/prev.png)]]
     157[[Image(source:/ipk/source/fonts_default_1_0/preview/prev.png)]]
     158[[Image(source:/ipk/source/fonts_digifaceregular_1_0/preview/prev.png)]]
     159[[Image(source:/ipk/source/fonts_goodtime_1_0/preview/prev.png)]]
     160[[Image(source:/ipk/source/fonts_ihatecomicsans_1_0/preview/prev.png)]]
     161[[Image(source:/ipk/source/fonts_lydianbolditalicbt_1_0/preview/prev.png)]]
     162[[Image(source:/ipk/source/fonts_mightyzeocaps_1_0/preview/prev.png)]]
     163[[Image(source:/ipk/source/fonts_monoglyceridedemibold_1_0/preview/prev.png)]]
     164[[Image(source:/ipk/source/fonts_newgothicbt_1_0/preview/prev.png)]]
     165[[Image(source:/ipk/source/fonts_paddingtonbold_1_0/preview/prev.png)]]
     166[[Image(source:/ipk/source/fonts_ploverbold_1_0/preview/prev.png)]]
     167----
     168'''10.13 Senderlogos (Picons)''' [=#point10.13] ([WikiStart#point0 Inhaltsverzeichnis])
     169----
     170[[Image(source:/ipk/source/picons_black3d_SAT13_0/preview/prev.png)]]
     171[[Image(source:/ipk/source/picons_black3d_SAT19_2/preview/prev.png)]]
     172[[Image(source:/ipk/source/picons_black3d_SAT23_5/preview/prev.png)]]
     173
     174[[Image(source:/ipk/source/picons_gold_SAT13_0/preview/prev.png)]]
     175[[Image(source:/ipk/source/picons_gold_SAT19_2/preview/prev.png)]]
     176[[Image(source:/ipk/source/picons_gold_SAT23_5/preview/prev.png)]]
     177[[Image(source:/ipk/source/picons_gold_SAT28_2/preview/prev.png)]]
     178
     179[[Image(source:/ipk/source/picons_KabelBW/preview/prev.png)]]
     180[[Image(source:/ipk/source/picons_KabelDblack3d/preview/prev.png)]]
     181[[Image(source:/ipk/source/picons_KabelDtransparent/preview/prev.png)]]
     182
     183[[Image(source:/ipk/source/picons_spiegel_SAT19_2/preview/prev.png)]]
     184
     185[[Image(source:/ipk/source/picons_transparent_SAT13_0/preview/prev.png)]]
     186[[Image(source:/ipk/source/picons_transparent_SAT19_2/preview/prev.png)]]
     187[[Image(source:/ipk/source/picons_transparent_SAT23_5/preview/prev.png)]]
     188[[Image(source:/ipk/source/picons_transparent_SAT28_2/preview/prev.png)]]
     189[[Image(source:/ipk/source/picons_transparent_small_black_SAT19_2/preview/prev.png)]]
     190
     191[[Image(source:/ipk/source/picons_white3d_SAT13_0/preview/prev.png)]]
     192[[Image(source:/ipk/source/picons_white3d_SAT19_2/preview/prev.png)]]
     193[[Image(source:/ipk/source/picons_white3d_SAT23_5/preview/prev.png)]]
     194[[Image(source:/ipk/source/picons_white3d_SAT28_2/preview/prev.png)]]
     195
     196[[Image(source:/ipk/source/picons_white70_SAT13_0/preview/prev.png)]]
     197[[Image(source:/ipk/source/picons_white70_SAT19_2/preview/prev.png)]]
     198[[Image(source:/ipk/source/picons_white70_SAT23_5/preview/prev.png)]]
     199[[Image(source:/ipk/source/picons_white70_SAT28_2/preview/prev.png)]]
     200
     201[[Image(source:/ipk/source/picons_X_LightTransparent_SAT13_0/preview/prev.png)]]
     202[[Image(source:/ipk/source/picons_X_LightTransparent_SAT19_2/preview/prev.png)]]
     203[[Image(source:/ipk/source/picons_X_LightTransparent_SAT19_2_small/preview/prev.png)]]
     204[[Image(source:/ipk/source/picons_X_LightTransparent_SAT23_5/preview/prev.png)]]
     205[[Image(source:/ipk/source/picons_X_LightTransparent_SAT28_2/preview/prev.png)]]
     206----
     207'''10.14 Skins''' [=#point10.14] ([wiki:German-Wiki#point0.1 Inhaltsverzeichnis])
     208----
     209
     210||= '''0Acht5Zehn''' =||= '''0Acht5Zehnblack''' =||= '''0Acht5Zehnwhite''' =||= '''Cool''' =||= '''CoolMiniTV''' =||= '''Default''' =||
     211||= [[Image(source:/ipk/source/skins_0Acht5Zehn/preview/prev.png,link=source:/ipk/source/skins_0Acht5Zehn/_path_/usr/local/share/titan/skin/0Acht5Zehn)]] =||=[[Image(source:/ipk/source/skins_0Acht5Zehnblack/preview/prev.png,link=source:/ipk/source/skins_0Acht5Zehnblack/_path_/usr/local/share/titan/skin/0Acht5Zehn_black)]] =||= [[Image(source:/ipk/source/skins_0Acht5Zehnwhite/preview/prev.png,link=source:/ipk/source/skins_0Acht5Zehnwhite/_path_/usr/local/share/titan/skin/0Acht5Zehn_white)]] =||= [[Image(source:/ipk/source/skins_cool/preview/prev.png,link=source:/ipk/source/skins_cool/_path_/usr/local/share/titan/skin/cool)]] =||= [[Image(source:/ipk/source/skins_coolMiniTV/preview/prev.png,link=source:/ipk/source/skins_coolMiniTV/_path_/usr/local/share/titan/skin/coolMiniTV)]] =||= [[Image(source:/ipk/source/skins_default/preview/prev.png,link=source:/ipk/source/skins_default/_path_/usr/local/share/titan/skin/default)]]
     212=||
     213[[br]]
     214||= '''Default no MiniTV''' =||= '''Megastyle-Blue''' =||= '''Megastyle-Blue-MiniTV''' =||= '''MegaStyle-Grey''' =||= '''MegaStyle-Grey-MiniTV''' =||= '''MetrixHD''' =
     215||= [[Image(source:/ipk/source/skins_defnominitv/preview/prev.png,link=source:/ipk/source/skins_default/_path_/usr/local/share/titan/skin/default)]]||= [[Image(source:/ipk/source/skins_MegaStyle_blue/preview/prev.png,link=source:/ipk/source/skins_MegaStyle_blue/_path_/usr/local/share/titan/skin/MegaStyle-Blue)]] =||=[[Image(source:/ipk/source/skins_MegaStyle_blue_MiniTV/preview/prev.png,link=source:/ipk/source/skins_MegaStyle_blue_MiniTV/_path_/usr/local/share/titan/skin/MegaStyle-Blue-MiniTV)]] =||= [[Image(source:/ipk/source/skins_MegaStyle_grey/preview/prev.png,link=source:/ipk/source/skins_MegaStyle_grey/_path_/usr/local/share/titan/skin/MegaStyle-Grey)]] =||= [[Image(source:/ipk/source/skins_MegaStyle_grey_MiniTV/preview/prev.png,link=source:/ipk/source/skins_MegaStyle_grey_MiniTV/_path_/usr/local/share/titan/skin/MegaStyle-Grey-MiniTV)]] =||= [[Image(source:/ipk/source/skins_MetrixHD/preview/prev.png,link=source:/ipk/source/skins_MetrixHD/_path_/usr/local/share/titan/skin/MetrixHD)]]=||
     216[[br]]
     217||= '''NoGfx''' =||= '''NoGfx Grey''' =||= '''SmartTV''' =||= '''tobayer01''' =||= '''ufs912''' =||
     218||= [[Image(source:/ipk/source/skins_nogfx/preview/prev.png,link=source:/ipk/source/skins_nogfx/_path_/usr/local/share/titan/skin/nogfx)]]=||= [[Image(source:/ipk/source/skins_nogfx_grey/preview/prev.png,link=source:/ipk/source/skins_nogfx_grey/_path_/usr/local/share/titan/skin/nogfx_grey)]] =||=[[Image(source:/ipk/source/skins_smartTV/preview/prev.png,link=source:/ipk/source/skins_smartTV/_path_/usr/local/share/titan/skin/smartTV)]] =||= [[Image(source:/ipk/source/skins_tobayer01/preview/prev.png,link=source:/ipk/source/skins_tobayer01/_path_/usr/local/share/titan/skin/tobayer01)]] =||= [[Image(source:/ipk/source/skins_ufs912/preview/prev.png,link=source:/ipk/source/skins_ufs912/_path_/usr/local/share/titan/skin/ufs912)]]
     219=||
     220----
     221'''10.15 Spiele''' [=#point10.15] ([WikiStart#point0 Inhaltsverzeichnis])
     222----
     223[[Image(source:/ipk/source.sh4/games_catcatch/preview/prev.png)]]
     224[[Image(source:/ipk/source.sh4/games_wins3/preview/prev.png)]]
     225----
     226'''10.16 Tools''' [=#point10.16] ([WikiStart#point0 Inhaltsverzeichnis])
     227----
     228[[Image(source:/ipk/source.sh4/tools_autotimer/preview/prev.png)]]
     229[[Image(source:/ipk/source.sh4/tools_callmonitor/preview/prev.png)]]
     230[[Image(source:/ipk/source.sh4/tools_filemanager/preview/prev.png)]]
     231[[Image(source:/ipk/source.sh4/tools_IP-Kamera/preview/prev.png)]]
     232[[Image(source:/ipk/source.sh4/tools_lcdpearl1/preview/prev.png)]]
     233[[Image(source:/ipk/source.sh4/tools_lcdsamsung/preview/prev.png)]]
     234[[Image(source:/ipk/source.sh4/tools_optimize/preview/prev.png)]]
     235[[Image(source:/ipk/source.sh4/tools_panel/preview/prev.png)]]
     236[[Image(source:/ipk/source.sh4/tools_PermanentTime/preview/prev.png)]]
     237[[Image(source:/ipk/source.sh4/tools_tsschnitt/preview/prev.png)]]
     238[[Image(source:/ipk/source.sh4/tools_rgui/preview/prev.png)]]
     239[[Image(source:/ipk/source.sh4/tools_scriptexec/preview/prev.png)]]
     240[[Image(source:/ipk/source.sh4/tools_stopifnotused/preview/prev.png)]]
     241[[Image(source:/ipk/source.sh4/tools_parted/preview/prev.png)]]
     242[[Image(source:/ipk/source.sh4/tools_usbreset/preview/prev.png)]]
     243[[Image(source:/ipk/source.sh4/tools_zapback/preview/prev.png)]]
     244----
     245'''10.17 WLAN Module''' [=#point10.17] ([WikiStart#point0 Inhaltsverzeichnis])
     246----
     247[[Image(source:/ipk/source.sh4/wlan_8192cu/preview/prev.png)]]
     248[[Image(source:/ipk/source.sh4/wlan_8712u/preview/prev.png)]]
     249[[Image(source:/ipk/source.sh4/wlan_rt2870sta/preview/prev.png)]]
     250[[Image(source:/ipk/source.sh4/wlan_rt3070sta/preview/prev.png)]]
     251[[Image(source:/ipk/source.sh4/wlan_rt5370sta/preview/prev.png)]]

  • wiki/pages/RealMedia

    r40221 r40226  
     1RealMedia ist die Sammelbezeichnung für die Dateiformate und die damit verbundenen Client- und Serverprodukte des Software-Herstellers RealNetworks.
     2
     3Insbesondere bezeichnet Real Media das Audioformat RealAudio und das Videoformat RealVideo.

  • wiki/pages/RecentChanges

    r40221 r40226  
     1''' [TitleIndex Index by Title] ''' | ''' Index by Date '''
     2
     3[[RecentChanges]]

  • wiki/pages/SandBox

    r40221 r40226  
     1= The Sandbox =
     2
     3This is just a page to practice and learn WikiFormatting.
     4
     5Go ahead, edit it freely.

  • wiki/pages/TicketQuery

    r40221 r40226  
     1= !TicketQuery Wiki Macro
     2
     3The !TicketQuery macro lets you display information on tickets within wiki pages.
     4The query language used by the `[[TicketQuery]]` macro is described in [TracQuery#UsingtheTicketQueryMacro TracQuery] page.
     5
     6== Usage
     7
     8[[MacroList(TicketQuery)]]
     9
     10== Example
     11
     12||= **Example** =||= **Result** =||= **Macro** =||
     13|-----------------------------------------------------------
     14||=Number of [query:status=new&milestone= Triage tickets]: =||\
     15|| **[[TicketQuery(status=new&milestone=,count)]]**||\
     16|| `[[TicketQuery(status=new&milestone=,count)]]` ||
     17|-----------------------------------------------------------
     18||=Number of new tickets: =||\
     19|| **[[TicketQuery(status=new,count)]]**||\
     20|| `[[TicketQuery(status=new,count)]]` ||
     21|-----------------------------------------------------------
     22||=Number of reopened tickets: =||\
     23|| **[[TicketQuery(status=reopened,count)]]**||\
     24|| `[[TicketQuery(status=reopened,count)]]` ||
     25|-----------------------------------------------------------
     26||=Number of assigned tickets: =||\
     27|| **[[TicketQuery(status=assigned,count)]]**||\
     28|| `[[TicketQuery(status=assigned,count)]]` ||
     29|-----------------------------------------------------------
     30||=Number of invalid tickets: =||\
     31|| **[[TicketQuery(status=closed,resolution=invalid,count)]]**||\
     32|| `[[TicketQuery(status=closed,resolution=invalid,count)]]` ||
     33|-----------------------------------------------------------
     34||=Number of worksforme tickets: =||\
     35|| **[[TicketQuery(status=closed,resolution=worksforme,count)]]**||\
     36|| `[[TicketQuery(status=closed,resolution=worksforme,count)]]` ||
     37|-----------------------------------------------------------
     38||=Number of duplicate tickets: =||\
     39|| **[[TicketQuery(status=closed,resolution=duplicate,count)]]**||\
     40|| `[[TicketQuery(status=closed,resolution=duplicate,count)]]` ||
     41|-----------------------------------------------------------
     42||=Number of wontfix tickets: =||\
     43|| **[[TicketQuery(status=closed,resolution=wontfix,count)]]**||\
     44|| `[[TicketQuery(status=closed,resolution=wontfix,count)]]` ||
     45|-----------------------------------------------------------
     46||=Number of fixed tickets: =||\
     47|| **[[TicketQuery(status=closed,resolution=fixed,count)]]**||\
     48|| `[[TicketQuery(status=closed,resolution=fixed,count)]]` ||
     49|-----------------------------------------------------------
     50||=Total number of tickets: =||\
     51|| **[[TicketQuery(count)]]**||\
     52|| `[[TicketQuery(count)]]` ||
     53|-----------------------------------------------------------
     54||=Number of tickets reported **or** owned by current user: =||\
     55|| **[[TicketQuery(reporter=$USER,or,owner=$USER,count)]]**||\
     56|| `[[TicketQuery(reporter=$USER,or,owner=$USER,count)]]` ||
     57|-----------------------------------------------------------
     58||=Number of tickets created this month: =||\
     59|| **[[TicketQuery(created=thismonth..,count)]]**||\
     60|| `[[TicketQuery(created=thismonth..,count)]]` ||
     61|-----------------------------------------------------------
     62||=Last 3 modified tickets: =||\
     63||**[[TicketQuery(max=3,order=modified,desc=1,compact)]]**||\
     64|| `[[TicketQuery(max=3,order=modified,desc=1,compact)]]` ||
     65|-----------------------------------------------------------
     66{{{#!th rowspan=2, style="text-align: left;"
     67Details of ticket #1:
     68}}}
     69{{{#!td style="border-bottom: 0;"
     70}}}
     71{{{#!td
     72`[[TicketQuery(id=1,col=id|owner|reporter,rows=summary,table)]]`
     73}}}
     74|-
     75{{{#!td colspan=2, style="border-top: 0;"
     76[[TicketQuery(id=1,col=id|owner|reporter,rows=summary,table)]]
     77}}}
     78|-----------------------------------------------------------
     79
     80== Using the `[[TicketQuery]]` Macro
     81
     82The [trac:TicketQuery TicketQuery] macro lets you display lists of tickets matching certain criteria anywhere you can use WikiFormatting.
     83
     84Example:
     85{{{
     86[[TicketQuery(version=0.6|0.7&resolution=duplicate)]]
     87}}}
     88
     89This is displayed as:
     90  [[TicketQuery(version=0.6|0.7&resolution=duplicate)]]
     91
     92Just like the [wiki:TracQuery#UsingTracLinks query: wiki links], the parameter of this macro expects a query string formatted according to the rules of the simple [wiki:TracQuery#QueryLanguage ticket query language]. This also displays the link and description of a single ticket:
     93{{{
     94[[TicketQuery(id=123)]]
     95}}}
     96
     97This is displayed as:
     98  [[TicketQuery(id=123)]]
     99
     100A more compact representation without the ticket summaries is:
     101{{{
     102[[TicketQuery(version=0.6|0.7&resolution=duplicate, compact)]]
     103}}}
     104
     105This is displayed as:
     106  [[TicketQuery(version=0.6|0.7&resolution=duplicate, compact)]]
     107
     108Finally, if you wish to receive only the number of defects that match the query, use the `count` parameter:
     109{{{
     110[[TicketQuery(version=0.6|0.7&resolution=duplicate, count)]]
     111}}}
     112
     113This is displayed as:
     114  [[TicketQuery(version=0.6|0.7&resolution=duplicate, count)]]
     115
     116----
     117See also: TracQuery, TracTickets, TracReports, TracGuide

  • wiki/pages/TitleIndex

    r40221 r40226  
     1''' Index by Title ''' | ''' [RecentChanges Index by Date] '''
     2
     3[[TitleIndex(format=group,min=4)]]

  • wiki/pages/TracAccessibility

    r40221 r40226  
     1= Accessibility Support in Trac =
     2
     3Not every user has a graphic environment with a mouse or other pointing device. Some users rely on keyboard, alternative keyboard or voice input to navigate links, activate form controls, etc. In a Trac session, users can use devices other than a pointing device by enabling keyboard shortcuts through the [/prefs/keybindings Keyboard Shortcuts] preferences panel.
     4
     5Trac supports accessibility keys for the most common operations. The access keys differ by browser and the following work for several browsers, but see [http://en.wikipedia.org/wiki/Access_key#Access_in_different_browsers access in different browsers] for more details.
     6 - on Linux platforms, press any of the keys listed below in combination with the `<Alt>` key
     7 - on a Mac, use the `<Ctrl>` + `<Opt>` key instead
     8 - on Windows, you need to hit `<Shift> + <Alt> + <Key>`. This works for the most common browsers, such as Firefox, Chrome, Safari and Internet Explorer
     9
     10== Global Access Keys ==
     11
     12 * `1` - WikiStart
     13 * `2` - [TracTimeline Timeline]
     14 * `3` - [TracRoadmap Roadmap]
     15 * `4` - [TracSearch Search]
     16 * `6` - [TracGuide Trac Guide / Documentation]
     17 * `7` - [TracTickets New Ticket]
     18 * `9` - [/about About Trac]
     19 * `e` - Edit (wiki or report)
     20 * `r` - Preview (wiki or ticket)
     21 * `f` - Search
     22
     23
     24----
     25See also: TracGuide

  • wiki/pages/TracAdmin

    r40221 r40226  
     1= TracAdmin
     2
     3[[PageOutline(2-5, Contents, floated)]]
     4[[TracGuideToc]]
     5
     6Trac is distributed with a powerful command-line configuration tool. This tool can be used  to configure and customize your Trac-installation to better fit your needs.
     7
     8Some of those operations can also be performed via the web administration module.
     9
     10== Usage
     11
     12For nearly every `trac-admin` command, you'll need to specify the path to the TracEnvironment that you want to administer as the first argument, for example:
     13{{{
     14trac-admin /path/to/projenv wiki list
     15}}}
     16
     17The only exception is for the `help` command, but even in this case if you omit the environment, you'll only get a very succinct list of commands (`help` and `initenv`), the same list you'd get when invoking `trac-admin` alone.
     18Also, `trac-admin --version` will tell you about the Trac version (e.g. 0.12) corresponding to the program.
     19
     20If you want to get a comprehensive list of the available commands and sub-commands, you need to specify an existing environment:
     21{{{
     22trac-admin /path/to/projenv help
     23}}}
     24
     25Some commands have a more detailed help, which you can access by specifying the command's name as a subcommand for `help`:
     26
     27{{{
     28trac-admin /path/to/projenv help <command>
     29}}}
     30
     31=== `trac-admin <targetdir> initenv` === #initenv
     32
     33This subcommand is very important as it's the one used to create a TracEnvironment in the specified `<targetdir>`. That directory must not exist prior to the call.
     34
     35[[TracAdminHelp(initenv)]]
     36
     37It supports an extra `--inherit` option, which can be used to specify a global configuration file which can be used to share settings between several environments. You can also inherit from a shared configuration afterwards, by setting the `[inherit] file` option in the `conf/trac.ini` file in your newly created environment, but the advantage of specifying the inherited configuration file at environment creation time is that only the options ''not'' already specified in the global configuration file will be written in the created environment's `conf/trac.ini` file.
     38See TracIni#GlobalConfiguration.
     39
     40Note that in version 0.11 of Trac, `initenv` lost an extra last argument `<templatepath>`, which was used in previous versions to point to the `templates` folder. If you are using the one-liner '`trac-admin /path/to/trac/ initenv <projectname> <db> <repostype> <repospath>`' in the above and getting an error that reads ''''`Wrong number of arguments to initenv: 4`'''', then this is because you're using a `trac-admin` script from an '''older''' version of Trac.
     41
     42== Interactive Mode
     43
     44When passing the environment path as the only argument, `trac-admin` starts in interactive mode.
     45Commands can then be executed on the selected environment using the prompt, which offers tab-completion
     46(on non-Windows environments, and when the Python `readline` module is available) and automatic repetition of the last command issued.
     47
     48Once you're in interactive mode, you can also get help on specific commands or subsets of commands:
     49
     50For example, to get an explanation of the `resync` command, run:
     51{{{
     52> help resync
     53}}}
     54
     55To get help on all the Wiki-related commands, run:
     56{{{
     57> help wiki
     58}}}
     59
     60== Full Command Reference
     61
     62You'll find below the detailed help for all the commands available by default in `trac-admin`. Note that this may not match the list given by `trac-admin <yourenv> help`, as the commands  pertaining to components disabled in that environment won't be available and conversely some plugins activated in the environment can add their own commands.
     63
     64[[TracAdminHelp()]]
     65
     66----
     67See also: TracGuide, TracBackup, TracPermissions, TracEnvironment, TracIni, [trac:TracMigrate TracMigrate]

  • wiki/pages/TracBackup

    r40221 r40226  
     1= Trac Backup
     2
     3[[TracGuideToc]]
     4
     5Backups are simply a copied snapshot of the entire [wiki:TracEnvironment project environment] directory, including the database. Backups can be created using the `hotcopy` command in [wiki:TracAdmin trac-admin].
     6
     7'''Note''': Trac uses the `hotcopy` nomenclature to match that of [http://subversion.tigris.org/ Subversion], to make it easier to remember when managing both Trac and Subversion servers.
     8
     9== Creating a Backup
     10
     11To create a backup of a live TracEnvironment simply run:
     12{{{#!sh
     13$ trac-admin /path/to/projenv hotcopy /path/to/backupdir
     14}}}
     15
     16[wiki:TracAdmin trac-admin] will lock the database while copying.
     17
     18The resulting backup directory is safe to handle using standard file-based backup tools like `tar` or `dump`/`restore`.
     19
     20Please note, the `hotcopy` command will not overwrite a target directory and when such exists, the operation ends with an error: `Command failed: [Errno 17] File exists:` This is discussed in [trac:ticket:3198 #3198].
     21
     22=== Restoring a Backup
     23
     24To restore an environment from a backup, stop the process running Trac, ie the Web server or [wiki:TracStandalone tracd], restore the contents of your backup (path/to/backupdir) to your [wiki:TracEnvironment project environment] directory and restart the service.
     25
     26To restore a PostgreSQL database backup, use the command:
     27{{{#!sh
     28psql -U <user> -d <database> -f postgresql.dump
     29}}}
     30The `<database>` option is the same as the [TracEnvironment#DatabaseConnectionStrings database connection string] in the `[trac]` `database` option of //trac.ini//.
     31
     32----
     33See also: TracAdmin, TracEnvironment, TracGuide, [trac:TracMigrate TracMigrate]

  • wiki/pages/TracBatchModify

    r40221 r40226  
     1= Trac Ticket Batch Modification =
     2[[TracGuideToc]]
     3
     4Trac supports modifying a batch of tickets in one request from [TracQuery custom query] results .
     5
     6To perform a batch modification, select the tickets you wish to modify and set the new field values using the section underneath the query results.
     7
     8== List fields
     9
     10The `Keywords` and `Cc` fields are treated as lists, where list items can be added and/or removed in addition of replacing the entire list value. All list field controls accept multiple items, such as multiple keywords or cc addresses.
     11
     12== Excluded fields
     13
     14Multi-line text fields are not supported, because no valid use-case has been presented for syncing them across several tickets. That restriction applies to the `Description` field as well as to any [TracTicketsCustomFields#AvailableFieldTypesandOptions custom field] of type 'textarea'. However, future versions of Trac could support in conjunction with more suitable actions like 'prepend', 'append' or 'search & replace' ([http://trac-hacks.org/ticket/2415 th:#2415]).

  • wiki/pages/TracBrowser

    r40221 r40226  
     1= The Trac Repository Browser
     2
     3[[TracGuideToc]]
     4
     5The Trac repository browser can be used to browse specific revisions of directories and files stored in the repositories associated with the Trac environment.
     6
     7At the top-level of the repository browser is the '''Repository Index''', listing all the configured repositories.
     8Each repository has a name which is used as a path prefix in a "virtual" file hierarchy encompassing all the available repositories.
     9One of the repositories can be configured with an empty name; this is the default repository. When such a default repository is present, its top-level files and directories are also listed, in a '''Default Repository''' section placed before the repository index. If the default repository is the only repository associated with the Trac environment, then the '''Repository Index''' will be omitted. This means that after upgrading a single-repository Trac of version 0.11 (or earlier) to a multi-repository Trac (0.12), the repository browser will look and feel the same, that single repository becoming automatically the "default" repository.
     10
     11Directory entries are displayed in a list with sortable columns. The list entries can be sorted by ''Name'', ''Size'', ''Age'' or ''Author'' by clicking on the column headers. The sort order can be reversed by clicking on a given column header again.
     12
     13The browser can be used to navigate through the directory structure by clicking on the directory names.
     14Clicking on a file name will show the contents of the file.
     15Clicking on the revision number of a file or directory will take you to the TracRevisionLog for that file.
     16Note that there's also a ''Revision Log'' navigation link that will do the same for the path currently being examined.
     17Clicking on the ''diff'' icon after revision number will display the changes made to the files modified in that revision.
     18Clicking on the ''Age'' of the file - will take you to that changeset in the timeline.
     19
     20It's also possible to browse directories or files as they were in history, at any given repository revision. The default behavior is to display the latest revision but another revision number can easily be selected using the ''View revision'' input field at the top of the page.
     21
     22The color bar next to the ''Age'' column gives a visual indication of the age of the last change to a file or directory, following the convention that '''[[span(style=color:#88f,blue)]]''' is oldest and '''[[span(style=color:#f88,red)]]''' is newest, but this can be [TracIni#browser-section configured].
     23
     24At the top of the browser page, there's a ''Visit'' drop-down menu which you can use to select some interesting places in the repository, for example branches or tags.
     25This is sometimes referred to as the ''browser quickjump'' facility.
     26The precise meaning and content of this menu depends on your repository backend.
     27For Subversion, this list contains by default the top-level trunk directory and sub-directories of the top-level branches and tags directories (`/trunk`, `/branches/*`, and `/tags/*`). This can be [TracIni#svn-section configured] for more advanced cases.
     28
     29If you're using a Javascript enabled browser, you'll be able to expand and collapse directories in-place by clicking on the arrow head at the right side of a directory. Alternatively, the [trac:TracKeys keyboard] can also be used for this:
     30 - use `j` and `k` to select the next or previous entry, starting with the first
     31 - `o` ('''o'''pen) to toggle between expanded and collapsed state of the selected
     32   directory or for visiting the selected file
     33 - `v` ('''v'''iew, '''v'''isit) and `<Enter>`, same as above
     34 - `r` can be used to force the '''r'''eload of an already expanded directory
     35 - `a` can be used to directly visit a file in '''a'''nnotate (blame) mode
     36 - `l` to view the '''l'''og for the selected entry
     37If no row has been selected using `j` or `k` these keys will operate on the entry under the mouse.
     38
     39For the Subversion backend, some advanced additional features are available:
     40 - The `svn:needs-lock` property will be displayed.
     41 - Support for the `svn:mergeinfo` property showing the merged and eligible information.
     42 - Support for browsing the `svn:externals` property, which can be [TracIni#svn:externals-section configured].
     43 - The `svn:mime-type` property is used to select the syntax highlighter for rendering the file. For example, setting `svn:mime-type` to `text/html` will ensure the file is highlighted as HTML, regardless of the file extension. It also allows selecting the character encoding used in the file content. For example, if the file content is encoded in UTF-8, set `svn:mime-type` to `text/html;charset=utf-8`. The `charset=` specification overrides the default encoding defined in the `default_charset` option of the `[trac]` section of [TracIni#trac-section trac.ini].
     44{{{#!comment
     45MMM: I found this section a bit hard to understand. I changed the first item as I understood that well.
     46but I think the other items could be changed also
     47 cboos: in the meantime, I've added the ''advanced'' word as a hint this can be a bit complex...
     48}}}
     49
     50----
     51See also: TracGuide, TracChangeset, TracFineGrainedPermissions

  • wiki/pages/TracCgi

    r40221 r40226  
     1= Installing Trac as CGI
     2[[TracGuideToc]]
     3[[PageOutline]]
     4
     5{{{#!div class=important
     6 ''Please note that using Trac via CGI is the slowest deployment method available. It is slower than [TracModPython mod_python], [TracFastCgi FastCGI] and even [trac:TracOnWindowsIisAjp IIS/AJP] on Windows.''
     7}}}
     8
     9CGI script is the entrypoint that web-server calls when a web-request to an application is made. The `trac.cgi` script can be created using the `trac-admin <env> deploy <dir>` command which automatically substitutes the required paths, see TracInstall#cgi-bin. Make sure the script is executable by your web server.
     10
     11== Apache web-server configuration
     12
     13In [http://httpd.apache.org/ Apache] there are two ways to run Trac as CGI:
     14
     15 1. Use a `ScriptAlias` directive that maps an URL to the `trac.cgi` script (recommended)
     16 1. Copy the `trac.cgi` file into the directory for CGI executables used by your web server (commonly named `cgi-bin`). You can also create a symbolic link, but in that case make sure that the `FollowSymLinks` option is enabled for the `cgi-bin` directory.
     17
     18To make Trac available at `http://yourhost.example.org/trac` add `ScriptAlias` directive to Apache configuration file, changing `trac.cgi` path to match your installation:
     19{{{#!apache
     20ScriptAlias /trac /path/to/www/trac/cgi-bin/trac.cgi
     21}}}
     22
     23 ''Note that this directive requires enabled `mod_alias` module.''
     24
     25If you're using Trac with a single project you need to set its location using the `TRAC_ENV` environment variable:
     26{{{#!apache
     27<Location "/trac">
     28  SetEnv TRAC_ENV "/path/to/projectenv"
     29</Location>
     30}}}
     31
     32Or to use multiple projects you can specify their common parent directory using the `TRAC_ENV_PARENT_DIR` variable:
     33{{{#!apache
     34<Location "/trac">
     35  SetEnv TRAC_ENV_PARENT_DIR "/path/to/project/parent/dir"
     36</Location>
     37}}}
     38
     39 ''Note that the `SetEnv` directive requires enabled `mod_env` module. It is also possible to set TRAC_ENV in trac.cgi. Just add the following code between "try:" and "from trac.web ...":''
     40
     41{{{#!python
     42    import os
     43    os.environ['TRAC_ENV'] = "/path/to/projectenv"
     44}}}
     45
     46 '' Or for TRAC_ENV_PARENT_DIR: ''
     47
     48{{{#!python
     49    import os
     50    os.environ['TRAC_ENV_PARENT_DIR'] = "/path/to/project/parent/dir"
     51}}}
     52
     53If you are using the [http://httpd.apache.org/docs/suexec.html Apache suEXEC] feature please see [trac:ApacheSuexec].
     54
     55On some systems, you ''may'' need to edit the shebang line in the `trac.cgi` file to point to your real Python installation path. On a Windows system you may need to configure Windows to know how to execute a .cgi file (Explorer -> Tools -> Folder Options -> File Types -> CGI).
     56
     57=== Using WSGI
     58
     59You can run a [http://henry.precheur.org/python/how_to_serve_cgi WSGI handler] [http://pythonweb.org/projects/webmodules/doc/0.5.3/html_multipage/lib/example-webserver-web-wsgi-simple-cgi.html under CGI].  You can [wiki:TracModWSGI#Thetrac.wsgiscript write your own application function], or use the deployed trac.wsgi's application.
     60
     61== Mapping Static Resources
     62
     63See TracInstall#MappingStaticResources.
     64
     65== Adding Authentication
     66
     67See TracInstall#ConfiguringAuthentication.
     68
     69----
     70See also:  TracGuide, TracInstall, [wiki:TracModWSGI], TracFastCgi, TracModPython

  • wiki/pages/TracChangeLog

    r40221 r40226  
     1[[PageOutline(2-3)]]
     2= Change Log
     3This is a rough list of changes between released versions.
     4
     5To see where Trac is going in future releases, see the [trac:roadmap Roadmap].
     6
     7
     8== 1.1.x Releases
     9// 1.1.x releases are development releases leading eventually to Trac 1.2. See them as kind of snapshots of [trac:source:trunk].
     10
     11** No guarantees of feature and API compatibility is made from one 1.1.x release to the next. //
     12
     13=== 1.1.6
     14
     15//(July 17, 2015)//
     16
     17Trac 1.1.6 contains more than a half dozen minor fixes and enhancements.
     18
     19For more information see the [trac:wiki:TracDev/ApiChanges/1.1 API changes] and the detailed
     20release notes for [[trac:wiki:TracDev/ReleaseNotes/1.1#DevelopmentReleases | 1.1.6]] and [[trac:wiki:TracDev/ReleaseNotes/1.0#MaintenanceReleases | 1.0.7]]
     21(as 1.1.6 contains all the fixes done for 1.0.7).
     22
     23[trac:source:/tags/trac-1.1.6 View Tag] | [trac:milestone:1.1.6 View Milestone]
     24
     25
     26=== 1.1.5
     27
     28//(May 18, 2015)//
     29
     30Highlights of the changes:
     31
     32 - Corrected highlighting of unmodified values in //Config// section of the //About Trac// page ([trac:#6551]).
     33 - New helper methods on `DatabaseManager` class for plugins to upgrade the database ([trac:#8172]).
     34 - New `[notification-subscriber]` config section for general configuration of notification subscription defaults and `SubscriberList` macro ([trac:#11875]).
     35 - Removed dependency on `ConfigObj` for TracFineGrainedPermissions ([trac:#11982]).
     36 - `Image` macro supports InterWiki prefixes ([trac:#12025]).
     37
     38See also the [trac:wiki:TracDev/ApiChanges/1.1 API changes] and the detailed
     39release notes for [[trac:wiki:TracDev/ReleaseNotes/1.1#DevelopmentReleases | 1.1.5]], [[trac:wiki:TracDev/ReleaseNotes/1.0#MaintenanceReleases | 1.0.6]] and [[trac:wiki:TracDev/ReleaseNotes/0.12#MaintenanceReleases | 0.12.7]]
     40(as 1.1.5 contains all the fixes done for 1.0.6 and 0.12.7).
     41
     42[trac:source:/tags/trac-1.1.5 View Tag] | [trac:milestone:1.1.5 View Milestone]
     43
     44=== 1.1.4
     45
     46//(March 24, 2015)//
     47
     48Highlights of the changes:
     49
     50 - Performance improvements with MySQL/MariaDB ([trac:#3676]).
     51 - Click on //Permissions// Admin page table row toggles all
     52   checkboxes in the row ([trac:#11417]).
     53 - Configuration sections are written to trac.ini when enabling a
     54   component through TracAdmin or the web administration module
     55   ([trac:#11437]).
     56 - Subscription rules can be reordered by drag and drop ([trac:#11941]).
     57
     58See also the [trac:wiki:TracDev/ApiChanges/1.1 API changes] and the detailed
     59release notes for [[trac:wiki:TracDev/ReleaseNotes/1.1#DevelopmentReleases | 1.1.4]]
     60and [[trac:wiki:TracDev/ReleaseNotes/1.0#MaintenanceReleases | 1.0.4/1.0.5]]
     61(as 1.1.4 contains all the fixes done for 1.0.4 and 1.0.5).
     62
     63[trac:source:/tags/trac-1.1.4 View Tag] | [trac:milestone:1.1.4 View Milestone]
     64
     65=== 1.1.3
     66
     67//(January 13, 2015)//
     68
     69The following list contains highlights of the changes:
     70
     71 - The ticket creation step can be configured in the TracWorkflow and the
     72   workflow controls are present on the !NewTicket page ([trac:#2045]).
     73 - New notification system that can be extended by plugins ([trac:#3517]).
     74 - New preferences panel for notification subscriptions ([trac:#4056]).
     75 - Wiki page version comments can be edited by users with `WIKI_ADMIN` ([trac:#6573]).
     76 - Improved positioning of //Add Comment// section and //author// field
     77   on the ticket form ([trac:#10207]).
     78 - The delete confirmation pages warn if attachments will also be deleted
     79   ([trac:#11542]).
     80 - Removed support for [trac:SilverCity], Enscript and !PhpRenderer syntax
     81   highlighters ([trac:#11795]).
     82 - Combined //Date & Time// and //Language// preference panels as
     83   //Localization// ([trac:#11813]).
     84 - Groups and permissions can be used in the workflow `set_owner` attribute
     85   ([trac:#11839]).
     86
     87See also the [trac:wiki:TracDev/ApiChanges/1.1 API changes] and the detailed release notes for [[trac:wiki:TracDev/ReleaseNotes/1.1#DevelopmentReleases | 1.1.3]] and [[trac:wiki:TracDev/ReleaseNotes/1.0#MaintenanceReleases | 1.0.3]] (as 1.1.3 contains all the fixes done
     88for 1.0.3).
     89
     90[trac:source:/tags/trac-1.1.3 View Tag] | [trac:milestone:1.1.3 View Milestone]
     91
     92=== 1.1.2
     93
     94//(October 23, 2014)//
     95
     96The following list contains highlights of the changes:
     97
     98 - Dropped support for Python 2.5. Trac can no longer be run on Python 2.5 as incompatible changes have been made in the source code ([trac:#11600]).
     99 - The new ticket workflow action `may_set_owner` is similar to `set_owner` but the owner defaults to the existing ticket owner rather than the current user ([trac:#10018]).
     100 - The new option `[ticket]` `optional_fields` specifies ticket select fields that are treated as optional (i.e. an empty value is allowed) ([trac:#10772]).
     101 - Line number and row highlighting annotations can be specified for !WikiProcessor code blocks ([trac:#10834]).
     102 - The //default handler// can be set as a session preference ([trac:#11597]), and the default value for all users can be set from the //Basic Settings// admin page ([trac:#11519]).
     103 - Attachments can't be added to read-only wiki pages ([trac:#11244]).
     104 - Tables on the admin pages have a //Select all// checkbox in the header ([trac:#10994]).
     105 - Submit buttons are disabled if the required items are not selected ([trac:#11056]).
     106 - The Admin //Permissions// page has a //Copy Permissions// form for copying permissions between users and groups ([trac:#11099]).
     107 - The new option `[milestone]` `default_retarget_to` determines the default milestone for retargeting tickets when a milestone is deleted or closed, and can be specified from the //Milestone// admin page ([trac:#10010]).
     108 - The //retarget// select is not shown when closing or deleting a milestone which has no tickets associated with it ([trac:#11366]).
     109 - //Clear default// buttons allow the ticket system default values (e.g. `default_milestone`, `default_version`) to be cleared through the corresponding admin pages ([trac:#10772], [trac:#11300]).
     110 - The `TitleIndex` macro supports relative path prefixes when used on wiki pages ([trac:#11455]).
     111 - [trac:CommitTicketUpdater] will recognize a ticket reference that includes a trailing `#comment:N` or `#comment:description` ([trac:#11622]).
     112 - The //Tickets// column of the milestone table on the //Milestone// admin page contains links to the query page showing all tickets associated with the milestone, grouped by status ([trac:#11661]).
     113 - Authz policy can be used to restrict access to the //Report List// page using the resource id `-1` ([trac:#11697]).
     114
     115See also the [trac:wiki:TracDev/ApiChanges/1.1 API changes] and the detailed release notes for [[trac:wiki:TracDev/ReleaseNotes/1.1#DevelopmentReleases | 1.1.2]], [[trac:wiki:TracDev/ReleaseNotes/1.0#MaintenanceReleases | 1.0.2]] and [[trac:wiki:TracDev/ReleaseNotes/0.12#MaintenanceReleases | 0.12.6]] (as 1.1.2 contains all the fixes done for 1.0.2 and 0.12.6).
     116
     117[trac:source:/tags/trac-1.1.2 View Tag] | [trac:milestone:1.1.2 View Milestone]
     118
     119=== 1.1.1
     120
     121//(February 3, 2013)//
     122
     123Trac 1.1.1 starts the 1.1.x development line leading to 1.2 with some new features and a few not-so-disruptive changes.
     124
     125The following list contains only a few highlights:
     126
     127 - Added support for custom ticket fields of type time ([trac:#1942])
     128 - In new tickets, custom time ticket fields may default to an absolute or relative date / time ([trac:#10853])
     129 - In TracBatchModify, custom time ticket fields can be changed with a date(time)picker popup control ([trac:#10854])
     130 - Optionally display the component of tickets in their timeline entries (`[timeline]` `ticket_show_component` setting) ([trac:#10885])
     131 - Fixed batch modification when no fields are changed ([trac:#10924])
     132 - Dynamic variables can be used in the report title and description ([trac:#10979])
     133 - jQuery upgraded to 1.8.3, jQuery UI upgraded to 1.9.2 and jQuery UI Timepicker upgraded to 1.1.1 ([trac:#10976])
     134 - Dropped support for Python 2.5, either Python 2.6 or Python 2.7 is required //(well, as it happens, 2.5 //still// works, that's a bug ;-) )//
     135
     136See also the [trac:wiki:TracDev/ApiChanges/1.1 API changes] and the detailed release notes for [[trac:wiki:TracDev/ReleaseNotes/1.1#DevelopmentReleases | 1.1.1]], [[trac:wiki:TracDev/ReleaseNotes/1.0#MaintenanceReleases | 1.0.1]] and [[trac:wiki:TracDev/ReleaseNotes/0.12#MaintenanceReleases | 0.12.5]] (as 1.1.1 contains all the fixes done for 1.0.1 and 0.12.5).
     137
     138[trac:source:/tags/trac-1.1.1 View Tag] | [trac:milestone:1.1.1 View Milestone]
     139
     140== 1.0.x Releases ==
     141
     142=== 1.0.7
     143
     144//(July 17, 2015)//
     145
     146Trac 1.0.7 contains more than a dozen minor fixes and enhancements, including the following highlights:
     147 - Custom `svn:keywords` definitions are expanded in Subversion 1.8 and later ([trac:#11364]).
     148 - Fixed MySQL performance regression in query with custom fields ([trac:#12113]).
     149
     150See the detailed release notes for [[trac:wiki:TracDev/ReleaseNotes/1.0#MaintenanceReleases | 1.0.7]].
     151
     152[trac:source:/tags/trac-1.0.7 View Tag] | [trac:milestone:1.0.7 View Milestone]
     153
     154=== 1.0.6
     155
     156//(May 20, 2015)//
     157
     158Trac 1.0.6 provides more than 20 fixes and enhancements. The following are some highlights:
     159 - Hash changeset ids and branch names can be used in revision ranges ([trac:#11050])
     160 - Improved rendering performance using chunked response when `[trac]` `use_chunked_encoding` is `True` ([trac:#11802])
     161 - Improved performance of Git repositories ([trac:#11971]).
     162 - Header to send when `[trac]` `use_xsendfile` is `True` can be specified through the option `[trac]` `xsendfile_header`. X-Sendfile is supported in Nginx by specifying `X-Accel-Redirect` for the header ([trac:#11981]).
     163 - Symbolic link can be used for `conf/trac.ini` in environment directory ([trac:#12000]).
     164 - Hyphen character can be used in !WikiProcessor parameter name ([trac:#12023]).
     165
     166See the detailed release notes for [[trac:wiki:TracDev/ReleaseNotes/1.0#MaintenanceReleases | 1.0.6]] and [[trac:wiki:TracDev/ReleaseNotes/0.12#MaintenanceReleases | 0.12.7]] (as 1.0.6 contains all the changes in 0.12.7).
     167
     168[trac:source:/tags/trac-1.0.6 View Tag] | [trac:milestone:1.0.6 View Milestone]
     169
     170=== 1.0.5
     171
     172//(March 24, 2015)//
     173
     174Trac 1.0.5 provides several fixes. The following are some highlights:
     175
     176 - Images are not rendered in the timeline ([trac:#10751]).
     177 - Git tags are shown in the browser view ([trac:#11964]).
     178 - Added support for `journal_mode` and `synchronous` pragmas in `sqlite:` database connection string ([trac:#11967]).
     179
     180See the detailed release notes for [[trac:wiki:TracDev/ReleaseNotes/1.0#MaintenanceReleases | 1.0.5]].
     181
     182[trac:source:/tags/trac-1.0.5 View Tag] | [trac:milestone:1.0.5 View Milestone]
     183
     184=== 1.0.4
     185
     186//(February 8, 2015)//
     187
     188Trac 1.0.4 contains a few fixes, including a fix for a regression in 1.0.3.
     189
     190 - Workflow action labels were not displayed unless name attribute
     191   was explicitly defined ([trac:#11930]).
     192
     193See the detailed release notes for [[trac:wiki:TracDev/ReleaseNotes/1.0#MaintenanceReleases | 1.0.4]].
     194
     195[trac:source:/tags/trac-1.0.4 View Tag] | [trac:milestone:1.0.4 View Milestone]
     196
     197=== 1.0.3
     198
     199//(January 13, 2015)//
     200
     201Trac 1.0.3 is a maintenance release containing numerous fixes and minor
     202enhancements. The following are a few of the highlights:
     203
     204The following list contains only a few highlights:
     205
     206 - Notification is sent when adding an attachment to a ticket ([trac:#2259]).
     207 - Stylesheets and scripts are loaded during autopreview, resulting in proper
     208   syntax highlighting when code WikiProcessors are added ([trac:#10470]) and display
     209   of Workflow graphs without explicit autopreview ([trac:#10674]).
     210 - Merge changesets are shown as differences against first parent, resulting
     211   in less noisy changesets ([trac:#10740]).
     212 - Pygments 2.0 is supported ([trac:#11796]).
     213 - Fixed error when completing the `initenv` TracAdmin command ([trac:#11797]).
     214 - Performance improvement on systems with many thousands of authenticated
     215   users due to caching of Environment.get_known_users ([trac:#11868]).
     216 - Distribution metadata of wheel package is supported and displayed on the
     217   About page ([trac:#11877]).
     218 - … and more than 3 dozen total fixes!
     219
     220See the detailed release notes for [[trac:wiki:TracDev/ReleaseNotes/1.0#MaintenanceReleases | 1.0.3]].
     221
     222[trac:source:/tags/trac-1.0.3 View Tag] | [trac:milestone:1.0.3 View Milestone]
     223
     224
     225=== 1.0.2
     226
     227//(October 23, 2014)//
     228
     229Trac 1.0.2 contains a number of bug fixes and minor enhancements, as well as a major update for many translations.
     230
     231The following list contains only a few highlights:
     232
     233 - Subversion keywords are expanded and EOL substitutions made when viewing a file in the repository browser and when downloading a file ([trac:#717]).
     234 - Notification email is sent to the old owner when a ticket is reassigned ([trac:#2311]).
     235 - Ticket change history is updated when renaming and deleting a milestone, and when retargeting tickets to another milestone ([trac:#4582], [trac:#5658]).
     236 - Numerous fixes for the Authz permissions policy in the browser/repository ([trac:#10961], [trac:#11646]), wiki ([trac:#8976], [trac:#11067]), admin ([trac:#11069]) and report ([trac:#11176]) realms.
     237 - Multiple forms submits are disallowed ([trac:#10138]).
     238 - `ConfigurationError` is raised if any of the `permission_policies` can't be loaded, preventing possible information leakage due to internal and installation errors ([trac:#10285]).
     239 - Wiki toolbars can be disabled through a configuration setting ([trac:#10837])
     240 - The number of entries in a table is shown next to heading on applicable admin pages ([trac:#11027]).
     241 - //Cancel// buttons are consistently located on all pages ([trac:#11076]).
     242 - Focus is placed on a text element when an edit page is loaded ([trac:#11084]).
     243 - The //Edit conflict// and //Merge// warning messages are always visible in side-by-side edit mode ([trac:#11102]).
     244 - Improvements to the layout of the Report ([trac:#11106], [trac:#11664]) and Ticket pages ([trac:#11471]).
     245 - Genshi 0.7 compatibility ([trac:#11218]).
     246 - Numerous minor fixes for Git repository support.
     247 - … and more than a hundred more fixes!
     248
     249See the detailed release notes for [[trac:wiki:TracDev/ReleaseNotes/1.0#MaintenanceReleases | 1.0.2]] and [[trac:wiki:TracDev/ReleaseNotes/0.12#MaintenanceReleases | 0.12.6]] (as 1.0.2 contains all the fixes done for 0.12.6).
     250
     251[trac:source:/tags/trac-1.0.2 View Tag] | [trac:milestone:1.0.2 View Milestone]
     252
     253
     254=== 1.0.1
     255
     256//(February 1, 2013)//
     257
     258Trac 1.0.1 contains a number of bug fixes and minor enhancements, as well as a major update for many translations.
     259
     260The following list contains only a few highlights:
     261
     262 - Fix zip source download for large directories in Subversion repositories ([trac:#10840])
     263 - Performance improvement for the Roadmap, by caching milestone properties ([trac:#10879])
     264 - Added a ''select all'' checkbox to table of components for each plugin on the Plugins admin panel ([trac:#9609])
     265 - Restore the ''Modify'' link at the top of the ticket page, as it was in Trac 0.12 ([trac:#10856])
     266 - `ListOption` keeps values other than empty string and None in raw list as default ([trac:#10541])
     267 - Prevent possibility of multiple identical info or warning messages being presented to the user ([trac:#10987])
     268 - The !BatchModify select-all checkboxes are toggled with tri-state behavior when the ticket checkboxes are toggled ([trac:#10992])
     269 - Update the ticket changetime to the current time when deleting a ticket comment ([trac:#10486])
     270
     271See the detailed release notes for [[trac:wiki:TracDev/ReleaseNotes/1.0#MaintenanceReleases | 1.0.1]] and [[trac:wiki:TracDev/ReleaseNotes/0.12#MaintenanceReleases | 0.12.5]] (as 1.0.1 contains all the fixes done for 0.12.5).
     272
     273[trac:source:/tags/trac-1.0.1 View Tag] | [trac:milestone:1.0.1 View Milestone]
     274
     275
     276=== '''1.0 'Cell' '''
     277
     278//(September 7, 2012)//
     279
     280Trac 1.0 is a major release adding refreshed user interface and improved DVCS repository support as the most visible changes.
     281
     282The following list contains only a few highlights:
     283 - The default theme looks more modern, especially on recent browsers (no effort has been made to make it look better on older browsers like IE6 or 7)
     284 - The [TH:GitPlugin] has been donated by Herbert Valerio Riedel to the Trac project (many thanks!) and is now maintained here as an optional component
     285 - As a consequence, the Subversion support has been moved below `tracopt.versioncontrol` as well
     286 - The Git and Mercurial log view feature a visualization of the branching structure
     287 - Usability improvements for the tickets, with a better support for conflict detection and resolution
     288 - Integration of the [TH:BatchModifyPlugin], contributed by Brian Meeker (many thanks!) and is now maintained there as a default component
     289 - jQuery/UI integration, featuring a date picker for date fields
     290 - Improved integration with Pygments syntax highlighting
     291 - ... and numerous smaller features added and bugs fixed since 0.12!
     292
     293See the full list in [trac:wiki:TracDev/ReleaseNotes/1.0 1.0].
     294
     295[[trac:source:/tags/trac-1.0 View Tag]] | [[trac:milestone:1.0 View Milestone]]
     296
     297== 0.12.x Releases
     298
     299=== 0.12.7
     300
     301//(May 20, 2015)//
     302
     303Trac 0.12.7 fixes a minor security issue, as well as a half dozen other minor issues:
     304 - InterWiki filters links through `[wiki] safe_schemes` option if `[wiki] render_unsafe_content` is disabled ([trac:#12053]).
     305
     306See the detailed release notes for [[trac:wiki:TracDev/ReleaseNotes/0.12#MaintenanceReleases | 0.12.7]].
     307
     308[trac:source:/tags/trac-0.12.7 View Tag] | [trac:milestone:0.12.7 View Milestone]
     309
     310=== 0.12.6
     311
     312//(October 23, 2014)//
     313
     314Trac 0.12.6 contains fixes for a few issues:
     315 - Subversion blame would fail for a path with URL-encoded characters ([trac:#10386]), a lower-case drive letter on Windows ([trac:#10514]), or a non-ascii filename with Subversion 1.7 ([trac:#11167]).
     316 - Improved performance rendering `svn:mergeinfo` properties in browser view ([trac:#8459]) and changeset view ([trac:#11219]).
     317 - Query with many custom fields would fail ([trac:#11140]).
     318 - Zip archive had a timestamp with no timezone information ([trac:#11162]).
     319 - Failure or incorrect ranges rendering log TracLinks ([trac:#11308], [trac:#11346]).
     320 - Textareas in ticket view did not wrap correctly in IE 11 ([trac:#11376]).
     321 - Emails were not being obfuscated in owner field on CSV export from ticket and query pages ([trac:#11594]).
     322 - Locale data was not being included in egg in Distribute 0.6.29 and later ([trac:#11640]).
     323 - Deleting a milestone would not delete its attachments ([trac:#11672]).
     324 - Added support for Babel 1.0 and later ([trac:#11258], [trac:#11345]).
     325 - Added support for `ConfigObj` 5.0 and later ([trac:#11498]).
     326 - … and dozens more fixes!
     327
     328See the detailed release notes for [[trac:wiki:TracDev/ReleaseNotes/0.12#MaintenanceReleases | 0.12.6]].
     329
     330[trac:source:/tags/trac-0.12.6 View Tag] | [trac:milestone:0.12.6 View Milestone]
     331
     332=== 0.12.5
     333
     334//(January 15, 2013)//
     335
     336Trac 0.12.5 contains fixes for a few issues:
     337 - upload of .mht files ([Wikipedia:MHTML] web page archive files) now works ([trac:#9880])
     338 - more robust parsing of attachment URLs ([trac:#10280]) and uploaded file names ([trac:#10850])
     339 - lots of improvement to the date formatting code, which is now much more robust when timezone and daylight saving time computations are involved ([trac:#10768], [trac:#10863], [trac:#10864], [trac:#10912], [trac:#10920])
     340 - no longer generate invalid JSON encoded data with Python 2.4 and 2.5 ([trac:#10877])
     341 - ... and fix a couple more minor defects ([trac:#10967], [trac:#10892], [trac:#10923], [trac:#10858], [trac:#10835])
     342
     343[trac:source:/tags/trac-0.12.5 View Tag] | [trac:milestone:0.12.5 View Milestone]
     344
     345=== 0.12.4
     346
     347//(September 7, 2012)//
     348
     349Trac 0.12.4 contains only a handful of minor fixes.
     350
     351[trac:source:/tags/trac-0.12.4 View Tag] | [trac:milestone:0.12.4 View Milestone]
     352
     353=== 0.12.3 ===
     354
     355//(February 6, 2012)//
     356
     357Trac 0.12.3 contains a few minor fixes and a few minor features.
     358 - compatibility with Subversion 1.7 ([trac:#10414])
     359 - easier troubleshooting of common startup errors ([trac:#10024])
     360 - jQuery upgraded to 1.4.4 ([trac:#10001])
     361 - improve fine-grained permission handling in the source browser ([trac:#9976], [trac:#10208], [trac:#10110])
     362 - added compatibility with MySQL 5.5.3 utf8mb4 databases ([trac:#9766])
     363 - ... and dozens more fixes!
     364
     365[trac:source:/tags/trac-0.12.3 View Tag] | [trac:milestone:0.12.3 View Milestone]
     366
     367=== 0.12.2
     368
     369//(January 31, 2011)//
     370
     371Trac 0.12.2 contains a few minor fixes and a few minor features.
     372
     373This list contains only a few highlights:
     374 - install: improved robustness of Trac installation if Babel is
     375   installed after the fact ([trac:#9439], [trac:#9595], [trac:#9961])
     376 - notifications: support for Asian character width ([trac:#4717])
     377 - roadmap: fix display of progress bar in some corner cases ([trac:#9718])
     378   and respect the overall_completion milestone group setting ([trac:#9721])
     379 - reports: reports and queries look much better, as the columns now
     380   keep the same width across groups; the absence of word wrapping in
     381   reports has been fixed ([trac:#9825])
     382 - web admin: improved layout ([trac:#8866], [trac:#9963])
     383 - web: it's now possible to log in different Trac instances sharing
     384   the same URL prefix (e.g. /project and /project-test) ([trac:#9951])
     385
     386[trac:source:/tags/trac-0.12.2 View Tag] | [trac:milestone:0.12.2 View Milestone]
     387
     388=== 0.12.1
     389
     390//(October 9, 2010)//
     391
     392Trac 0.12.1 contains a few important performance improvements, some minor fixes and a few minor features.
     393
     394This list contains only a few highlights:
     395 - db: improve concurrency behavior ([trac:#9111])
     396 - fcgi: add an environment variable `TRAC_USE_FLUP` to control the usage of flup vs. bundled _fcgi.py (defaults to 0, i.e. use bundled as before)
     397 - svn authz: improve compatibility with svn 1.5 format ([trac:#8289])
     398 - milestone: allow to set the time for the due date ([trac:#6369], [trac:#9582])
     399 - ticket: fixes for the CC: property ([trac:#8597], [trac:#9522])
     400 - notification: improved the formatting of ticket fields in notification e-mails ([trac:#9484], [trac:#9494])
     401 - i18n: added a configuration option to set the default language ([trac:#8117])
     402 - several fixes for upgrade ([trac:#9400], [trac:#9416], [trac:#9483], [trac:#9556])
     403
     404[trac:source:/tags/trac-0.12.1 View Tag] | [trac:milestone:0.12.1 View Milestone]
     405
     406=== ''' 0.12 'Babel' '''
     407
     408//(June 13, 2010)//
     409
     410Trac 0.12 is a major release introducing i18n and multiple repository support as the most visible changes.
     411
     412The following list contains only a few highlights:
     413 - The user interface is translated in a dozen of languages, provided the [Babel:] package is installed
     414 - Multiple repositories can be associated to a single Trac environment; the repositories can be of heterogeneous types (svn, hg, git, darcs...)
     415 - Usability improvements for the Wiki, with a nice side-by-side edit mode with automatic preview
     416 - Richer Wiki syntax, with much improved support for tables, partial [trac:WikiCreole] compatibility and numerous smaller improvements
     417 - Usability improvements for the Ticket module, with automatic preview of comments while you type and possibility to edit or remove them later
     418 - Improved Custom Queries (time fields, multiple disjoint conditions, a.k.a. OR queries)
     419 - Timeline filtering by user
     420 - ... and numerous smaller features added and bugs fixed since 0.11!
     421
     422[trac:source:/tags/trac-0.12 View Tag] | [trac:milestone:0.12 View Milestone]
     423
     424== Older Releases
     425
     426For releases prior to 0.12, see [trac:TracChangeLog@95].

  • wiki/pages/TracChangeset

    r40221 r40226  
     1= Trac Changeset Module =
     2[[TracGuideToc]]
     3
     4Trac has a built-in functionality for visualizing “diffs”, or changes to files.
     5
     6There are different kinds of ''change sets''.  Some correspond to revisions made in the repositories, others aggregate changes made in several revisions. Ultimately, any kind of difference can be shown.
     7
     8The changeset view consists of two parts, the ''header'' and the ''diff views''.
     9
     10== Changeset Header ==
     11
     12The header shows an overview of the whole changeset.
     13Here you will find information such as:
     14
     15 * Timestamp — When the changeset was commited
     16 * Author — Who commited the changeset
     17 * Message — A brief description from the author (the commit log message)
     18 * Location — Parent directory of all files affected by this changeset
     19 * Files — A list of files affected by this changeset
     20
     21If more than one revision is involved in the set of changes being displayed, the ''Timestamp'', ''Author'' and ''Message'' fields will not be shown.
     22
     23A colored rectangle indicates how the file is affected by the changeset:
     24 
     25 [[span(style=background:#bfb;border:1px solid #999;font-size:80%;margin-right:.5em,''  '')]] Green: Added \\
     26 [[span(style=background:#f88;border:1px solid #999;font-size:80%;margin-right:.5em,''  '')]] Red: Removed \\
     27 [[span(style=background:#fd8;border:1px solid #999;font-size:80%;margin-right:.5em,''  '')]] Yellow: Modified \\
     28 [[span(style=background:#88f;border:1px solid #999;font-size:80%;margin-right:.5em,''  '')]] Blue: Copied \\
     29 [[span(style=background:#ccc;border:1px solid #999;font-size:80%;margin-right:.5em,''  '')]] Gray: Moved \\
     30The color legend is located below the header as a reminder.
     31
     32== Diff Views ==
     33
     34Below the header is the main part of the changeset, the diff view. Each file is shown in a separate section, each of which contains only the regions of the file that are affected by the changeset. There are two different styles to display the diffs: ''inline'' or ''side-by-side''. You can switch between the styles using the preferences form:
     35
     36 * The ''inline'' style shows the changed regions of a file underneath each other. A region removed from the file will be colored red, an added region will be colored green. If a region was modified, the old version is displayed above the new version. Line numbers indicate the exact position of the change in both the old and the new version of the file.
     37 * The ''side-by-side'' style shows the old version on the left and the new version on the right and this will typically require more screen width than the inline style. Added and removed regions will be colored in the same way as with the inline style (green and red), and modified regions will have a yellow background.
     38
     39In addition, various advanced options are available in the preferences form for adjusting the display of the diffs:
     40 * You can set how many lines are displayed before and after every change; if the value ''all'' is used, then the full file will be shown.
     41 * You can toggle whether blank lines, case changes and white space changes are ignored, thereby letting you find the functional changes more quickly.
     42
     43== The Different Ways to Get a Diff ==
     44
     45=== Examining a Changeset ===
     46
     47When viewing a repository check-in, such as when following a changeset [wiki:TracLinks link] or a changeset event in the [wiki:TracTimeline timeline], Trac will display the exact changes made by the check-in.
     48
     49There will be also navigation links to the ''Previous Changeset'' to and ''Next Changeset''.
     50
     51=== Examining Differences Between Revisions ===
     52
     53Often you want to look at changes made on a file or on a directory spanning multiple revisions. The easiest way to get there is from the TracRevisionLog, where you can select the ''old'' and the ''new'' revisions of the file or directory, and then click the ''View changes'' button.
     54
     55=== Examining Differences Between Branches ===
     56
     57One of the core features of version control systems is the possibility to work simultaneously on different ''Lines of Developments'', commonly called “branches”. Trac enables you to examine the exact differences between such branches.
     58
     59Using the '''View changes ...''' button in the TracBrowser allows you to enter ''From:'' and ''To:'' path/revision pairs. The resulting set of differences consist of the changes that should be applied to the ''From:'' content to get to the ''To:'' content.
     60
     61For convenience, it is possible to invert the roles of the ''old'' and the ''new'' path/revision pairs by clicking the ''Reverse Diff'' link on the changeset page.
     62
     63=== Checking the Last Change ===
     64
     65Another way to examine changes is to use the ''Last Change'' link provided by the TracBrowser.
     66
     67This link will take you to the last change that was made on that path. From there, you can use the ''Previous Change'' and ''Next Change'' links to traverse the change history of the file or directory.
     68
     69----
     70See also: TracGuide, TracBrowser

  • wiki/pages/TracEnvironment

    r40221 r40226  
     1= The Trac Environment
     2
     3[[TracGuideToc]]
     4[[PageOutline(2-5)]]
     5
     6Trac uses a directory structure and a database for storing project data. The directory is referred to as the environment.
     7
     8== Creating an Environment
     9
     10A new Trac environment is created using [TracAdmin#initenv trac-admin's initenv]:
     11{{{#!sh
     12$ trac-admin /path/to/myproject initenv
     13}}}
     14
     15`trac-admin` will ask you for the name of the project and the database connection string, see below.
     16
     17=== Useful Tips
     18
     19 - Place your environment's directory on a filesystem which supports sub-second timestamps, as Trac monitors the timestamp of its configuration files and changes happening on a filesystem with too coarse-grained timestamp resolution may go undetected in Trac < 1.0.2. This is also true for the location of authentication files when using TracStandalone.
     20
     21 - The user under which the web server runs will require file system write permission to the environment directory and all the files inside. Please remember to set the appropriate permissions. The same applies to the source code repository, although the user under which Trac runs will only require write access to a Subversion repository created with the BDB file system; for other repository types, check the corresponding plugin's documentation.
     22 
     23 - `initenv`, when using an svn repository, does not imply that trac-admin will perform `svnadmin create` for the specified repository path. You need to perform the `svnadmin create` prior to `trac-admin initenv` if you're creating a new svn repository altogether with a new Trac environment; otherwise you will see a message "Warning: couldn't index the repository" when initializing the environment.
     24
     25 - Non-ascii environment paths are not supported.
     26 
     27 - Also, it seems that project names with spaces can be problematic for authentication, see [trac:#7163].
     28
     29 - TracPlugins located in a [TracIni#inherit-section shared plugins folder] that is defined in an [TracIni#GlobalConfiguration inherited configuration] are currently not loaded during creation, and hence, if they need to create extra tables for example, you'll need to [TracUpgrade#UpgradetheTracEnvironment upgrade the environment] before being able to use it.
     30
     31{{{#!div style="border: 1pt dotted; margin: 1em"
     32**Caveat:** don't confuse the //Trac environment directory// with the //source code repository directory//.
     33
     34This is a common beginners' mistake.
     35It happens that the structure for a Trac environment is loosely modeled after the Subversion repository directory structure, but those are two disjoint entities and they are not and //must not// be located at the same place.
     36}}}
     37
     38== Database Connection Strings
     39
     40Trac supports [http://sqlite.org/ SQLite], [http://www.postgresql.org/ PostgreSQL] and [http://mysql.com/ MySQL] database backends. The default is SQLite, which is probably sufficient for most projects. The database file is then stored in the environment directory, and can easily be [wiki:TracBackup backed up] together with the rest of the environment.
     41
     42Note that if the username or password of the connection string (if applicable) contains the `:`, `/` or `@` characters, they need to be URL encoded.
     43
     44=== SQLite Connection String
     45
     46The connection string for an SQLite database is:
     47{{{
     48sqlite:db/trac.db
     49}}}
     50where `db/trac.db` is the path to the database file within the Trac environment.
     51
     52=== PostgreSQL Connection String
     53
     54If you want to use PostgreSQL instead, you'll have to use a different connection string. For example, to connect to a PostgreSQL database on the same machine called `trac` for user `johndoe` with the password `letmein` use:
     55{{{
     56postgres://johndoe:letmein@localhost/trac
     57}}}
     58
     59If PostgreSQL is running on a non-standard port, for example 9342, use:
     60{{{
     61postgres://johndoe:letmein@localhost:9342/trac
     62}}}
     63
     64On UNIX, you might want to select a UNIX socket for the transport, either the default socket as defined by the PGHOST environment variable:
     65{{{
     66postgres://user:password@/database
     67}}}
     68
     69or a specific one:
     70{{{
     71postgres://user:password@/database?host=/path/to/socket/dir
     72}}}
     73
     74Note that with PostgreSQL you will have to create the database before running `trac-admin initenv`.
     75
     76See the [http://www.postgresql.org/docs/ PostgreSQL documentation] for detailed instructions on how to administer [http://postgresql.org PostgreSQL].
     77Generally, the following is sufficient to create a database user named `tracuser` and a database named `trac`:
     78{{{#!sh
     79$ createuser -U postgres -E -P tracuser
     80$ createdb -U postgres -O tracuser -E UTF8 trac
     81}}}
     82
     83When running `createuser` you will be prompted for the password for the user 'tracuser'. This new user will not be a superuser, will not be allowed to create other databases and will not be allowed to create other roles. These privileges are not needed to run a Trac instance. If no password is desired for the user, simply remove the `-P` and `-E` options from the `createuser` command. Also note that the database should be created as UTF8. LATIN1 encoding causes errors, because of Trac's use of unicode. SQL_ASCII also seems to work.
     84
     85Under some default configurations (Debian) one will have run the `createuser` and `createdb` scripts as the `postgres` user:
     86{{{#!sh
     87$ sudo su - postgres -c 'createuser -U postgres -S -D -R -E -P tracuser'
     88$ sudo su - postgres -c 'createdb -U postgres -O tracuser -E UTF8 trac'
     89}}}
     90
     91Trac uses the `public` schema by default, but you can specify a different schema in the connection string:
     92{{{
     93postgres://user:pass@server/database?schema=yourschemaname
     94}}}
     95
     96=== MySQL Connection String
     97
     98The format of the MySQL connection string is similar to those for PostgreSQL, with the `postgres` scheme being replaced by `mysql`. For example, to connect to a MySQL database on the same machine called `trac` for user `johndoe` with password `letmein`:
     99{{{
     100mysql://johndoe:letmein@localhost:3306/trac
     101}}}
     102
     103== Source Code Repository
     104
     105A single environment can be connected to more than one repository. However, by default Trac is not connected to any source code repository, and the ''Browse Source'' toolbar item will not be displayed.
     106
     107There are many different ways to connect repositories to an environment, see TracRepositoryAdmin. A single repository can be specified when the environment is created by passing the optional arguments `repository_type` and `repository_dir` to the `initenv` command.
     108
     109== Directory Structure
     110
     111An environment directory will usually consist of the following files and directories:
     112
     113 * `README` - Brief description of the environment.
     114 * `VERSION` - Environment version identifier.
     115 * `files`
     116  * `attachments` - Attachments to wiki pages and tickets.
     117 * `conf`
     118  * `trac.ini` - Main configuration file. See TracIni.
     119 * `db`
     120  * `trac.db` - The SQLite database, if you are using SQLite.
     121 * `htdocs` - Directory containing web resources, which can be referenced in Genshi templates using `/chrome/site/...` URLs.
     122 * `log` - Default directory for log files, if `file` logging is enabled and a relative path is given.
     123 * `plugins` - Environment-specific [wiki:TracPlugins plugins].
     124 * `templates` - Custom Genshi environment-specific templates.
     125  * `site.html` - Method to customize header, footer, and style, described in TracInterfaceCustomization#SiteAppearance.
     126
     127----
     128See also: TracAdmin, TracBackup, TracIni, TracGuide

  • wiki/pages/TracFastCgi

    r40221 r40226  
     1= Trac with FastCGI
     2
     3[[TracGuideToc]]
     4[[PageOutline(2-5, Contents, floated)]]
     5
     6[http://www.fastcgi.com/ FastCGI] interface allows Trac to remain resident much like with [wiki:TracModPython mod_python] or [wiki:TracModWSGI mod_wsgi]. It is faster than external CGI interfaces which must start a new process for each request.  Additionally, it is supported by much wider variety of web servers.
     7
     8Note that unlike mod_python, FastCGI supports [http://httpd.apache.org/docs/suexec.html Apache SuEXEC], ie run with different permissions than the web server runs with. `mod_wsgi` supports the `WSGIDaemonProcess` with user / group parameters to achieve the same effect.
     9
     10'''Note for Windows:''' Trac's FastCGI does not run under Windows, as Windows does not implement `Socket.fromfd`, which is used by `_fcgi.py`. If you want to connect to IIS, you may want to try [trac:TracOnWindowsIisAjp AJP]/[trac:TracOnWindowsIisAjp ISAPI].
     11
     12== Simple Apache configuration
     13
     14There are two FastCGI modules commonly available for Apache: `mod_fastcgi` and
     15`mod_fcgid` (preferred). The latter is more up-to-date.
     16
     17The following sections focus on the FCGI specific setup, see also [wiki:TracModWSGI#ConfiguringAuthentication] for configuring the authentication in Apache.
     18
     19Regardless of which cgi module is used, be sure the web server has executable permissions on the cgi-bin folder. While FastCGI will throw specific permissions errors, mod_fcgid will throw an ambiguous error if this has not been done. Connection reset by peer: mod_fcgid: error reading data from FastCGI server.
     20
     21=== Set up with `mod_fastcgi`
     22
     23`mod_fastcgi` uses `FastCgiIpcDir` and `FastCgiConfig` directives that should be added to an appropriate Apache configuration file:
     24{{{
     25# Enable fastcgi for .fcgi files
     26# (If you're using a distro package for mod_fcgi, something like
     27# this is probably already present)
     28<IfModule mod_fastcgi.c>
     29   AddHandler fastcgi-script .fcgi
     30   FastCgiIpcDir /var/lib/apache2/fastcgi
     31</IfModule>
     32LoadModule fastcgi_module /usr/lib/apache2/modules/mod_fastcgi.so
     33}}}
     34Setting `FastCgiIpcDir` is optional if the default is suitable. Note that the `LoadModule` line must be after the `IfModule` group.
     35
     36Configure `ScriptAlias` or similar options as described in TracCgi, but
     37calling `trac.fcgi` instead of `trac.cgi`.
     38
     39Add the following to the Apache configuration file (below the `FastCgiIpcDir` line) if you intend to set up the `TRAC_ENV` as an overall default:
     40{{{
     41FastCgiConfig -initial-env TRAC_ENV=/path/to/env/trac
     42}}}
     43
     44Alternatively, you can serve multiple Trac projects in a directory by adding this:
     45{{{
     46FastCgiConfig -initial-env TRAC_ENV_PARENT_DIR=/parent/dir/of/projects
     47}}}
     48
     49=== Set up with `mod_fcgid`
     50
     51Configure `ScriptAlias` (see TracCgi for details), but call `trac.fcgi` instead of `trac.cgi`:
     52{{{
     53ScriptAlias /trac /path/to/www/trac/cgi-bin/trac.fcgi/
     54}}}
     55Note the slash at the end.
     56
     57To set up Trac environment for `mod_fcgid` it is necessary to use `DefaultInitEnv` directive. It cannot be used in `Directory` or `Location` context, so if you need to support multiple projects, try alternative environment setup below.
     58
     59{{{
     60DefaultInitEnv TRAC_ENV /path/to/env/trac/
     61}}}
     62
     63=== alternative environment setup
     64
     65A better method to specify path to the Trac environment is to embed the path into `trac.fcgi` script itself. That doesn't require configuration of the server environment variables, works for both [trac:FastCgi] modules as well as for [http://www.lighttpd.net/ lighttpd] and CGI:
     66{{{
     67import os
     68os.environ['TRAC_ENV'] = "/path/to/projectenv"
     69}}}
     70or:
     71{{{
     72import os
     73os.environ['TRAC_ENV_PARENT_DIR'] = "/path/to/project/parent/dir"
     74}}}
     75
     76With this method different projects can be supported by using different `.fcgi` scripts with different `ScriptAliases`.
     77
     78See [https://coderanger.net/~coderanger/httpd/fcgi_example.conf this fcgid example config] which uses a !ScriptAlias directive with trac.fcgi with a trailing / like this:
     79{{{
     80ScriptAlias / /srv/tracsite/cgi-bin/trac.fcgi/
     81}}}
     82
     83== Simple Cherokee Configuration
     84
     85The configuration on Cherokee's side is quite simple. You will only need to know that you can spawn Trac as an SCGI process.
     86You can either start it manually, or better yet, automatically by letting Cherokee spawn the server whenever it is down.
     87First set up an information source in cherokee-admin with a local interpreter:
     88
     89{{{
     90Host:
     91localhost:4433
     92
     93Interpreter:
     94/usr/bin/tracd —single-env —daemonize —protocol=scgi —hostname=localhost —port=4433 /path/to/project/
     95}}}
     96
     97If the port was not reachable, the interpreter command would be launched. Note that, in the definition of the information source, you will have to manually launch the spawner if you use a ''Remote host'' as ''Information source'' instead of a ''Local interpreter''.
     98
     99After doing this, we will just have to create a new rule managed by the SCGI handler to access Trac. It can be created in a new virtual server, trac.example.net for instance, and will only need two rules. The '''default''' one will use the SCGI handler associated to the previously created information source.
     100The second rule will be there to serve the few static files needed to correctly display the Trac interface. Create it as ''Directory rule'' for ''/common'' and just set it to the ''Static files'' handler and with a ''Document root'' that points to the appropriate files: ''$TRAC_LOCAL/htdocs/'' (where $TRAC_LOCAL is a directory defined by the user or the system administrator to place local trac resources).
     101
     102Note:\\
     103If the tracd process fails to start up, and cherokee displays a 503 error page, you might be missing the [http://trac.saddi.com/flup python-flup] package.\\
     104Python-flup is a dependency which provides trac with SCGI capability. You can install it on debian based systems with:
     105{{{
     106sudo apt-get install python-flup
     107}}}
     108
     109== Simple Lighttpd Configuration
     110
     111The FastCGI front-end was developed primarily for use with alternative webservers, such as [http://www.lighttpd.net/ Lighttpd].
     112
     113Lighttpd is a secure, fast, compliant and very flexible web-server that has been optimized for high-performance environments. It has a very low memory footprint compared to other web servers and takes care of CPU load.
     114
     115For using `trac.fcgi`(prior to 0.11) / fcgi_frontend.py (0.11) with Lighttpd add the following to your lighttpd.conf:
     116{{{
     117#var.fcgi_binary="/usr/bin/python /path/to/fcgi_frontend.py" # 0.11 if installed with easy_setup, it is inside the egg directory
     118var.fcgi_binary="/path/to/cgi-bin/trac.fcgi" # 0.10 name of prior fcgi executable
     119fastcgi.server = ("/trac" =>
     120   
     121                   ("trac" =>
     122                     ("socket" => "/tmp/trac-fastcgi.sock",
     123                      "bin-path" => fcgi_binary,
     124                      "check-local" => "disable",
     125                      "bin-environment" =>
     126                        ("TRAC_ENV" => "/path/to/projenv")
     127                     )
     128                   )
     129                 )
     130}}}
     131
     132Note that you will need to add a new entry to `fastcgi.server` for each separate Trac instance that you wish to run. Alternatively, you may use the `TRAC_ENV_PARENT_DIR` variable instead of `TRAC_ENV` as described above, and you may set one of the two in `trac.fcgi` instead of in `lighttpd.conf` using `bin-environment`, as in the section above on Apache configuration.
     133
     134Note that Lighttpd has a bug related to 'SCRIPT_NAME' and 'PATH_INFO' when the uri of fastcgi.server is '/' instead of '/trac' in this example (see [trac:#2418]). This is fixed in Lighttpd 1.5, and under Lighttpd 1.4.23 or later the workaround is to add `"fix-root-scriptname" => "enable"` as a parameter of fastcgi.server.
     135
     136For using two projects with lighttpd add the following to your `lighttpd.conf`:
     137{{{
     138fastcgi.server = ("/first" =>
     139                   ("first" =>
     140                    ("socket" => "/tmp/trac-fastcgi-first.sock",
     141                     "bin-path" => fcgi_binary,
     142                     "check-local" => "disable",
     143                     "bin-environment" =>
     144                       ("TRAC_ENV" => "/path/to/projenv-first")
     145                    )
     146                  ),
     147                  "/second" =>
     148                    ("second" =>
     149                    ("socket" => "/tmp/trac-fastcgi-second.sock",
     150                     "bin-path" => fcgi_binary,
     151                     "check-local" => "disable",
     152                     "bin-environment" =>
     153                       ("TRAC_ENV" => "/path/to/projenv-second")
     154                    )
     155                  )
     156                )
     157}}}
     158
     159Note that field values are different. If you prefer setting the environment variables in the `.fcgi` scripts, then copy/rename `trac.fcgi`, eg to `first.fcgi` and `second.fcgi`, and reference them in the above settings.
     160Note that the above will result in different processes in any event, even if both are running from the same `trac.fcgi` script.
     161
     162{{{
     163#!div class=important
     164'''Note''' It's very important the order on which server.modules are loaded, if mod_auth is not loaded '''BEFORE''' mod_fastcgi, then the server will fail to authenticate the user.
     165}}}
     166
     167For authentication you should enable mod_auth in lighttpd.conf 'server.modules', select auth.backend and auth rules:
     168{{{
     169server.modules              = (
     170...
     171  "mod_auth",
     172...
     173)
     174
     175auth.backend               = "htpasswd"
     176
     177# Separated password files for each project
     178# See "Conditional Configuration" in
     179# http://trac.lighttpd.net/trac/file/branches/lighttpd-merge-1.4.x/doc/configuration.txt
     180
     181$HTTP["url"] =~ "^/first/" {
     182  auth.backend.htpasswd.userfile = "/path/to/projenv-first/htpasswd.htaccess"
     183}
     184$HTTP["url"] =~ "^/second/" {
     185  auth.backend.htpasswd.userfile = "/path/to/projenv-second/htpasswd.htaccess"
     186}
     187
     188# Enable auth on trac URLs, see
     189# http://trac.lighttpd.net/trac/file/branches/lighttpd-merge-1.4.x/doc/authentication.txt
     190
     191auth.require = ("/first/login" =>
     192                ("method"  => "basic",
     193                 "realm"   => "First project",
     194                 "require" => "valid-user"
     195                ),
     196                "/second/login" =>
     197                ("method"  => "basic",
     198                 "realm"   => "Second project",
     199                 "require" => "valid-user"
     200                )
     201               )
     202
     203}}}
     204Note that Lighttpd (v1.4.3) stops if the password file doesn't exist.
     205
     206Note that Lighttpd doesn't support 'valid-user' in versions prior to 1.3.16.
     207
     208Conditional configuration is also useful for mapping static resources, ie serving out images and CSS directly instead of through FastCGI:
     209{{{
     210# Aliasing functionality is needed
     211server.modules += ("mod_alias")
     212
     213# Set up an alias for the static resources
     214alias.url = ("/trac/chrome/common" => "/usr/share/trac/htdocs")
     215
     216# Use negative lookahead, matching all requests that ask for any resource under /trac, EXCEPT in
     217# /trac/chrome/common, and use FastCGI for those
     218$HTTP["url"] =~ "^/trac(?!/chrome/common)" {
     219# Even if you have other fastcgi.server declarations for applications other than Trac, do NOT use += here
     220fastcgi.server = ("/trac" =>
     221                   ("trac" =>
     222                     ("socket" => "/tmp/trac-fastcgi.sock",
     223                      "bin-path" => fcgi_binary,
     224                      "check-local" => "disable",
     225                      "bin-environment" =>
     226                        ("TRAC_ENV" => "/path/to/projenv")
     227                     )
     228                   )
     229                 )
     230}
     231}}}
     232
     233The technique can be easily adapted for use with multiple projects by creating aliases for each of them, and wrapping the fastcgi.server declarations inside conditional configuration blocks.
     234Also there is another way to handle multiple projects and it's to use TRAC_ENV_PARENT_DIR instead of TRAC_ENV and use global auth, let's see an example:
     235{{{
     236#  This is for handling multiple projects
     237  alias.url       = ( "/trac/" => "/path/to/trac/htdocs/" )
     238
     239  fastcgi.server += ("/projects"  =>
     240                      ("trac" =>
     241                        (
     242                          "socket" => "/tmp/trac.sock",
     243                          "bin-path" => fcgi_binary,
     244                          "check-local" => "disable",
     245                          "bin-environment" =>
     246                            ("TRAC_ENV_PARENT_DIR" => "/path/to/parent/dir/of/projects/" )
     247                        )
     248                      )
     249                    )
     250#And here starts the global auth configuration
     251  auth.backend = "htpasswd"
     252  auth.backend.htpasswd.userfile = "/path/to/unique/htpassword/file/trac.htpasswd"
     253  $HTTP["url"] =~ "^/projects/.*/login$" {
     254    auth.require = ("/" =>
     255                     (
     256                       "method"  => "basic",
     257                       "realm"   => "trac",
     258                       "require" => "valid-user"
     259                     )
     260                   )
     261  }
     262}}}
     263
     264Changing date/time format also supported by lighttpd over environment variable LC_TIME:
     265{{{
     266fastcgi.server = ("/trac" =>
     267                   ("trac" =>
     268                     ("socket" => "/tmp/trac-fastcgi.sock",
     269                      "bin-path" => fcgi_binary,
     270                      "check-local" => "disable",
     271                      "bin-environment" =>
     272                        ("TRAC_ENV" => "/path/to/projenv",
     273                        "LC_TIME" => "ru_RU")
     274                     )
     275                   )
     276                 )
     277}}}
     278For details about languages specification see [trac:TracFaq TracFaq] question 2.13.
     279
     280Other important information like the [wiki:TracInstall#MappingStaticResources mapping static resources advices] are useful for non-fastcgi specific installation aspects.
     281]
     282
     283Relaunch Lighttpd and browse to `http://yourhost.example.org/trac` to access Trac.
     284
     285Note about running Lighttpd with reduced permissions: If nothing else helps and trac.fcgi doesn't start with Lighttpd settings `server.username = "www-data"`, `server.groupname = "www-data"`, then in the `bin-environment` section set `PYTHON_EGG_CACHE` to the home directory of `www-data` or some other directory accessible to this account for writing.
     286
     287== Simple !LiteSpeed Configuration
     288
     289The FastCGI front-end was developed primarily for use with alternative webservers, such as [http://www.litespeedtech.com/ LiteSpeed].
     290
     291!LiteSpeed web server is an event-driven asynchronous Apache replacement designed from the ground-up to be secure, scalable, and operate with minimal resources. !LiteSpeed can operate directly from an Apache config file and is targeted for business-critical environments.
     292
     293 1. Please make sure you have a working install of a Trac project. Test install with "tracd" first.
     294
     295 2. Create a Virtual Host for this setup. From now on we will refer to this vhost as !TracVhost. For this tutorial we will be assuming that your Trac project will be accessible via:
     296{{{
     297http://yourdomain.com/trac/
     298}}}
     299
     300 3. Go "!TracVhost → External Apps" tab and create a new "External Application".
     301{{{
     302Name: MyTracFCGI       
     303Address: uds://tmp/lshttpd/mytracfcgi.sock
     304Max Connections: 10
     305Environment: TRAC_ENV=/fullpathto/mytracproject/ <--- path to root folder of trac project
     306Initial Request Timeout (secs): 30
     307Retry Timeout (secs): 0
     308Persistent Connection   Yes
     309Connection Keepalive Timeout: 30
     310Response Bufferring: No
     311Auto Start: Yes
     312Command: /usr/share/trac/cgi-bin/trac.fcgi  <--- path to trac.fcgi
     313Back Log: 50
     314Instances: 10
     315}}}
     316
     317 4. Optional: If you need to use htpasswd based authentication. Go to "!TracVhost → Security" tab and create a new security Realm.
     318
     319{{{
     320DB Type: Password File
     321Realm Name: MyTracUserDB               <--- any name you wish and referenced later
     322User DB Location: /fullpathto/htpasswd <--- path to your htpasswd file
     323}}}
     324
     325If you don’t have a htpasswd file or don’t know how to create the entries within one, go to http://sherylcanter.com/encrypt.php, to generate the user:password combos.
     326
     327 5. Go to "!PythonVhost → Contexts" and create a new FCGI Context.
     328
     329{{{
     330URI: /trac/                              <--- URI path to bind to python fcgi app we created   
     331Fast CGI App: [VHost Level] MyTractFCGI  <--- select the trac fcgi extapp we just created
     332Realm: TracUserDB                        <--- only if (4) is set. select realm created in (4)
     333}}}
     334
     335 6. Modify `/fullpathto/mytracproject/conf/trac.ini`
     336
     337{{{
     338#find/set base_rul, url, and link variables
     339base_url = http://yourdomain.com/trac/ <--- base url to generate correct links to
     340url = http://yourdomain.com/trac/      <--- link of project
     341link = http://yourdomain.com/trac/     <--- link of graphic logo
     342}}}
     343
     344 7. Restart !LiteSpeed, “lswsctrl restart”, and access your new Trac project at:
     345
     346{{{
     347http://yourdomain.com/trac/
     348}}}
     349
     350== Simple Nginx Configuration
     351
     352Nginx is able to communicate with FastCGI processes, but can not spawn them. So you need to start FastCGI server for Trac separately.
     353
     354 1. Nginx configuration with basic authentication handled by Nginx - confirmed to work on 0.6.32
     355 {{{
     356    server {
     357        listen       10.9.8.7:443;
     358        server_name  trac.example;
     359
     360        ssl                  on;
     361        ssl_certificate      /etc/ssl/trac.example.crt;
     362        ssl_certificate_key  /etc/ssl/trac.example.key;
     363
     364        ssl_session_timeout  5m;
     365
     366        ssl_protocols  SSLv2 SSLv3 TLSv1;
     367        ssl_ciphers  ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;
     368        ssl_prefer_server_ciphers   on;
     369
     370        # it makes sense to serve static resources through Nginx (or ``~ [/some/prefix]/chrome/(.*)``)
     371        location ~ /chrome/(.*) {
     372             alias /home/trac/instance/static/htdocs/$1;
     373        }
     374
     375        # You can copy this whole location to ``location [/some/prefix](/login)``
     376        # and remove the auth entries below if you want Trac to enforce
     377        # authorization where appropriate instead of needing to authenticate
     378        # for accessing the whole site.
     379        # (Or ``~ location /some/prefix(/.*)``.)
     380        location ~ (/.*) {
     381            auth_basic            "trac realm";
     382            auth_basic_user_file /home/trac/htpasswd;
     383
     384            # socket address
     385            fastcgi_pass   unix:/home/trac/run/instance.sock;
     386
     387            # python - wsgi specific
     388            fastcgi_param HTTPS on;
     389
     390            ## WSGI REQUIRED VARIABLES
     391            # WSGI application name - trac instance prefix.
     392            # (Or ``fastcgi_param  SCRIPT_NAME  /some/prefix``.)
     393            fastcgi_param  SCRIPT_NAME        "";
     394            fastcgi_param  PATH_INFO          $1;
     395
     396            ## WSGI NEEDED VARIABLES - trac warns about them
     397            fastcgi_param  REQUEST_METHOD     $request_method;
     398            fastcgi_param  SERVER_NAME        $server_name;
     399            fastcgi_param  SERVER_PORT        $server_port;
     400            fastcgi_param  SERVER_PROTOCOL    $server_protocol;
     401            fastcgi_param  QUERY_STRING       $query_string;
     402
     403            # For Nginx authentication to work - do not forget to comment these
     404            # lines if not using Nginx for authentication
     405            fastcgi_param  AUTH_USER          $remote_user;
     406            fastcgi_param  REMOTE_USER        $remote_user;
     407
     408            # for ip to work
     409            fastcgi_param REMOTE_ADDR         $remote_addr;
     410
     411            # For attchments to work
     412            fastcgi_param    CONTENT_TYPE     $content_type;
     413            fastcgi_param    CONTENT_LENGTH   $content_length;
     414        }
     415    }
     416}}}
     417 1. Modified trac.fcgi:
     418 {{{
     419#!/usr/bin/env python
     420import os
     421sockaddr = '/home/trac/run/instance.sock'
     422os.environ['TRAC_ENV'] = '/home/trac/instance'
     423
     424try:
     425     from trac.web.main import dispatch_request
     426     import trac.web._fcgi
     427
     428     fcgiserv = trac.web._fcgi.WSGIServer(dispatch_request,
     429          bindAddress = sockaddr, umask = 7)
     430     fcgiserv.run()
     431
     432except SystemExit:
     433    raise
     434except Exception, e:
     435    print 'Content-Type: text/plain\r\n\r\n',
     436    print 'Oops...'
     437    print
     438    print 'Trac detected an internal error:'
     439    print
     440    print e
     441    print
     442    import traceback
     443    import StringIO
     444    tb = StringIO.StringIO()
     445    traceback.print_exc(file=tb)
     446    print tb.getvalue()
     447
     448}}}
     449 1. reload nginx and launch trac.fcgi like that:
     450 {{{#!sh
     451trac@trac.example ~ $ ./trac-standalone-fcgi.py
     452}}}
     453
     454The above assumes that:
     455 * There is a user named 'trac' for running trac instances and keeping trac environments in its home directory
     456 * `/home/trac/instance` contains a trac environment
     457 * `/home/trac/htpasswd` contains authentication information
     458 * `/home/trac/run` is owned by the same group the nginx runs under
     459  * and if your system is Linux the `/home/trac/run` has setgid bit set (`chmod g+s run`)
     460  * and patch from ticket #T7239 is applied, or you'll have to fix the socket file permissions every time
     461
     462Unfortunately nginx does not support variable expansion in fastcgi_pass directive.
     463Thus it is not possible to serve multiple Trac instances from one server block.
     464
     465If you worry enough about security, run Trac instances under separate users.
     466
     467Another way to run Trac as a FCGI external application is offered in ticket #T6224
     468
     469----
     470See also:  TracGuide, TracInstall, [wiki:TracModWSGI ModWSGI], [wiki:TracCgi CGI], [wiki:TracModPython ModPython], [trac:TracNginxRecipe TracNginxRecipe]

  • wiki/pages/TracFineGrainedPermissions

    r40221 r40226  
     1= Fine grained permissions =
     2[[PageOutline(2-5, Contents, floated)]]
     3[[TracGuideToc]]
     4
     5There is a general mechanism in place that allows custom **permission policy plugins** to grant or deny any action on any kind of Trac resource, even at the level of specific versions of such resources.
     6
     7That mechanism is `authz_policy`, which is an optional module in `tracopt.perm.authz_policy.*`, so it is installed by default. It can be activated via the //Plugins// panel in the Trac administration module.
     8
     9== Permission Policies ==
     10
     11A great diversity of permission policies can be implemented and Trac comes with a few examples.
     12
     13Which policies are currently active is determined by a configuration setting in TracIni:
     14
     15{{{#!ini
     16[trac]
     17permission_policies = ReadonlyWikiPolicy, DefaultPermissionPolicy, LegacyAttachmentPolicy
     18}}}
     19This lists the [#ReadonlyWikiPolicy] which controls readonly access to wiki pages, followed by the !DefaultPermissionPolicy which checks for the traditional coarse grained style permissions described in TracPermissions, and the !LegacyAttachmentPolicy which knows how to use the coarse grained permissions for checking the permissions available on attachments.
     20
     21Among the optional choices, there is [#AuthzPolicy], a very generic permission policy, based on an Authz-style system. See
     22[trac:source:branches/1.0-stable/tracopt/perm/authz_policy.py authz_policy.py] for details.
     23
     24Another popular permission policy [#AuthzSourcePolicy], re-implements the pre-0.12 support for checking fine-grained permissions limited to Subversion repositories in terms of the new system.
     25
     26See also [trac:source:branches/1.0-stable/sample-plugins/permissions sample-plugins/permissions] for more examples.
     27
     28=== !AuthzPolicy ===
     29==== Configuration ====
     30* Put a [http://swapoff.org/files/authzpolicy.conf authzpolicy.conf] file somewhere, preferably on a secured location on the server, not readable for others than the webuser. If the  file contains non-ASCII characters, the UTF-8 encoding should be used.
     31* Update your `trac.ini`:
     32  1. modify the [TracIni#trac-section permission_policies] entry in the `[trac]` section:
     33{{{#!ini
     34[trac]
     35...
     36permission_policies = AuthzPolicy, ReadonlyWikiPolicy, DefaultPermissionPolicy, LegacyAttachmentPolicy
     37}}}
     38  1. add a new `[authz_policy]` section:
     39{{{#!ini
     40[authz_policy]
     41authz_file = /some/trac/env/conf/authzpolicy.conf
     42}}}
     43  1. enable the plugin through [/admin/general/plugin WebAdmin] or by editing the `[components]` section:
     44{{{#!ini
     45[components]
     46tracopt.perm.authz_policy.* = enabled
     47}}}
     48
     49==== Usage Notes ====
     50
     51Note the order in which permission policies are specified: policies are implemented in the sequence provided and therefore may override earlier policy specifications.
     52
     53A policy will return either `True`, `False` or `None` for a given permission check. `True` is returned if the policy explicitly grants the permission. `False` is returned if the policy explicitly denies the permission. `None` is returned if the policy is unable to either grant or deny the permission.
     54
     55NOTE: Only if the return value is `None` will the ''next'' permission policy be consulted. If none of the policies explicitly grants the permission, the final result will be `False`, i.e. permission denied.
     56
     57The `authzpolicy.conf` file is a `.ini` style configuration file:
     58{{{#!ini
     59[wiki:PrivatePage@*]
     60john = WIKI_VIEW, !WIKI_MODIFY
     61jack = WIKI_VIEW
     62* =
     63}}}
     64* Each section of the config is a glob pattern used to match against a Trac resource descriptor. These descriptors are in the form:
     65{{{
     66<realm>:<id>@<version>[/<realm>:<id>@<version> ...]
     67}}}
     68
     69Resources are ordered left to right, from parent to child. If any component is inapplicable, `*` is substituted. If the version pattern is not specified explicitly, all versions (`@*`) is added implicitly. Example: Match the WikiStart page:
     70{{{#!ini
     71[wiki:*]
     72[wiki:WikiStart*]
     73[wiki:WikiStart@*]
     74[wiki:WikiStart]
     75}}}
     76
     77Example: Match the attachment `wiki:WikiStart@117/attachment:FOO.JPG@*` on WikiStart:
     78{{{#!ini
     79[wiki:*]
     80[wiki:WikiStart*]
     81[wiki:WikiStart@*]
     82[wiki:WikiStart@*/attachment:*]
     83[wiki:WikiStart@117/attachment:FOO.JPG]
     84}}}
     85
     86* Sections are checked against the current Trac resource descriptor '''IN ORDER''' of appearance in the configuration file. '''ORDER IS CRITICAL'''.
     87
     88* Once a section matches, the current username is matched against the keys (usernames) of the section, '''IN ORDER'''.
     89  * If a key (username) is prefixed with a `@`, it is treated as a group.
     90  * If a value (permission) is prefixed with a `!`, the permission is denied rather than granted.
     91
     92The username will match any of 'anonymous', 'authenticated', <username> or '*', using normal Trac permission rules. || '''Note:''' Other groups which are created by user (e.g. by 'adding subjects to groups' on web interface page //Admin / Permissions//) cannot be used. See [trac:ticket:5648 #5648] for details about this missing feature. ||
     93
     94For example, if the `authz_file` contains:
     95{{{#!ini
     96[wiki:WikiStart@*]
     97* = WIKI_VIEW
     98
     99[wiki:PrivatePage@*]
     100john = WIKI_VIEW
     101* = !WIKI_VIEW
     102}}}
     103and the default permissions are set like this:
     104{{{
     105john           WIKI_VIEW
     106jack           WIKI_VIEW
     107# anonymous has no WIKI_VIEW
     108}}}
     109
     110Then:
     111  * All versions of WikiStart will be viewable by everybody, including anonymous
     112  * !PrivatePage will be viewable only by john
     113  * other pages will be viewable only by john and jack
     114
     115Groups:
     116{{{#!ini
     117[groups]
     118admins = john, jack
     119devs = alice, bob
     120
     121[wiki:Dev@*]
     122@admins = TRAC_ADMIN
     123@devs = WIKI_VIEW
     124* =
     125
     126[*]
     127@admins = TRAC_ADMIN
     128* =
     129}}}
     130
     131Then:
     132- everything is blocked (whitelist approach), but
     133- admins get all TRAC_ADMIN everywhere and
     134- devs can view wiki pages.
     135
     136Some repository examples (Browse Source specific):
     137{{{#!ini
     138# A single repository:
     139[repository:test_repo@*]
     140john = BROWSER_VIEW, FILE_VIEW
     141# John has BROWSER_VIEW and FILE_VIEW for the entire test_repo
     142
     143# The default repository (requires Trac 1.0.2 or later):
     144[repository:@*]
     145john = BROWSER_VIEW, FILE_VIEW
     146# John has BROWSER_VIEW and FILE_VIEW for the entire default repository
     147
     148# All repositories:
     149[repository:*@*]
     150jack = BROWSER_VIEW, FILE_VIEW
     151# Jack has BROWSER_VIEW and FILE_VIEW for all repositories
     152}}}
     153
     154Very granular repository access:
     155{{{#!ini
     156# John has BROWSER_VIEW and FILE_VIEW access to trunk/src/some/location/ only
     157[repository:test_repo@*/source:trunk/src/some/location/*@*]
     158john = BROWSER_VIEW, FILE_VIEW
     159
     160# John has BROWSER_VIEW and FILE_VIEW access to only revision 1 of all files at trunk/src/some/location only
     161[repository:test_repo@*/source:trunk/src/some/location/*@1]
     162john = BROWSER_VIEW, FILE_VIEW
     163
     164# John has BROWSER_VIEW and FILE_VIEW access to all revisions of 'somefile' at trunk/src/some/location only
     165[repository:test_repo@*/source:trunk/src/some/location/somefile@*]
     166john = BROWSER_VIEW, FILE_VIEW
     167
     168# John has BROWSER_VIEW and FILE_VIEW access to only revision 1 of 'somefile' at trunk/src/some/location only
     169[repository:test_repo@*/source:trunk/src/some/location/somefile@1]
     170john = BROWSER_VIEW, FILE_VIEW
     171}}}
     172
     173Note: In order for Timeline to work/visible for John, we must add CHANGESET_VIEW to the above permission list.
     174
     175==== Missing Features ====
     176Although possible with the !DefaultPermissionPolicy handling (see Admin panel), fine-grained permissions still miss those grouping features (see [trac:ticket:9573 #9573], [trac:ticket:5648 #5648]). Patches are partially available, see authz_policy.2.patch, part of [trac:ticket:6680 #6680].
     177
     178You cannot do the following:
     179{{{#!ini
     180[groups]
     181team1 = a, b, c
     182team2 = d, e, f
     183team3 = g, h, i
     184departmentA = team1, team2
     185}}}
     186
     187Permission groups are not supported either, so you cannot do the following:
     188{{{#!ini
     189[groups]
     190permission_level_1 = WIKI_VIEW, TICKET_VIEW
     191permission_level_2  = permission_level_1, WIKI_MODIFY, TICKET_MODIFY
     192[*]
     193@team1 = permission_level_1
     194@team2 = permission_level_2
     195@team3 = permission_level_2, TICKET_CREATE
     196}}}
     197
     198=== !AuthzSourcePolicy  (mod_authz_svn-like permission policy) === #AuthzSourcePolicy
     199
     200At the time of this writing, the old granular permissions system from Trac 0.11 and before used for restricting access to the repository has been converted to a permission policy component. But from the user's point of view, this makes little if any difference.
     201
     202That kind of granular permission control needs a definition file, which is the one used by Subversion's mod_authz_svn.
     203More information about this file format and about its usage in Subversion is available in the [http://svnbook.red-bean.com/en/1.5/svn.serverconfig.pathbasedauthz.html Path-Based Authorization] section in the Server Configuration chapter of the svn book.
     204
     205Example:
     206{{{#!ini
     207[/]
     208* = r
     209
     210[/branches/calc/bug-142]
     211harry = rw
     212sally = r
     213
     214[/branches/calc/bug-142/secret]
     215harry =
     216}}}
     217
     218 * '''/''' = ''Everyone has read access by default''
     219 * '''/branches/calc/bug-142''' = ''harry has read/write access, sally read only''
     220 * '''/branches/calc/bug-142/secret''' = ''harry has no access, sally has read access (inherited as a sub folder permission)''
     221
     222==== Trac Configuration ====
     223
     224To activate granular permissions you __must__ specify the {{{authz_file}}} option in the `[svn]` section of trac.ini. If this option is set to null or not specified, the permissions will not be used.
     225
     226{{{#!ini
     227[svn]
     228authz_file = /path/to/svnaccessfile
     229}}}
     230
     231If you want to support the use of the `[`''modulename''`:/`''some''`/`''path''`]` syntax within the `authz_file`, add:
     232
     233{{{#!ini
     234authz_module_name = modulename
     235}}}
     236
     237where ''modulename'' refers to the same repository indicated by the `<name>.dir` entry in the `[repositories]` section. As an example, if the `somemodule.dir` entry in the `[repositories]` section is `/srv/active/svn/somemodule`, that would yield the following:
     238
     239{{{ #!ini
     240[svn]
     241authz_file = /path/to/svnaccessfile
     242authz_module_name = somemodule
     243...
     244[repositories]
     245somemodule.dir = /srv/active/svn/somemodule
     246}}}
     247
     248where the svn access file, {{{/path/to/svnaccessfile}}}, contains entries such as {{{[somemodule:/some/path]}}}.
     249
     250'''Note:''' Usernames inside the Authz file __must__ be the same as those used inside trac.
     251
     252As of version 0.12, make sure you have ''!AuthzSourcePolicy'' included in the permission_policies list in trac.ini, otherwise the authz permissions file will be ignored.
     253
     254{{{#!ini
     255[trac]
     256permission_policies = AuthzSourcePolicy, ReadonlyWikiPolicy, DefaultPermissionPolicy, LegacyAttachmentPolicy
     257}}}
     258
     259==== Subversion Configuration ====
     260
     261The same access file is typically applied to the corresponding Subversion repository using an Apache directive like this:
     262{{{#!apache
     263<Location /repos>
     264  DAV svn
     265  SVNParentPath /usr/local/svn
     266
     267  # our access control policy
     268  AuthzSVNAccessFile /path/to/svnaccessfile
     269</Location>
     270}}}
     271
     272For information about how to restrict access to entire projects in a multiple project environment see [trac:wiki:TracMultipleProjectsSVNAccess].
     273
     274=== ReadonlyWikiPolicy
     275
     276Since 1.1.2, the read-only attribute of wiki pages is enabled and enforced when `ReadonlyWikiPolicy` is in the list of active permission policies. The default for new Trac installations in 1.1.2 and later is:
     277{{{
     278[trac]
     279permission_policies = ReadonlyWikiPolicy,
     280 DefaultPermissionPolicy,
     281 LegacyAttachmentPolicy
     282}}}
     283
     284When upgrading from earlier versions of Trac, `ReadonlyWikiPolicy` will be appended to the list of `permission_policies` when upgrading the environment, provided that `permission_policies` has the default value. If any non-default `permission_polices` are active, `ReadonlyWikiPolicy` **will need to be manually added** to the list. A message will be echoed to the console when upgrading the environment, indicating if any action needs to be taken.
     285
     286**!ReadonlyWikiPolicy must be listed //before// !DefaultPermissionPolicy**. The latter returns `True` to allow modify, delete or rename actions when the user has the respective `WIKI_*` permission, without consideration for the read-only attribute.
     287
     288The `ReadonlyWikiPolicy` returns `False` to deny modify, delete and rename actions on wiki pages when the page has the read-only attribute set and the user does not have `WIKI_ADMIN`, regardless of `WIKI_MODIFY`, `WIKI_DELETE` and `WIKI_RENAME` permissions. It returns `None` for all other cases.
     289
     290When active, the [#AuthzPolicy] should therefore come before `ReadonlyWikiPolicy`, allowing it to grant or deny the actions on individual resources, which is the usual ordering for `AuthzPolicy` in the `permission_policies` list.
     291{{{
     292[trac]
     293permission_policies = AuthzPolicy,
     294 ReadonlyWikiPolicy,
     295 DefaultPermissionPolicy,
     296 LegacyAttachmentPolicy
     297}}}
     298
     299The placement of [#AuthzSourcePolicy] relative to `ReadonlyWikiPolicy` does not matter since they don't perform checks on the same realms.
     300
     301For all other permission policies, the user will need to decide the proper ordering. Generally, if the permission policy should be capable of overriding the check performed by `ReadonlyWikiPolicy`, it should come before `ReadonlyWikiPolicy` in the list. If the `ReadonlyWikiPolicy` should override the check performed by another permission policy, as is the case for `DefaultPermissionPolicy`, then `ReadonlyWikiPolicy` should come first.
     302
     303== Debugging permissions
     304In trac.ini set:
     305{{{#!ini
     306[logging]
     307log_file = trac.log
     308log_level = DEBUG
     309log_type = file
     310}}}
     311
     312Display the trac.log to understand what checks are being performed:
     313{{{#!sh
     314tail -n 0 -f log/trac.log | egrep '\[perm\]|\[authz_policy\]'
     315}}}
     316
     317See the sourced documentation of the plugin for more info.
     318
     319----
     320See also: TracPermissions,
     321[http://trac-hacks.org/wiki/FineGrainedPageAuthzEditorPlugin TracHacks:FineGrainedPageAuthzEditorPlugin] for a simple editor plugin.

  • wiki/pages/TracGuide

    r40221 r40226  
     1= The Trac User and Administration Guide =
     2[[TracGuideToc]]
     3{{{#!span style="font-size:90%"
     4//The TracGuide is meant to serve as a starting point for all documentation regarding Trac usage and development. The guide is a free document, a collaborative effort, and a part of the [http://trac.edgewall.org Trac Project] itself.//
     5}}}
     6
     7== Introduction
     8
     9Trac is an enhanced wiki and issue tracking system for software development projects. Trac uses a minimalistic approach to web-based software project management. It strives to help developers write great software while staying out of the way. Trac should impose as little as possible on a team's established development process and policies.
     10
     11It provides an interface to Subversion (and other version control systems), an integrated Wiki and convenient reporting facilities.
     12
     13Trac allows wiki markup in issue descriptions and commit messages, creating links and seamless references between bugs, tasks, changesets, files and wiki pages. A timeline shows all current and past project events in order, making the acquisition of an overview of the project and tracking progress very easy. The roadmap shows the road ahead, listing the upcoming milestones.
     14== User Guide
     15   * Using the Wiki subsystem
     16     * TracWiki — How to use the built-in Wiki.
     17     * WikiFormatting — Reference to the wiki syntax used throughout.
     18   * Using the Version Control subsystem
     19     * TracBrowser — Browsing source code with Trac.
     20     * TracChangeset — Viewing changes to source code.
     21     * TracRevisionLog — Viewing change history.
     22   * Using the Ticket subsystem
     23     * TracTickets — Using the issue tracker.
     24     * TracRoadmap — The roadmap helps tracking project progress.
     25     * TracReports — Writing and using reports.
     26     * TracQuery — Executing custom ticket queries.
     27     * TracBatchModify - Modifying a batch of tickets in one request.
     28   * Other modules and general topics
     29     * TracSearch — Full text search in all content.
     30     * TracTimeline — The timeline provides a historic perspective on a project.
     31     * TracRss — RSS content syndication in Trac.
     32     * TracAccessibility — Accessibility keys support
     33
     34
     35== Administrator Guide
     36   * Installation and upgrade
     37     * TracInstall — How to install and run Trac.
     38     * TracUpgrade — How to upgrade existing installations.
     39     * TracImport — Importing tickets from other bug databases.
     40     * TracPlugins — Installing and managing Trac extensions.
     41   * Configuration and customization
     42     * TracIni — Trac configuration file reference.
     43     * TracPermissions — Access control and permissions.
     44     * TracNavigation — Customize main navigation menus.
     45     * TracInterfaceCustomization — Customizing the Trac interface.
     46     * TracLogging — The Trac logging facility.
     47   * Administering the Version Control subsystem
     48     * TracRepositoryAdmin — Management of Source Code Repositories.
     49   * Administering the Ticket subsystem
     50     * TracTicketsCustomFields — Expanding tickets with customized fields.
     51     * TracNotification — Email notification.
     52     * TracWorkflow — Configurable Ticket Workflow.
     53   * Reference
     54     * TracEnvironment — All you need to know about Trac environments
     55     * TracAdmin — Administering a Trac project via the command-line.
     56
     57== Support and Other Sources of Information ==
     58
     59 * [trac:TracFaq Trac FAQ] — A collection of Frequently Asked Questions (on the project website).
     60 * [trac:TracDev] and [trac:TracDev/ApiDocs API docs] — Trac Developer documentation
     61 * TracSupport — How to get more information
     62
     63If you are looking for a good place to ask a question about Trac, look no further than the [trac:MailingList MailingList]. It provides a friendly environment to discuss openly among Trac users and developers.

  • wiki/pages/TracImport

    r40221 r40226  
     1= Importing ticket data =
     2[[PageOutline]]
     3
     4To migrate issue tickets from other issue-tracking systems or perform housekeeping actions on tickets or simply synchronize different databases, there are some tools, plug-ins and scripts available, which let you import or update tickets into Trac.
     5
     6== !TicketImportPlugin ==
     7
     8[http://trac-hacks.org/wiki/TicketImportPlugin TicketImportPlugin]: this plug-in lets you import or update into Trac a series of tickets from a '''CSV file''' or (if the [http://pypi.python.org/pypi/xlrd xlrd library] is installed) from an '''Excel spreadsheet'''.
     9
     10== !ExportImportXlsPlugin ==
     11
     12[http://trac-hacks.org/wiki/ExportImportXlsPlugin ExportImportXlsPlugin]: this plug-in adds an admin panel for exporting and importing tickets via '''XLS file'''. Requires the python packages xlwt/rxld.
     13
     14== Bugzilla ==
     15
     16[http://trac-hacks.org/wiki/BugzillaIssueTrackingPlugin BugzillaIssueTrackingPlugin]: integrates Bugzilla issue data into Trac keeping TracLinks. Ticket data can be imported from Bugzilla using the [trac:browser:trunk/contrib/bugzilla2trac.py bugzilla2trac.py] script, available in the contrib/ directory of the Trac distribution.
     17
     18{{{
     19$ bugzilla2trac.py
     20bugzilla2trac - Imports a bug database from Bugzilla into Trac.
     21
     22Usage: bugzilla2trac.py [options]
     23
     24Available Options:
     25  --db <MySQL dbname>              - Bugzilla's database
     26  --tracenv /path/to/trac/env      - full path to Trac db environment
     27  -h | --host <MySQL hostname>     - Bugzilla's DNS host name
     28  -u | --user <MySQL username>     - effective Bugzilla's database user
     29  -p | --passwd <MySQL password>   - Bugzilla's user password
     30  -c | --clean                     - remove current Trac tickets before importing
     31  --help | help                    - this help info
     32
     33Additional configuration options can be defined directly in the script.
     34}}}
     35
     36Currently, the following data is imported from Bugzilla:
     37  * bugs
     38  * bug activity (field changes)
     39  * bug attachments
     40  * user names and passwords (put into a htpasswd file)
     41
     42The script provides a number of features to ease the conversion, such as:
     43  * PRODUCT_KEYWORDS: Trac has no concept of products, so the script provides the ability to attach a ticket keyword instead.
     44  * IGNORE_COMMENTS: Don't import Bugzilla comments that match a certain regexp.
     45  * STATUS_KEYWORDS: Attach ticket keywords for the Bugzilla statuses not available in Trac. By default, the 'VERIFIED' and 'RELEASED' Bugzilla statuses are translated into Trac keywords.
     46
     47For more details on the available options, see the configuration section at the top of the script.
     48
     49=== Known Issues ===
     50{{{
     51#!comment
     52                   Don't merge this section in the default page
     53}}}
     54[[TicketQuery(keywords=~bugzilla,status=!closed)]]
     55
     56The adequate milestone for valid bugzilla2trac issue is usually ''Not applicable'', which means that fixes to the contributed script are not planned for a particular Trac release, but can happen anytime.
     57
     58== Jira ==
     59
     60[http://trac-hacks.org/wiki/JiraToTracIntegration JiraToTracIntegration]: provides tools to import Atlassian Jira backup files into Trac. The plug-in consists of a Python 3.1 commandline tool that:
     61  - Parses the Jira backup XML file.
     62  - Sends the imported Jira data and attachments to Trac using the [http://trac-hacks.org/wiki/XmlRpcPlugin XmlRpcPlugin].
     63  - Generates a htpasswd file containing the imported Jira users and their SHA-512 base64 encoded passwords.
     64
     65== Mantis ==
     66
     67[http://trac-hacks.org/wiki/MantisImportScript MantisImportScript]: script to import the following data from Mantis into Trac:
     68  * bugs
     69  * bug comments
     70  * bug activity (field changes)
     71  * attachments (as long as the files live in the mantis db, not on the filesystem) .
     72
     73== !PlanetForge ==
     74
     75[http://trac-hacks.org/wiki/PlanetForgeImportExportPlugin PlanetForgeImportExportPlugin]: this plugin exports Trac data (wiki, tickets, compoments, permissions, repositories, etc.) using the open format designed by the COCLICO project. It extends the webadmin panel and the 'trac admin ...' command. Has no 'import' feature.
     76
     77== Scarab ==
     78
     79[http://trac-hacks.org/wiki/ScarabToTracScript ScarabToTracScript]: script that migrates Scarab issues to Trac tickets. Requires [http://trac-hacks.org/wiki/XmlRpcPlugin XmlRpcPlugin]
     80
     81== Sourceforge ==
     82
     83[http://trac-hacks.org/wiki/SfnToTracScript SfnToTracScript]: importer of !SourceForge's new backup file (originated from #Trac3521).
     84Also, ticket data can be imported from Sourceforge using the [trac:browser:trunk/contrib/sourceforge2trac.py sourceforge2trac.py] script, available in the contrib/ directory of the Trac distribution.
     85
     86== Other ==
     87
     88Since Trac uses a SQL database to store the data, you can also custom-import from other systems by examining the database tables. Just go into [http://www.sqlite.org/sqlite.html sqlite] command line to look at the tables and import them from your application.
     89
     90=== Comma delimited file - CSV ===
     91See [trac:attachment:csv2trac.2.py:wiki:TracSynchronize csv2trac.2.py] for details. This approach is particularly useful if you need to enter a large number of tickets by hand. Note that the ticket type type field, (task etc...) is also needed for this script to work with more recent Trac releases.
     92Comments on script: The script has an error on line 168: 'Ticket' needs to be 'ticket'. Also, the listed values for severity and priority are swapped.
     93
     94----
     95See also:
     96 * to import/export wiki pages: TracAdmin,
     97 * to export tickets: TracTickets, TracQuery

  • wiki/pages/TracIni

    r40221 r40226  
     1= The Trac Configuration File
     2
     3[[TracGuideToc]]
     4[[PageOutline]]
     5
     6Trac is configured by editing the **`trac.ini`** file, located in the `<projectenv>/conf` directory. The `trac.ini` configuration file and its parent directory should be writable by the web server.
     7
     8Trac monitors the timestamp of the file to trigger a complete environment reload and flush its caches when the timestamp changes. Most changes to the configuration will be reflected immediately, though changes to the `[components]` or `[logging]` sections will require restarting the web server. You may also need to restart the web server after creating a [#GlobalConfiguration global configuration] file when none was previously present.
     9
     10== Global Configuration
     11
     12Configuration can be shared among environments using one or more global configuration files. Options in the global configuration will be merged with the environment-specific options, with local options overriding global options. The global configuration file is specified as follows:
     13{{{#!ini
     14[inherit]
     15file = /path/to/global/trac.ini
     16}}}
     17Multiple files can be specified using a comma-separated list.
     18
     19Note that you can also specify a global option file when creating a new project,  by adding the option `--inherit=/path/to/global/trac.ini` to [TracAdmin#initenv trac-admin]'s `initenv` command.  If you do not do this but nevertheless intend to use a global option file with your new environment, you will have to go through the newly generated `conf/trac.ini` file and delete the entries that will otherwise override those set in the global file.
     20
     21There are two more entries in the [[#inherit-section| [inherit] ]] section, `templates_dir` for sharing global templates and `plugins_dir`, for sharing plugins. Those entries can themselves be specified in the shared configuration file, and in fact, configuration files can even be chained if you specify another `[inherit] file` there.
     22
     23Note that the templates found in the `templates/` directory of the TracEnvironment have precedence over those found in `[inherit] templates_dir`. In turn, the latter have precedence over the installed templates, so be careful about what you put there. Notably, if you override a default template, refresh your modifications when you upgrade to a new version of Trac. The preferred way to perform TracInterfaceCustomization is still to write a custom plugin doing an appropriate `ITemplateStreamFilter` transformation.
     24
     25== Reference for settings
     26
     27This is a brief reference of available configuration options, and their default settings.
     28
     29Documentation improvements should be discussed on the [trac:MailingList#Trac-dev trac-dev mailing list] or described in a [trac:NewTicket ticket]. Even better, [trac:TracDev/SubmittingPatches submit a patch] against the docstrings in the code.
     30{{{ #!comment
     31Please don't waste your time by editing the HTML code below, changes won't be picked up. Instead, follow the above guidance for suggesting documentation improvements.
     32}}}
     33[[TracIni]]
     34
     35----
     36See also: TracGuide, TracAdmin, TracEnvironment

  • wiki/pages/TracInstall

    r40221 r40226  
     1= Trac Installation Guide for 1.1
     2[[TracGuideToc]]
     3
     4Trac is written in the Python programming language and needs a database, [http://sqlite.org/ SQLite], [http://www.postgresql.org/ PostgreSQL], or [http://mysql.com/ MySQL]. For HTML rendering, Trac uses the [http://genshi.edgewall.org Genshi] templating system.
     5
     6Trac can also be localized, and there is probably a translation available in your language. If you want to use the Trac interface in other languages, then make sure you have installed the optional package [#OtherPythonPackages Babel]. Pay attention to the extra steps for localization support in the [#InstallingTrac Installing Trac] section below. Lacking Babel, you will only get the default English version.
     7
     8If you're interested in contributing new translations for other languages or enhancing the existing translations, then please have a look at [trac:wiki:TracL10N TracL10N].
     9
     10What follows are generic instructions for installing and setting up Trac. While you may find instructions for installing Trac on specific systems at [trac:TracInstallPlatforms TracInstallPlatforms], please '''first read through these general instructions''' to get a good understanding of the tasks involved.
     11
     12[[PageOutline(2-3,Installation Steps,inline)]]
     13
     14== Dependencies
     15=== Mandatory Dependencies
     16To install Trac, the following software packages must be installed:
     17
     18 * [http://www.python.org/ Python], version >= 2.6 and < 3.0
     19   (note that we dropped the support for Python 2.5 in this release)
     20 * [http://pypi.python.org/pypi/setuptools setuptools], version >= 0.6
     21 * [http://genshi.edgewall.org/wiki/Download Genshi], version >= 0.6
     22
     23You also need a database system and the corresponding python bindings. The database can be either SQLite, PostgreSQL or MySQL.
     24
     25==== For the SQLite database #ForSQLite
     26
     27As you must be using Python 2.6 or 2.7, you already have the SQLite database bindings bundled with the standard distribution of Python (the `sqlite3` module).
     28
     29Optionally, you may install a newer version of [pypi:pysqlite pysqlite] than the one provided by the Python distribution. See [trac:PySqlite#ThePysqlite2bindings PySqlite] for details.
     30
     31==== For the PostgreSQL database #ForPostgreSQL
     32
     33You need to install the database and its Python bindings:
     34 * [http://www.postgresql.org/ PostgreSQL], version 8.0 or later
     35 * [http://pypi.python.org/pypi/psycopg2 psycopg2], version 2.0 or later
     36
     37See [trac:DatabaseBackend#Postgresql DatabaseBackend] for details.
     38
     39==== For the MySQL database #ForMySQL
     40
     41Trac works well with MySQL, provided you follow the guidelines:
     42
     43 * [http://mysql.com/ MySQL], version 5.0 or later
     44 * [http://sf.net/projects/mysql-python MySQLdb], version 1.2.2 or later
     45
     46Given the caveats and known issues surrounding MySQL, read carefully the [trac:MySqlDb] page before creating the database.
     47
     48=== Optional Dependencies
     49
     50==== Subversion
     51
     52[http://subversion.apache.org/ Subversion], 1.6.x or later and the '''''corresponding''''' Python bindings.
     53
     54There are [http://subversion.apache.org/packages.html pre-compiled SWIG bindings] available for various platforms. (Good luck finding precompiled SWIG bindings for any Windows package at that listing. [trac:TracSubversion] points you to [http://alagazam.net Alagazam], which works for me under Python 2.6.)
     55
     56For troubleshooting information, see the [trac:TracSubversion#Troubleshooting TracSubversion] page.
     57
     58{{{#!div style="border: 1pt dotted; margin: 1em"
     59**Note:**
     60* Trac '''doesn't''' use [http://pysvn.tigris.org/ PySVN], nor does it work yet with the newer `ctype`-style bindings.
     61* If using Subversion, Trac must be installed on the '''same machine'''. Remote repositories are currently [trac:ticket:493 not supported].
     62}}}
     63
     64==== Git
     65
     66[http://git-scm.com/ Git] 1.5.6 or later is supported. More information is available on the [trac:TracGit] page.
     67
     68==== Other Version Control Systems
     69
     70Support for other version control systems is provided via third-party plugins. See [trac:PluginList#VersionControlSystems] and [trac:VersionControlSystem].
     71
     72==== Web Server
     73A web server is optional because Trac is shipped with a server included, see the [#RunningtheStandaloneServer Running the Standalone Server] section below.
     74
     75Alternatively you can configure Trac to run in any of the following environments:
     76 * [http://httpd.apache.org/ Apache] with
     77   - [https://github.com/GrahamDumpleton/mod_wsgi mod_wsgi], see [wiki:TracModWSGI] and
     78     [http://code.google.com/p/modwsgi/wiki/IntegrationWithTrac ModWSGI IntegrationWithTrac].
     79   - [http://modpython.org/ mod_python 3.5.0], see TracModPython
     80 * a [http://www.fastcgi.com/ FastCGI]-capable web server (see TracFastCgi)
     81 * an [http://tomcat.apache.org/connectors-doc/ajp/ajpv13a.html AJP]-capable web
     82   server (see [trac:TracOnWindowsIisAjp TracOnWindowsIisAjp])
     83 * Microsoft IIS with FastCGI and a FastCGI-to-WSGI gateway (see [trac:CookBook/Installation/TracOnWindowsIisWfastcgi IIS with FastCGI])
     84 * a CGI-capable web server (see TracCgi), '''but usage of Trac as a cgi script
     85   is highly discouraged''', better use one of the previous options.
     86   
     87
     88==== Other Python Packages
     89
     90 * [http://babel.edgewall.org Babel], version 0.9.6 or >= 1.3,
     91   needed for localization support
     92 * [http://docutils.sourceforge.net/ docutils], version >= 0.3.9
     93   for WikiRestructuredText.
     94 * [http://pygments.org Pygments] for
     95   [TracSyntaxColoring syntax highlighting].
     96 * [http://pytz.sf.net pytz] to get a complete list of time zones,
     97   otherwise Trac will fall back on a shorter list from
     98   an internal time zone implementation.
     99
     100{{{#!div style="border: 1pt dotted; margin: 1em"
     101**Attention**: The available versions of these dependencies are not necessarily interchangeable, so please pay attention to the version numbers. If you are having trouble getting Trac to work, please double-check all the dependencies before asking for help on the [trac:MailingList] or [trac:IrcChannel].
     102}}}
     103
     104Please refer to the documentation of these packages to find out how they are best installed. In addition, most of the [trac:TracInstallPlatforms platform-specific instructions] also describe the installation of the dependencies. Keep in mind however that the information there ''probably concern older versions of Trac than the one you're installing''.
     105
     106== Installing Trac
     107
     108The [TracAdmin trac-admin] command-line tool, used to create and maintain [TracEnvironment project environments], as well as the [TracStandalone tracd] standalone server are installed along with Trac. There are several methods for installing Trac.
     109
     110=== Using `easy_install`
     111Trac can be installed from PyPI or the Subversion repository using [http://pypi.python.org/pypi/setuptools setuptools].
     112
     113A few examples:
     114
     115 - Install Trac 1.0:
     116   {{{#!sh
     117   easy_install Trac==1.0
     118   }}}
     119 - Install latest development version:
     120   {{{#!sh
     121   easy_install Trac==dev
     122   }}}
     123   Note that in this case you won't have the possibility to run a localized version of Trac;
     124   either use a released version or install from source
     125
     126More information can be found on the [trac:setuptools] page.
     127
     128{{{#!div style="border: 1pt dotted; margin: 1em"
     129**Setuptools Warning:** If the version of your setuptools is in the range 5.4 through 5.6, the environment variable `PKG_RESOURCES_CACHE_ZIP_MANIFESTS` must be set in order to avoid significant performance degradation. More information may be found in the sections on [#RunningtheStandaloneServer Running The Standalone Server] and [#RunningTraconaWebServer Running Trac on a Web Server].
     130}}}
     131
     132=== Using `pip`
     133'pip' is an easy_install replacement that is very useful to quickly install python packages.
     134To get a Trac installation up and running in less than 5 minutes:
     135
     136Assuming you want to have your entire pip installation in `/opt/user/trac`
     137
     138 -
     139 {{{#!sh
     140pip install trac psycopg2
     141}}}
     142or
     143 -
     144 {{{#!sh
     145pip install trac mysql-python
     146}}}
     147
     148Make sure your OS specific headers are available for pip to automatically build PostgreSQL (`libpq-dev`) or MySQL (`libmysqlclient-dev`) bindings.
     149
     150pip will automatically resolve all dependencies (like Genshi, pygments, etc.), download the latest packages from pypi.python.org and create a self contained installation in `/opt/user/trac`.
     151
     152All commands (`tracd`, `trac-admin`) are available in `/opt/user/trac/bin`. This can also be leveraged for `mod_python` (using `PythonHandler` directive) and `mod_wsgi` (using `WSGIDaemonProcess` directive)
     153
     154Additionally, you can install several Trac plugins (listed [https://pypi.python.org/pypi?:action=browse&show=all&c=516 here]) through pip.
     155
     156=== From source
     157Using the python-typical setup at the top of the source directory also works. You can obtain the source for a .tar.gz or .zip file corresponding to a release (e.g. `Trac-1.0.tar.gz`) from the [trac:TracDownload] page, or you can get the source directly from the repository. See [trac:TracRepositories#OfficialSubversionrepository TracRepositories] for details.
     158
     159{{{#!sh
     160$ python ./setup.py install
     161}}}
     162
     163''You will need root permissions or equivalent for this step.''
     164
     165This will byte-compile the Python source code and install it as an .egg file or folder in the `site-packages` directory
     166of your Python installation. The .egg will also contain all other resources needed by standard Trac, such as `htdocs` and `templates`.
     167
     168If you install from source and want to make Trac available in other languages, make sure Babel is installed. Only then, perform the `install` (or simply redo the `install` once again afterwards if you realize Babel was not yet installed):
     169{{{#!sh
     170$ python ./setup.py install
     171}}}
     172Alternatively, you can run `bdist_egg` and copy the .egg from `dist/` to the place of your choice, or you can create a Windows installer (`bdist_wininst`).
     173
     174=== Using installer
     175
     176On Windows, Trac can be installed using the exe installers available on the [trac:TracDownload] page. Installers are available for the 32-bit and 64-bit versions of Python. Make sure to use the installer that matches the architecture of your Python installation.
     177
     178=== Using package manager
     179
     180Trac may be available in your platform's package repository. Note however, that the version provided by your package manager may not be the latest release.
     181
     182=== Advanced `easy_install` Options
     183
     184To install Trac to a custom location, or find out about other advanced installation options, run:
     185{{{#!sh
     186easy_install --help
     187}}}
     188
     189Also see [http://docs.python.org/2/install/index.html Installing Python Modules] for detailed information.
     190
     191Specifically, you might be interested in:
     192{{{#!sh
     193easy_install --prefix=/path/to/installdir
     194}}}
     195or, if installing Trac on a Mac OS X system:
     196{{{#!sh
     197easy_install --prefix=/usr/local --install-dir=/Library/Python/2.6/site-packages
     198}}}
     199
     200{{{#!div style="border: 1pt dotted; margin: 1em"
     201**Mac OS X Note:** On Mac OS X 10.6,  running `easy_install trac` will install into `/usr/local` and `/Library/Python/2.6/site-packages` by default.
     202
     203The `tracd` and `trac-admin` commands will be placed in `/usr/local/bin` and will install the Trac libraries and dependencies into `/Library/Python/2.6/site-packages`, which is Apple's preferred location for third-party Python application installations.
     204}}}
     205
     206== Creating a Project Environment
     207
     208A [TracEnvironment Trac environment] is the backend where Trac stores information like wiki pages, tickets, reports, settings, etc. An environment is a directory that contains a human-readable [TracIni configuration file], and other files and directories.
     209
     210A new environment is created using [TracAdmin trac-admin]:
     211{{{#!sh
     212$ trac-admin /path/to/myproject initenv
     213}}}
     214
     215[TracAdmin trac-admin] will prompt you for the information it needs to create the environment: the name of the project and the [TracEnvironment#DatabaseConnectionStrings database connection string]. If you're not sure what to specify for any of these options, just press `<Enter>` to use the default value.
     216
     217Using the default database connection string will always work as long as you have SQLite installed. For the other [trac:DatabaseBackend database backends] you should plan ahead and already have a database ready to use at this point.
     218
     219Also note that the values you specify here can be changed later using TracAdmin or directly editing the [TracIni conf/trac.ini] configuration file.
     220
     221{{{#!div style="border: 1pt dotted; margin: 1em"
     222**Filesystem Warning:** When selecting the location of your environment, make sure that the filesystem on which the environment directory resides supports sub-second timestamps (i.e. **not** `ext2` or `ext3` on Linux, or HFS+ on OSX), as the modification time of the `conf/trac.ini` file will be monitored to decide whether an environment restart is needed or not. A too coarse-grained timestamp resolution may result in inconsistencies in Trac < 1.0.2. The best advice is to opt for a platform with sub-second timestamp resolution, regardless of the Trac version.
     223}}}
     224
     225Finally, make sure the user account under which the web front-end runs will have '''write permissions''' to the environment directory and all the files inside. This will be the case if you run `trac-admin ... initenv` as this user. If not, you should set the correct user afterwards. For example on Linux, with the web server running as user `apache` and group `apache`, enter:
     226{{{#!sh
     227$ chown -R apache:apache /path/to/myproject
     228}}}
     229
     230The actual username and groupname of the apache server may not be exactly `apache`, and are specified in the Apache configuration file by the directives `User` and `Group` (if Apache `httpd` is what you use).
     231
     232{{{#!div class=important
     233'''Warning:''' Please only use ASCII-characters for account name and project path, unicode characters are not supported there.
     234}}}
     235
     236== Deploying Trac
     237
     238=== Running the Standalone Server
     239
     240After having created a Trac environment, you can easily try the web interface by running the standalone server [TracStandalone tracd]:
     241{{{#!sh
     242$ tracd --port 8000 /path/to/myproject
     243}}}
     244
     245Then, fire up a browser and visit `http://localhost:8000/`. You should get a simple listing of all environments that `tracd` knows about. Follow the link to the environment you just created, and you should see Trac in action. If you only plan on managing a single project with Trac you can have the standalone server skip the environment list by starting it like this:
     246{{{#!sh
     247$ tracd -s --port 8000 /path/to/myproject
     248}}}
     249
     250{{{#!div style="border: 1pt dotted; margin: 1em"
     251**Setuptools Warning:** If the version of your setuptools is in the range 5.4 through 5.6, the environment variable `PKG_RESOURCES_CACHE_ZIP_MANIFESTS` must be set in order to avoid significant performance degradation. The environment variable can be set system-wide, or for just the user that runs the `tracd` process. There are several ways to accomplish this in addition to what is discussed here, and depending on the distribution of your OS.
     252
     253To be effective system-wide a shell script with the `export` statement may be added to `/etc/profile.d`. To be effective for a user session the `export` statement may be added to `~/.profile`.
     254{{{#!sh
     255export PKG_RESOURCES_CACHE_ZIP_MANIFESTS=1
     256}}}
     257
     258Alternatively, the variable can be set in the shell before executing `tracd`:
     259{{{#!sh
     260$ PKG_RESOURCES_CACHE_ZIP_MANIFESTS=1 tracd --port 8000 /path/to/myproject
     261}}}
     262}}}
     263
     264=== Running Trac on a Web Server
     265
     266Trac provides various options for connecting to a "real" web server:
     267 - [TracFastCgi FastCGI]
     268 - [wiki:TracModWSGI mod_wsgi]
     269 - [TracModPython mod_python]
     270 - //[TracCgi CGI] (should not be used, as the performance is far from optimal)//
     271
     272Trac also supports [trac:TracOnWindowsIisAjp AJP] which may be your choice if you want to connect to IIS. Other deployment scenarios are possible: [trac:TracNginxRecipe nginx], [http://projects.unbit.it/uwsgi/wiki/Example#Traconapacheinasub-uri uwsgi], [trac:TracOnWindowsIisIsapi Isapi-wsgi] etc.
     273
     274==== Generating the Trac cgi-bin directory #cgi-bin
     275
     276In order for Trac to function properly with FastCGI you need to have a `trac.fcgi` file and for mod_wsgi a `trac.wsgi` file. These are Python scripts which load the appropriate Python code. They can be generated using the `deploy` option of [TracAdmin trac-admin].
     277
     278There is, however, a bit of a chicken-and-egg problem. The [TracAdmin trac-admin] command requires an existing environment to function, but complains if the deploy directory already exists. This is a problem, because environments are often stored in a subdirectory of the deploy. The solution is to do something like this:
     279{{{#!sh
     280mkdir -p /usr/share/trac/projects/my-project
     281trac-admin /usr/share/trac/projects/my-project initenv
     282trac-admin /usr/share/trac/projects/my-project deploy /tmp/deploy
     283mv /tmp/deploy/* /usr/share/trac
     284}}}
     285Don't forget to check that the web server has the execution right on scripts in the `/usr/share/trac/cgi-bin` directory.
     286
     287==== Mapping Static Resources
     288
     289Out of the box, Trac will pass static resources such as style sheets or images through itself. For anything but a tracd only based deployment, this is far from optimal as the web server could be set up to directly serve those static resources (for CGI setup, this is '''highly undesirable''' and will cause abysmal performance).
     290
     291Web servers such as [http://httpd.apache.org/ Apache] allow you to create “Aliases” to resources, giving them a virtual URL that doesn't necessarily reflect the layout of the servers file system. We also can map requests for static resources directly to the directory on the file system, avoiding processing these requests by Trac itself.
     292
     293There are two primary URL paths for static resources - `/chrome/common` and `/chrome/site`. Plugins can add their own resources, usually accessible by `/chrome/<plugin>` path, so its important to override only known paths and not try to make universal `/chrome` alias for everything.
     294
     295Note that in order to get those static resources on the filesystem, you need first to extract the relevant resources from Trac using the TracAdmin `deploy` command:
     296[[TracAdminHelp(deploy)]]
     297
     298The target `<directory>` will then contain an `htdocs` directory with:
     299 - `site/` - a copy of the environment's directory `htdocs/`
     300 - `common/` - the static resources of Trac itself
     301 - `<plugins>/` - one directory for each resource directory managed by the plugins enabled for this environment
     302
     303===== Example: Apache and `ScriptAlias` #ScriptAlias-example
     304
     305Assuming the deployment has been done this way:
     306{{{#!sh
     307$ trac-admin /var/trac/env deploy /path/to/shared/trac
     308}}}
     309
     310Add the following snippet to Apache configuration ''before'' the `ScriptAlias` or `WSGIScriptAlias` (which map all the other requests to the Trac application), changing paths to match your deployment:
     311{{{#!apache
     312Alias /trac/chrome/common /path/to/trac/htdocs/common
     313Alias /trac/chrome/site /path/to/trac/htdocs/site
     314
     315<Directory "/path/to/www/trac/htdocs">
     316  Order allow,deny
     317  Allow from all
     318</Directory>
     319}}}
     320
     321If using mod_python, you might want to add this too (otherwise, the alias will be ignored):
     322{{{#!apache
     323<Location "/trac/chrome/common/">
     324  SetHandler None
     325</Location>
     326}}}
     327
     328Note that we mapped the `/trac` part of the URL to the `trac.*cgi` script, and the path `/trac/chrome/common` is the path you have to append to that location to intercept requests to the static resources.
     329
     330Similarly, if you have static resources in a project's `htdocs` directory (which is referenced by `/trac/chrome/site` URL in themes), you can configure Apache to serve those resources (again, put this ''before'' the `ScriptAlias` or `WSGIScriptAlias` for the .*cgi scripts, and adjust names and locations to match your installation):
     331{{{#!apache
     332Alias /trac/chrome/site /path/to/projectenv/htdocs
     333
     334<Directory "/path/to/projectenv/htdocs">
     335  Order allow,deny
     336  Allow from all
     337</Directory>
     338}}}
     339
     340Alternatively to aliasing `/trac/chrome/common`, you can tell Trac to generate direct links for those static resources (and only those), using the [[TracIni#trac-section| [trac] htdocs_location]] configuration setting:
     341{{{#!ini
     342[trac]
     343htdocs_location = http://static.example.org/trac-common/
     344}}}
     345Note that this makes it easy to have a dedicated domain serve those static resources (preferentially [http://code.google.com/speed/page-speed/docs/request.html#ServeFromCookielessDomain cookie-less]).
     346
     347Of course, you still need to make the Trac `htdocs/common` directory available through the web server at the specified URL, for example by copying (or linking) the directory into the document root of the web server:
     348{{{#!sh
     349$ ln -s /path/to/trac/htdocs/common /var/www/static.example.org/trac-common
     350}}}
     351
     352==== Setting up the Plugin Cache
     353
     354Some Python plugins need to be extracted to a cache directory. By default the cache resides in the home directory of the current user. When running Trac on a Web Server as a dedicated user (which is highly recommended) who has no home directory, this might prevent the plugins from starting. To override the cache location you can set the `PYTHON_EGG_CACHE` environment variable. Refer to your server documentation for detailed instructions on how to set environment variables.
     355
     356== Configuring Authentication
     357
     358Trac uses HTTP authentication. You'll need to configure your webserver to request authentication when the `.../login` URL is hit (the virtual path of the "login" button). Trac will automatically pick the `REMOTE_USER` variable up after you provide your credentials. Therefore, all user management goes through your web server configuration. Please consult the documentation of your web server for more info.
     359
     360The process of adding, removing, and configuring user accounts for authentication depends on the specific way you run Trac.
     361
     362Please refer to one of the following sections:
     363 * TracStandalone#UsingAuthentication if you use the standalone server, `tracd`.
     364 * [wiki:TracModWSGI#ConfiguringAuthentication TracModWSGI#ConfiguringAuthentication] if you use the Apache web server, with any of its front end: `mod_wsgi`, `mod_python`, `mod_fcgi` or `mod_fastcgi`.
     365 * TracFastCgi if you're using another web server with FCGI support (Cherokee, Lighttpd, !LiteSpeed, nginx)
     366
     367[trac:TracAuthenticationIntroduction] also contains some useful information for beginners.
     368
     369== Granting admin rights to the admin user
     370Grant admin rights to user admin:
     371{{{#!sh
     372$ trac-admin /path/to/myproject permission add admin TRAC_ADMIN
     373}}}
     374
     375This user will have an //Admin// navigation item that directs to pages for administering your Trac project.
     376
     377== Configuring Trac
     378
     379TracRepositoryAdmin provides information on configuring version control repositories for your project.
     380
     381== Using Trac
     382
     383Once you have your Trac site up and running, you should be able to create tickets, view the timeline, browse your version control repository if configured, etc.
     384
     385Keep in mind that //anonymous// (not logged in) users can by default access only a few of the features, in particular they will have a read-only access to the resources. You will need to configure authentication and grant additional [TracPermissions permissions] to authenticated users to see the full set of features.
     386
     387'' Enjoy! ''
     388
     389[trac:TracTeam The Trac Team]
     390
     391----
     392See also: [trac:TracInstallPlatforms TracInstallPlatforms], TracGuide, TracUpgrade, TracPermissions

  • wiki/pages/TracInterfaceCustomization

    r40221 r40226  
     1= Customizing the Trac Interface
     2[[TracGuideToc]]
     3[[PageOutline]]
     4
     5== Introduction
     6This page gives suggestions on how to customize the look of Trac. Topics include editing the HTML templates and CSS files, but not the program code itself. The topics show users how they can modify the look of Trac to meet their specific needs. Suggestions for changes to Trac's interface applicable to all users should be filed as tickets, not listed on this page.
     7
     8== Project Logo and Icon
     9The easiest parts of the Trac interface to customize are the logo and the site icon. Both of these can be configured with settings in [wiki:TracIni trac.ini].
     10
     11The logo or icon image should be put in a folder named "htdocs" in your project's environment folder. ''Note: in projects created with a Trac version prior to 0.9 you will need to create this folder''.
     12
     13 '''Note''': you can actually put the logo and icon anywhere on your server (as long as it's accessible through the web server), and use their absolute or server-relative URLs in the configuration.
     14
     15Now configure the appropriate section of your [wiki:TracIni trac.ini]:
     16
     17=== Logo
     18Change the `src` setting to `site/` followed by the name of your image file. The `width` and `height` settings should be modified to match your image's dimensions. The Trac chrome handler uses "`site/`" for files within the project directory `htdocs`, and "`common/`" for the common `htdocs` directory belonging to a Trac installation. Note that 'site/' is not a placeholder for your project name, it is the literal prefix that should be used. For example, if your project is named 'sandbox', and the image file is 'red_logo.gif' then the 'src' setting would be 'site/red_logo.gif', not 'sandbox/red_logo.gif'.
     19
     20{{{#!ini
     21[header_logo]
     22src = site/my_logo.gif
     23alt = My Project
     24width = 300
     25height = 100
     26}}}
     27
     28=== Icon
     29Icons are small images displayed by your web browser next to the site's URL and in the `Bookmarks` menu. Icons should be a 32x32 image in `.gif` or `.ico` format. Change the `icon` setting to `site/` followed by the name of your icon file:
     30
     31{{{#!ini
     32[project]
     33icon = site/my_icon.ico
     34}}}
     35
     36== Custom Navigation Entries
     37The new [mainnav] and [metanav] can now be used to customize the text and link used for the navigation items, or even to disable them, but not for adding new ones.
     38
     39In the following example, we rename the link to the Wiki start "Home", and hide the "!Help/Guide". We also make the "View Tickets" entry link to a specific report:
     40{{{#!ini
     41[mainnav]
     42wiki.label = Home
     43tickets.href = /report/24
     44
     45[metanav]
     46help = disabled
     47}}}
     48
     49See also TracNavigation for a more detailed explanation of the mainnav and metanav terms.
     50
     51== Site Appearance == #SiteAppearance
     52
     53Trac is using [http://genshi.edgewall.org Genshi] as the templating engine. Say you want to add a link to a custom stylesheet, and then your own header and footer. Save the following content as `site.html` inside your projects `templates/` directory (each Trac project can have their own `site.html`), eg `/path/to/env/templates/site.html`:
     54
     55{{{#!xml
     56<html xmlns="http://www.w3.org/1999/xhtml"
     57      xmlns:py="http://genshi.edgewall.org/"
     58      py:strip="">
     59
     60  <!--! Add site-specific style sheet -->
     61  <head py:match="head" py:attrs="select('@*')">
     62    ${select('*|comment()|text()')}
     63    <link rel="stylesheet" href="${href.chrome('site/style.css')}" />
     64  </head>
     65
     66  <body py:match="body" py:attrs="select('@*')">
     67    <!--! Add site-specific header -->
     68    <div id="siteheader">
     69      <!--! Place your header content here... -->
     70    </div>
     71
     72    ${select('*|text()')}
     73
     74    <!--! Add site-specific footer -->
     75    <div id="sitefooter">
     76      <!--! Place your footer content here... -->
     77    </div>
     78  </body>
     79</html>
     80}}}
     81
     82Notice that XSLT bears some similarities with Genshi templates. However, there are some Trac specific features, for example the `${href.chrome('site/style.css')}` attribute references `style.css` in the environment's `htdocs/` directory. In a similar fashion `${chrome.htdocs_location}` is used to specify the common `htdocs/` directory belonging to a Trac installation. That latter location can however be overriden using the [[TracIni#trac-section|[trac] htdocs_location]] configuration setting.
     83
     84`site.html` is one file to contain all your modifications. It usually works using the `py:match` directive (element or attribute), and it allows you to modify the page as it renders. The matches hook onto specific sections depending on what it tries to find and modify them.
     85See [http://groups.google.com/group/trac-users/browse_thread/thread/70487fb2c406c937/ this thread] for a detailed explanation of the above example `site.html`.
     86A `site.html` can contain any number of such `py:match` sections for whatever you need to modify. This is all Genshi, so the [http://genshi.edgewall.org/wiki/Documentation/xml-templates.html docs on the exact syntax] can be found there.
     87
     88Example snippet of adding introduction text to the new ticket form (but not shown during preview):
     89
     90{{{#!xml
     91<form py:match="div[@id='content' and @class='ticket']/form" py:attrs="select('@*')">
     92  <py:if test="req.environ['PATH_INFO'] == '/newticket' and (not 'preview' in req.args)">
     93    <p>Please make sure to search for existing tickets before reporting a new one!</p>
     94  </py:if>
     95  ${select('*')}
     96</form>
     97}}}
     98
     99This example illustrates a technique of using `req.environ['PATH_INFO']` to limit scope of changes to one view only. For instance, to make changes in `site.html` only for timeline and avoid modifying other sections - use  `req.environ['PATH_INFO'] == '/timeline'` condition in `<py:if>` test.
     100
     101More examples snippets for `site.html` can be found at [trac:wiki:CookBook/SiteHtml CookBook/SiteHtml].
     102
     103Example snippets for `style.css` can be found at [trac:wiki:CookBook/SiteStyleCss CookBook/SiteStyleCss].
     104
     105Note that the `site.html`, despite its name, can be put in a shared templates directory, see the [[TracIni#inherit-section|[inherit] templates_dir]] option. This could provide easier maintainence (and a migration path from 0.10 for larger installations) as one new global `site.html` file can be made to include any existing header, footer and newticket snippets.
     106
     107== Project List == #ProjectList
     108
     109You can use a custom Genshi template to display the list of projects if you are using Trac with multiple projects. 
     110
     111The following is the basic template used by Trac to display a list of links to the projects. For projects that could not be loaded, it displays an error message. You can use this as a starting point for your own index template:
     112
     113{{{#!text/html
     114<!DOCTYPE html
     115    PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
     116    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
     117<html xmlns="http://www.w3.org/1999/xhtml"
     118      xmlns:py="http://genshi.edgewall.org/"
     119      xmlns:xi="http://www.w3.org/2001/XInclude">
     120  <head>
     121    <title>Available Projects</title>
     122  </head>
     123  <body>
     124    <h1>Available Projects</h1>
     125    <ul>
     126      <li py:for="project in projects" py:choose="">
     127        <a py:when="project.href" href="$project.href"
     128           title="$project.description">$project.name</a>
     129        <py:otherwise>
     130          <small>$project.name: <em>Error</em> <br /> ($project.description)</small>
     131        </py:otherwise>
     132      </li>
     133    </ul>
     134  </body>
     135</html>
     136}}}
     137
     138Once you've created your custom template you will need to configure the webserver to tell Trac where the template is located (pls verify ... not yet changed to 0.11):
     139
     140For [wiki:TracModWSGI mod_wsgi]:
     141{{{#!python
     142os.environ['TRAC_ENV_INDEX_TEMPLATE'] = '/path/to/template.html'
     143}}}
     144
     145For [wiki:TracFastCgi FastCGI]:
     146{{{#!apache
     147FastCgiConfig -initial-env TRAC_ENV_PARENT_DIR=/parent/dir/of/projects \
     148              -initial-env TRAC_ENV_INDEX_TEMPLATE=/path/to/template
     149}}}
     150
     151For [wiki:TracModPython mod_python]:
     152{{{#!apache
     153PythonOption TracEnvParentDir /parent/dir/of/projects
     154PythonOption TracEnvIndexTemplate /path/to/template
     155}}}
     156
     157For [wiki:TracCgi CGI]:
     158{{{#!apache
     159SetEnv TRAC_ENV_INDEX_TEMPLATE /path/to/template
     160}}}
     161
     162For [wiki:TracStandalone], you'll need to set up the `TRAC_ENV_INDEX_TEMPLATE` environment variable in the shell used to launch tracd:
     163 - Unix
     164   {{{#!sh
     165$ export TRAC_ENV_INDEX_TEMPLATE=/path/to/template
     166   }}}
     167 - Windows
     168   {{{#!sh
     169$ set TRAC_ENV_INDEX_TEMPLATE=/path/to/template
     170   }}}
     171
     172== Project Templates
     173
     174The appearance of each individual Trac environment, ie instance of a project, can be customized independently of other projects, even those hosted on the same server. The recommended way is to use a `site.html` template (see [#SiteAppearance]) whenever possible. Using `site.html` means changes are made to the original templates as they are rendered, and you should not normally need to redo modifications whenever Trac is upgraded. If you do make a copy of `theme.html` or any other Trac template, you need to migrate your modifiations to the newer version. If not, new Trac features or bug fixes may not work as expected.
     175
     176With that word of caution, any Trac template may be copied and customized. The default Trac templates are located inside the installed Trac egg (`/usr/lib/pythonVERSION/site-packages/Trac-VERSION.egg/trac/templates, .../trac/ticket/templates, .../trac/wiki/templates, ...`). The [#ProjectList] template file is called `index.html`, while the template responsible for main layout is called `theme.html`. Page assets such as images and CSS style sheets are located in the egg's `trac/htdocs` directory.
     177
     178However, do not edit templates or site resources inside the Trac egg. Reinstalling Trac overwrites your modifications. Instead use one of these alternatives:
     179 * For a modification to one project only, copy the template to project `templates` directory.
     180 * For a modification shared by several projects, copy the template to a shared location and have each project point to this location using the `[inherit] templates_dir` trac.ini option.
     181
     182Trac resolves requests for a template by first looking inside the project, then in any inherited templates location, and finally inside the Trac egg.
     183
     184Trac caches templates in memory by default to improve performance. To apply a template you need to restart the web server.
     185
     186----
     187See also TracGuide, TracIni

  • wiki/pages/TracLanguages

    r40221 r40226  
     1||=Code=||=Name=||=English name=||=Language title=||
     2||Ar||العربية||Arabic||لغات أخرى||
     3||Ast||asturianu||Asturian||Otres llingües||
     4||Az||azərbaycanca||Azeri||Başqa dillərdə||
     5||Be||беларуская||Belarusian||Іншыя мовы||
     6||Bg||български||Bulgarian||Други езици||
     7||Bn||বাংলা||Bengali||অন্যান্য ভাষাসমূহ||
     8||Bs||bosanski||Bosnian||Drugim jezicima||
     9||Ca||català||Catalan||Altres llengües||
     10||Ca-Valencia||valencià||Valencian||Altres llengües||
     11||Cs||čeština||Czech||Další jazyky||
     12||Da||dansk||Danish||Andre sprog||
     13||de||Deutsch||German||Andere Sprachen||
     14||gr||Ελληνικά||Greek||Άλλες γλώσσες||
     15||en||English||(American) English||Languages||
     16||En_AU||Australian||Australian English||Languages||
     17||En_GB||British||British||Languages||
     18||Es||español||Spanish||Altres idiomas||
     19||Et||eesti||Estonian||Teistes keeltes||
     20||Eu||euskara||Basque||Beste hizkuntzak||
     21||Fa||فارسی||Persian||زبانهای دیگر||
     22||Fi||suomi||Finnish||Muilla kielillä||
     23||fr||français||French||Autres langues||
     24||Gl||galego||Galician||Outras linguas||
     25||He||עברית||Hebrew||שפות אחרות||
     26||Hi||हिन्दी||Hindi||अन्य भाषाओं||
     27||Hr||hrvatski||Croatian||Drugi jezici||
     28||Hu||magyar||Hungarian||Más nyelveken||
     29||Hy||Հայերեն||Armenian||այլ լեզուներ||
     30||Id||Bahasa Indonesia||Indonesian||Bahasa lain||
     31||Is||Íslenska||Icelandic||Á öðrum tungumálum||
     32||it||italiano||Italian||Altre lingue||
     33||Ja||日本語||Japanese||他の言語||
     34||Ka||ქართული||Georgian||სხვა ენებზე||
     35||Ko||한국어||Korean||다른 언어||
     36||Km||ភាសាខ្មែរ||Khmer||ភាសាផ្សេងទៀត||
     37||Lt||lietuvių||Lithuanian||Kitomis kalbomis||
     38||Lv||latviešu||Latvian||Pārējās valodas||
     39||Mk||македонски||Macedonian||Други јазици||
     40||Nb||norsk bokmål||Norwegian (Bokmal)||Andre språk||
     41||nl||Nederlands||Dutch||Andere talen||
     42||pl||polski||Polish||Inne języki||
     43||Pt||português||Portuguese||Outras línguas||
     44||Pt_BR||português brasileiro||Brazilian Portuguese||Outras línguas||
     45||Ro||Română||Romanian||Alte limbi||
     46||ru||русский||Russian||Другие языки||
     47||Sq||shqip||Albanian||Gjuhët e tjera||
     48||Sk||slovenčina||Slovak||Ďalšie jazyky||
     49||Sl||slovenščina||Slovenian||Drugi jeziki||
     50||Sr||српски||Serbian||Остали језици||
     51||Sv||svenska||Swedish||Andra språk||
     52||Th||ไทย||Thai||ภาษาอื่น ๆ||
     53||Tr||Türkçe||Turkish||Diğer diller||
     54||Uk||українська||Ukrainian||Інші мови||
     55||Uz||ўзбек тили||Uzbek||Boshqa tillarda||
     56||vn||Tiếng Việt||Vietnamese||Ngôn ngữ khác||
     57||Zh_CN||简体中文||Chinese (Simplified)||其他语言||
     58||Zh_TW||正體中文||Chinese (Traditional)||其他語言||

  • wiki/pages/TracLinks

    r40221 r40226  
     1= Trac Links =
     2[[TracGuideToc]]
     3
     4TracLinks are a fundamental feature of Trac, because they allow easy hyperlinking between the various entities in the system—such as tickets, reports, changesets, Wiki pages, milestones, and source files—from anywhere WikiFormatting is used.
     5
     6TracLinks are generally of the form '''type:id''' (where ''id'' represents the
     7number, name or path of the item) though some frequently used kinds of items
     8also have short-hand notations.
     9
     10== Where to use TracLinks ==
     11You can use TracLinks in:
     12
     13 * Source code (Subversion) commit messages
     14 * Wiki pages
     15 * Full descriptions for tickets, reports and milestones
     16
     17and any other text fields explicitly marked as supporting WikiFormatting.
     18
     19== Overview ==
     20
     21||= Wiki Markup =||= Display =||
     22{{{#!td
     23 Wiki pages :: `CamelCase` or `wiki:CamelCase`
     24 Parent page :: `[..]`
     25 Tickets :: `#1` or `ticket:1`
     26 Ticket comments :: `comment:1:ticket:2`
     27 Reports :: `{1}` or `report:1`
     28 Milestones :: `milestone:1.0`
     29 Attachment :: `attachment:example.tgz` (for current page attachment), `attachment:attachment.1073.diff:ticket:944` (absolute path)
     30 Changesets :: `r1`, `[1]`, `changeset:1` or (restricted) `[1/trunk]`, `changeset:1/trunk`, `[1/repository]`
     31 Revision log :: `r1:3`, `[1:3]` or `log:@1:3`, `log:trunk@1:3`, `[2:5/trunk]`
     32 Diffs :: `diff:@1:3`, `diff:plugins/0.12/mercurial-plugin@9128:9953`,
     33          `diff:tags/trac-0.9.2/wiki-default//tags/trac-0.9.3/wiki-default`
     34          or `diff:trunk/trac@3538//sandbox/vc-refactoring@3539`
     35 Files :: `source:trunk/COPYING`, `source:/trunk/COPYING@200` (at version 200), `source:/trunk/COPYING@200#L25` (at version 200, line 25)
     36}}}
     37{{{#!td
     38 Wiki pages :: CamelCase or wiki:CamelCase
     39 Parent page :: [..]
     40 Tickets :: #1 or ticket:1
     41 Ticket comments :: comment:1:ticket:2
     42 Reports :: {1} or report:1
     43 Milestones :: milestone:1.0
     44 Attachment :: attachment:example.tgz (for current page attachment), attachment:attachment.1073.diff:ticket:944 (absolute path)
     45 Changesets :: r1, [1], changeset:1 or (restricted) [1/trunk], changeset:1/trunk, [1/repository]
     46 Revision log :: r1:3, [1:3] or log:@1:3, log:trunk@1:3, [2:5/trunk]
     47 Diffs :: diff:@1:3, diff:plugins/0.12/mercurial-plugin@9128:9953,
     48          diff:tags/trac-0.9.2/wiki-default//tags/trac-0.9.3/wiki-default
     49          or diff:trunk/trac@3538//sandbox/vc-refactoring@3539
     50 Files :: source:trunk/COPYING, source:/trunk/COPYING@200 (at version 200), source:/trunk/COPYING@200#L25 (at version 200, line 25)
     51}}}
     52
     53'''Note:''' The wiki:CamelCase form is rarely used, but it can be convenient to refer to
     54pages whose names do not follow WikiPageNames rules, i.e., single words,
     55non-alphabetic characters, etc. See WikiPageNames for more about features specific
     56to links to Wiki page names.
     57
     58
     59{{{#!table class=""
     60|||| Trac links using the full (non-shorthand) notation can also be given a custom link title like this: ||
     61{{{#!td
     62{{{
     63[ticket:1 This is a link to ticket number one] or
     64[[ticket:1|This is another link to ticket number one]].
     65}}}
     66}}}
     67{{{#!td
     68[ticket:1 This is a link to ticket number one] or
     69[[ticket:1|This is another link to ticket number one]].
     70}}}
     71|--------------------------------------------------------------------------------------
     72|||| If the title is omitted, only the id (the part after the colon) is displayed:  ||
     73{{{#!td
     74{{{
     75[ticket:1] or [[ticket:2]]
     76}}}
     77}}}
     78{{{#!td
     79[ticket:1] or [[ticket:2]]
     80}}}
     81|--------------------------------------------------------------------------------------
     82|||| `wiki` is the default if the namespace part of a full link is omitted:  ||
     83{{{#!td
     84{{{
     85[SandBox the sandbox] or
     86[[SandBox|the sandbox]]
     87}}}
     88}}}
     89{{{#!td
     90[SandBox the sandbox] or
     91[[SandBox|the sandbox]]
     92}}}
     93|--------------------------------------------------------------------------------------
     94|||| The short form ''realm:target'' can also be wrapped within a <...> pair, [[br]] which allow for arbitrary characters (i.e. anything but >)  ||
     95{{{#!td
     96{{{
     97<wiki:Strange(page@!)>
     98}}}
     99}}}
     100{{{#!td
     101<wiki:Strange(page@!)>
     102}}}
     103}}}
     104
     105TracLinks are a very simple idea, but actually allow quite a complex network of information. In practice, it's very intuitive and simple to use, and we've found the "link trail" extremely helpful to better understand what's happening in a project or why a particular change was made.
     106
     107
     108== Advanced use of TracLinks ==
     109
     110=== Relative links ===
     111
     112To create a link to a [trac:SubWiki SubWiki]-page just use a '/':
     113{{{
     114 WikiPage/SubWikiPage or ./SubWikiPage
     115}}}
     116
     117To link from a [trac:SubWiki SubWiki] page to a parent, simply use a '..':
     118{{{
     119  [..] or [[..]]
     120}}}
     121  [..] or [[..]]
     122
     123To link from a [trac:SubWiki SubWiki] page to a [=#sibling sibling] page, use a '../':
     124{{{
     125  [../Sibling see next sibling] or [[../Sibling|see next sibling]]
     126}}}
     127  [../Sibling see next sibling] or [[../Sibling|see next sibling]]
     128
     129But in practice you often won't need to add the `../` prefix to link to a sibling page.
     130For resolving the location of a wiki link, it's the target page closest in the hierarchy
     131to the page where the link is written which will be selected. So for example, within
     132a sub-hierarchy, a sibling page will be targeted in preference to a toplevel page.
     133This makes it easy to copy or move pages to a sub-hierarchy by [[WikiNewPage#renaming|renaming]] without having to adapt the links.
     134
     135In order to link explicitly to a [=#toplevel toplevel] Wiki page,
     136use the `wiki:/` prefix. Be careful **not** to use the `/` prefix alone, as this corresponds to the [#Server-relativelinks] syntax and with such a link you will lack the `/wiki/` part in the resulting URL. A link such as `[../newticket]` will stay in the wiki namespace and therefore link to a sibling page.
     137
     138=== Link anchors ===
     139
     140To create a link to a specific anchor in a page, use '#':
     141{{{
     142 [#Linkanchors Link anchors] or [[#Linkanchors|Link anchors]]
     143}}}
     144  [#Linkanchors Link anchors] or [[#Linkanchors|Link anchors]]
     145
     146Hint: when you move your mouse over the title of a section, a '¶' character will be displayed. This is a link to that specific section and you can use this to copy the `#...` part inside a relative link to an anchor.
     147
     148To create a link to the first or last occurrence of a term on a page, use a ''pseudo anchor'' starting with '#/' or '#?':
     149{{{
     150 [#/Milestone first occurrence of Milestone] or
     151 [#?Milestone last occurrence of Milestone]
     152}}}
     153 [#/Milestone first occurrence of Milestone] or
     154 [#?Milestone last occurrence of Milestone]
     155This will also highlight all other matches on the linked page. By default only case sensitive matches are considered. To include case insensitive matches append '/i':
     156{{{
     157 [#/Milestone/i first occurrence of Milestone or milestone] or
     158 [#?Milestone/i last occurrence of Milestone or milestone]
     159}}}
     160 [#/Milestone/i first occurrence of Milestone or milestone] or
     161 [#?Milestone/i last occurrence of Milestone or milestone]
     162
     163''(since Trac 1.0)''
     164
     165Such anchors can be very useful for linking to specific lines in a file in the source browser:
     166{{{
     167 [trac:source:tags/trac-0.12/trac/wiki/api.py#L127 Line 127] or
     168 [trac:source:tags/trac-0.12/trac/ticket/roadmap.py#L47 Line 47]
     169}}}
     170 [trac:source:tags/trac-0.12/trac/wiki/api.py#L127 Line 127] or
     171 [trac:source:tags/trac-0.12/trac/ticket/roadmap.py#L47 Line 47]
     172(Hint: The line numbers displayed in the source browser are links to anchors on the respective lines.)
     173
     174Since such links become outdated when the file changes, it can be useful to link using a '#/' pseudo anchor instead:
     175{{{
     176 [trac:source:trunk/trac/wiki/api.py#/IWikiSyntaxProvider IWikiSyntaxProvider] or
     177 [trac:source:trunk/trac/env.py#/ISystemInfoProvider ISystemInfoProvider]
     178}}}
     179 [trac:source:trunk/trac/wiki/api.py#/IWikiSyntaxProvider IWikiSyntaxProvider] or
     180 [trac:source:trunk/trac/env.py#/ISystemInfoProvider ISystemInfoProvider]
     181
     182=== InterWiki links ===
     183
     184Other prefixes can be defined freely and made to point to resources in other Web applications. The definition of those prefixes as well as the URLs of the corresponding Web applications is defined in a special Wiki page, the InterMapTxt page. Note that while this could be used to create links to other Trac environments, there's a more specialized way to register other Trac environments which offers greater flexibility.
     185
     186=== InterTrac links ===
     187
     188This can be seen as a kind of InterWiki link specialized for targeting other Trac projects.
     189
     190Any type of Trac link can be written in one Trac environment and actually refer to resources in another Trac environment. All that is required is to prefix the Trac link with the name of the other Trac environment followed by a colon. The other Trac environment must be registered on the InterTrac page.
     191
     192A distinctive advantage of InterTrac links over InterWiki links is that the shorthand form of Trac links (e.g. `{}`, `r`, `#`) can also be used. For example if T was set as an alias for Trac, links to Trac tickets can be written #T234, links to Trac changesets can be written [trac 1508].
     193See InterTrac for the complete details.
     194
     195=== Server-relative links ===
     196
     197It is often useful to be able to link to objects in your project that
     198have no built-in Trac linking mechanism, such as static resources, `newticket`,
     199a shared `/register` page on the server, etc.
     200
     201To link to resources inside the project, use either an absolute path from the project root,
     202or a relative link from the URL of the current page (''Changed in 0.11''):
     203
     204{{{
     205[/newticket Create a new ticket] or [[//newticket|Create a new ticket]]
     206[/ home] or [[/|home]]
     207}}}
     208
     209Display: [/newticket Create a new ticket] or [[//newticket|Create a new ticket]]
     210[/ home] or [[/|home]]
     211
     212To link to another location on the server (possibly outside the project but on the same host), use the `//` prefix (''Changed in 0.11''):
     213
     214{{{
     215[//register Register Here] or [[//register|Register Here]]
     216}}}
     217
     218Display: [//register Register Here] or [[//register|Register Here]]
     219
     220=== Quoting space in TracLinks ===
     221
     222Immediately after a TracLinks prefix, targets containing space characters should
     223be enclosed in a pair of quotes or double quotes.
     224Examples:
     225 * !wiki:"The whitespace convention"
     226 * !attachment:'the file.txt' or
     227 * !attachment:"the file.txt"
     228 * !attachment:"the file.txt:ticket:123"
     229
     230Note that by using [trac:WikiCreole] style links, it's quite natural to write links containing spaces:
     231 * ![[The whitespace convention]]
     232 * ![[attachment:the file.txt]]
     233
     234=== Escaping Links ===
     235
     236To prevent parsing of a !TracLink, you can escape it by preceding it with a '!' (exclamation mark).
     237{{{
     238 !NoLinkHere.
     239 ![42] is not a link either.
     240}}}
     241
     242Display:
     243 !NoLinkHere.
     244 ![42] is not a link either.
     245
     246
     247=== Parameterized Trac links ===
     248
     249Many Trac resources have more than one way to be rendered, depending on some extra parameters. For example, a Wiki page can accept a `version` or a `format` parameter, a report can make use of dynamic variables, etc.
     250
     251Trac links can support an arbitrary set of parameters, written in the same way as they would be for the corresponding URL. Some examples:
     252 - `wiki:WikiStart?format=txt`
     253 - `ticket:1?version=1`
     254 - `[/newticket?component=module1 create a ticket for module1]`
     255 - `[/newticket?summary=Add+short+description+here create a ticket with URL with spaces]`
     256
     257
     258== TracLinks Reference ==
     259The following sections describe the individual link types in detail, as well as notes on advanced usage of links.
     260
     261=== attachment: links ===
     262
     263The link syntax for attachments is as follows:
     264 * !attachment:the_file.txt creates a link to the attachment the_file.txt of the current object
     265 * !attachment:the_file.txt:wiki:MyPage creates a link to the attachment the_file.txt of the !MyPage wiki page
     266 * !attachment:the_file.txt:ticket:753 creates a link to the attachment the_file.txt of the ticket 753
     267
     268Note that the older way, putting the filename at the end, is still supported: !attachment:ticket:753:the_file.txt.
     269
     270If you'd like to create a direct link to the content of the attached file instead of a link to the attachment page, simply use `raw-attachment:` instead of `attachment:`.
     271
     272This can be useful for pointing directly to an HTML document, for example. Note that for this use case, you'd have to allow the web browser to render the content by setting `[attachment] render_unsafe_content = yes` (see TracIni#attachment-section). Caveat: only do that in environments for which you're 100% confident you can trust the people who are able to attach files, as otherwise this would open up your site to [wikipedia:Cross-site_scripting cross-site scripting] attacks.
     273
     274See also [#export:links].
     275
     276=== comment: links ===
     277
     278When you're inside a given ticket, you can simply write e.g. !comment:3 to link to the third change comment.
     279It is possible to link to a comment of a specific ticket from anywhere using one of the following syntax:
     280 - `comment:3:ticket:123`
     281 - `ticket:123#comment:3` (note that you can't write `#123#!comment:3`!)
     282It is also possible to link to the ticket's description using one of the following syntax:
     283 - `comment:description` (within the ticket)
     284 - `comment:description:ticket:123`
     285 - `ticket:123#comment:description`
     286
     287=== htdocs: links ===
     288
     289Use `htdocs:path/to/file` to reference files in the `htdocs` directory of the Trac environment, the [TracEnvironment#DirectoryStructure web resource directory].
     290
     291=== query: links ===
     292
     293See TracQuery#UsingTracLinks and [#ticket:links].
     294
     295=== search: links ===
     296
     297See TracSearch#SearchLinks
     298
     299=== ticket: links ===
     300 ''alias:'' `bug:`
     301
     302Besides the obvious `ticket:id` form, it is also possible to specify a list of tickets or even a range of tickets instead of the `id`. This generates a link to a custom query view containing this fixed set of tickets.
     303
     304Example:
     305 - `ticket:5000-6000`
     306 - `ticket:1,150`
     307
     308=== timeline: links ===
     309
     310Links to the timeline can be created by specifying a date in the ISO:8601 format. The date can be optionally followed by a time specification. The time is interpreted as being UTC time, but if you don't want to compute the UTC time, you can specify a local time followed by your timezone offset relative to UTC.
     311
     312Examples:
     313 - `timeline:2008-01-29`
     314 - `timeline:2008-01-29T15:48`
     315 - `timeline:2008-01-29T15:48Z`
     316 - `timeline:2008-01-29T16:48+01`
     317 - `timeline:2008-01-29T16:48+0100`
     318 - `timeline:2008-01-29T16:48+01:00`
     319
     320=== wiki: links ===
     321
     322See WikiPageNames and [#QuotingspaceinTracLinks quoting space in TracLinks] above. It is possible to create a link to a specific page revision using the syntax WikiStart@1.
     323
     324=== Version Control related links ===
     325
     326It should be noted that multiple repository support works by creating a kind of virtual namespace for versioned files in which the toplevel folders correspond to the repository names. Therefore, in presence of multiple repositories, a ''/path'' specification in the syntax of links detailed below should start with the name of the repository. If omitted, the default repository is used. In case a toplevel folder of the default repository has the same name as a repository, the latter "wins". One can always access such folder by fully qualifying it (the default repository can be an alias of a named repository, or conversely, it is always possible to create an alias for the default repository, ask your Trac administrator).
     327
     328For example, `source:/trunk/COPYING` targets the path `/trunk/COPYING` in the default repository, whereas `source:/projectA/trunk/COPYING` targets the path `/trunk/COPYING` in the repository named `projectA`. This can be the same file if `'projectA'` is an alias to the default repository or if `''` (the default repository) is an alias to `'projectA'`.
     329
     330==== source: links ====
     331 ''aliases:'' `browser:`, `repos:`
     332
     333The default behavior for a `source:/some/path link` is to open the browser in that directory directory
     334if the path points to a directory or to show the latest content of the file.
     335
     336It's also possible to link directly to a specific revision of a file like this:
     337 - `source:/some/file@123` - link to the file's revision 123
     338 - `source:/some/file@head` - link explicitly to the latest revision of the file
     339
     340If the revision is specified, one can even link to a specific line number:
     341 - `source:/some/file@123#L10`
     342 - `source:/tag/0.10@head#L10`
     343
     344Finally, one can also highlight an arbitrary set of lines:
     345 - `source:/some/file@123:10-20,100,103#L99` - highlight lines 10 to 20, and lines 100 and 103, and target line 99
     346 - or without version number (the `@` is still needed): `source:/some/file@:10-20,100,103#L99`. Version can be omitted when the path is pointing to a source file that will no longer change (like `source:/tags/...`), otherwise it's better to specify which lines of //which version// of the file you're talking about
     347
     348Note that in presence of multiple repositories, the name of the repository is simply integrated in the path you specify for `source:` (e.g. `source:reponame/trunk/README`). ''(since 0.12)''
     349
     350==== export: links ====
     351
     352To force the download of a file in the repository, as opposed to displaying it in the browser, use the `export` link.  Several forms are available:
     353 * `export:/some/file` - get the HEAD revision of the specified file
     354 * `export:123:/some/file` - get revision 123 of the specified file
     355 * `export:/some/file@123` - get revision 123 of the specified file
     356
     357This can be very useful for displaying XML or HTML documentation with correct stylesheets and images, in case that has been checked in into the repository. Note that for this use case, you'd have to allow the web browser to render the content by setting `[browser] render_unsafe_content = yes` (see TracIni#browser-section), otherwise Trac will force the files to be downloaded as attachments for security concerns.
     358
     359If the path is to a directory in the repository instead of a specific file, the source browser will be used to display the directory (identical to the result of `source:/some/dir`).
     360
     361==== log: links ====
     362
     363The `log:` links are used to display revision ranges. In its simplest form, it can link to the latest revisions of the specified path, but it can also support displaying an arbitrary set of revisions.
     364 - `log:/` - the latest revisions starting at the root of the repository
     365 - `log:/trunk/tools` - the latest revisions in `trunk/tools`
     366 - `log:/trunk/tools@10000` - the revisions in `trunk/tools` starting from  revision 10000
     367 - `log:@20788,20791:20795` - list revision 20788 and the revisions from 20791 to 20795
     368 - `log:/trunk/tools@20788,20791:20795` - list revision 20788 and the revisions from 20791 to 20795 which affect the given path
     369
     370There are short forms for revision ranges as well:
     371 - `[20788,20791:20795]`
     372 - `[20788,20791:20795/trunk/tools]`
     373 - `r20791:20795` (but not `r20788,20791:20795` nor `r20791:20795/trunk`)
     374
     375Finally, note that in all of the above, a revision range can be written either as `x:y` or `x-y`.
     376
     377In the presence of multiple repositories, the name of the repository should be specified as the first part of the path, e.g. `log:repos/branches` or `[20-40/repos]`.
     378
     379----
     380See also: WikiFormatting, TracWiki, WikiPageNames, InterTrac, InterWiki
     381 

  • wiki/pages/TracLogging

    r40221 r40226  
     1= Trac Logging
     2[[TracGuideToc]]
     3
     4Trac supports logging of system messages using the standard [http://docs.python.org/library/logging.html logging module] that comes with Python.
     5
     6Logging is configured in the `[logging]` section in [wiki:TracIni#logging-section trac.ini].
     7
     8== Supported Logging Methods
     9
     10The log method is set using the `log_type` option in [wiki:TracIni#logging-section trac.ini], which takes any of the following values:
     11
     12 '''none'':: Suppress all log messages.
     13 '''file''':: Log messages to a file, specified with the `log_file` option in [wiki:TracIni#logging-section trac.ini]. Relative paths in `log_file` are resolved relative to the `log` directory of the environment.
     14 '''stderr''':: Output all log entries to console ([wiki:TracStandalone tracd] only).
     15 '''syslog''':: (UNIX) Send all log messages to the local syslogd via named pipe `/dev/log`. By default, syslog will write them to the file /var/log/messages.
     16 '''eventlog''':: (Windows) Use the system's NT Event Log for Trac logging.
     17
     18== Log Levels
     19
     20The verbosity level of logged messages can be set using the `log_level` option in [wiki:TracIni#logging-section trac.ini]. The log level defines the minimum level of urgency required for a message to be logged, and those levels are:
     21
     22 '''CRITICAL''':: Log only the most critical (typically fatal) errors.
     23 '''ERROR''':: Log failures, bugs and errors.
     24 '''WARN''':: Log warnings, non-interrupting events.
     25 '''INFO''':: Diagnostic information, log information about all processing.
     26 '''DEBUG''':: Trace messages, profiling, etc.
     27
     28Additionally, you can  enable logging of SQL statements at debug level. This is turned off by default, as it's very verbose. Set `[trac] debug_sql = yes` in TracIni to activate.
     29
     30== Log Format
     31
     32The output format for log entries can be specified through the `log_format` option in [wiki:TracIni#logging-section trac.ini]. The format is a string which can contain any of the [http://docs.python.org/library/logging.html#logrecord-attributes Python logging Formatter variables]. Additonally, the following Trac-specific variables can be used:
     33 '''$(basename)s''':: The last path component of the current environment.
     34 '''$(path)s''':: The absolute path for the current environment.
     35 '''$(project)s''':: The originating project's name.
     36
     37Note that variables are identified using a dollar sign (`$(...)s`) instead of percent sign (`%(...)s`).
     38
     39The default format is:
     40{{{#!ini
     41log_format = Trac[$(module)s] $(levelname)s: $(message)s
     42}}}
     43
     44In a multi-project environment where all logs are sent to the same place (e.g. `syslog`), it makes sense to add the project name. In this example we use `basename` since that can generally be used to identify a project:
     45{{{#!ini
     46log_format = Trac[$(basename)s:$(module)s] $(levelname)s: $(message)s
     47}}}
     48
     49----
     50See also: TracIni, TracGuide, TracEnvironment

  • wiki/pages/TracModPython

    r40221 r40226  
     1[[TracGuideToc]]
     2
     3= Trac and mod_python
     4
     5Mod_python is an [https://httpd.apache.org/ Apache] module that embeds the Python interpreter within the server, so that web-based applications in Python will run many times faster than traditional CGI and will have the ability to retain database connections.
     6Trac supports [http://www.modpython.org/ mod_python], which speeds up Trac's response times considerably, especially compared to [TracCgi CGI], and permits use of many Apache features not possible with [wiki:TracStandalone tracd]/mod_proxy.
     7
     8These instructions are for Apache 2. If you are using Apache 1.3, you may have some luck with [trac:wiki:TracModPython2.7 TracModPython2.7], but that is a deprecated setup.
     9
     10[[PageOutline(2-3,Overview,inline)]]
     11
     12== Simple configuration: single project == #Simpleconfiguration
     13
     14If you just installed mod_python, you may have to add a line to load the module in the Apache configuration:
     15{{{#!apache
     16LoadModule python_module modules/mod_python.so
     17}}}
     18
     19'''Note''': The exact path to the module depends on how the HTTPD installation is laid out.
     20
     21On Debian using apt-get:
     22{{{#!sh
     23apt-get install libapache2-mod-python libapache2-mod-python-doc
     24}}}
     25
     26Still on Debian, after you have installed mod_python, you must enable the modules in apache2, equivalent to the above Load Module directive:
     27{{{#!sh
     28a2enmod python
     29}}}
     30
     31On Fedora use, using yum:
     32{{{#!sh
     33yum install mod_python
     34}}}
     35
     36You can test your mod_python installation by adding the following to your httpd.conf. You should remove this when you are done testing for security reasons. Note: mod_python.testhandler is only available in mod_python 3.2+.
     37{{{#!apache
     38<Location /mpinfo>
     39   SetHandler mod_python
     40   PythonInterpreter main_interpreter
     41   PythonHandler mod_python.testhandler
     42   Order allow,deny
     43   Allow from all
     44</Location>
     45}}}
     46
     47A simple setup of Trac on mod_python looks like this:
     48{{{#!apache
     49<Location /projects/myproject>
     50   SetHandler mod_python
     51   PythonInterpreter main_interpreter
     52   PythonHandler trac.web.modpython_frontend
     53   PythonOption TracEnv /var/trac/myproject
     54   PythonOption TracUriRoot /projects/myproject
     55   Order allow,deny
     56   Allow from all
     57</Location>
     58}}}
     59
     60The option '''`TracUriRoot`''' may or may not be necessary in your setup. Try your configuration without it; if the URLs produced by Trac look wrong, if Trac does not seem to recognize URLs correctly, or you get an odd "No handler matched request to..." error, add the '''`TracUriRoot`''' option. You will notice that the `Location` and '''`TracUriRoot`''' have the same path.
     61
     62The options available are:
     63{{{#!apache
     64# For a single project
     65PythonOption TracEnv /var/trac/myproject
     66
     67# For multiple projects
     68PythonOption TracEnvParentDir /var/trac/myprojects
     69
     70# For the index of multiple projects
     71PythonOption TracEnvIndexTemplate /srv/www/htdocs/trac/project_list_template.html
     72
     73# A space delimitted list, with a "," between key and value pairs.
     74PythonOption TracTemplateVars key1,val1 key2,val2
     75
     76# Useful to get the date in the wanted order
     77PythonOption TracLocale en_GB.UTF8
     78
     79# See description above       
     80PythonOption TracUriRoot /projects/myproject
     81}}}
     82
     83=== Python Egg Cache
     84
     85Compressed Python eggs like Genshi are normally extracted into a directory named `.python-eggs` in the users home directory. Since Apache's home usually is not writeable, an alternate egg cache directory can be specified like this:
     86{{{#!apache
     87PythonOption PYTHON_EGG_CACHE /var/trac/myprojects/egg-cache
     88}}}
     89
     90Or you can uncompress the Genshi egg to resolve problems extracting from it.
     91
     92=== Configuring Authentication
     93
     94See corresponding section in the [wiki:TracModWSGI#ConfiguringAuthentication] page.
     95
     96== Advanced Configuration
     97
     98=== Setting the Python Egg Cache
     99
     100If the Egg Cache isn't writeable by your Web server, you'll either have to change the permissions, or point Python to a location where Apache can write. This can manifest itself as a `500 internal server error` and/or a complaint in the syslog.
     101
     102{{{#!apache
     103<Location /projects/myproject>
     104  ...
     105  PythonOption PYTHON_EGG_CACHE /tmp
     106  ...
     107</Location>
     108}}}
     109
     110=== Setting the !PythonPath
     111
     112If the Trac installation isn't installed in your Python path, you will have to tell Apache where to find the Trac mod_python handler  using the `PythonPath` directive:
     113{{{#!apache
     114<Location /projects/myproject>
     115  ...
     116  PythonPath "sys.path + ['/path/to/trac']"
     117  ...
     118</Location>
     119}}}
     120
     121Be careful about using the !PythonPath directive, and ''not'' `SetEnv PYTHONPATH`, as the latter won't work.
     122
     123=== Setting up multiple projects
     124
     125The Trac mod_python handler supports a configuration option similar to Subversion's `SvnParentPath`, called `TracEnvParentDir`:
     126{{{#!apache
     127<Location /projects>
     128  SetHandler mod_python
     129  PythonInterpreter main_interpreter
     130  PythonHandler trac.web.modpython_frontend
     131  PythonOption TracEnvParentDir /var/trac
     132  PythonOption TracUriRoot /projects
     133</Location>
     134}}}
     135
     136When you request the `/projects` URL, you will get a listing of all subdirectories of the directory you set as `TracEnvParentDir` that look like Trac environment directories. Selecting any project in the list will bring you to the corresponding Trac environment.
     137
     138If you don't want to have the subdirectory listing as your projects home page you can use a
     139{{{#!apache
     140<LocationMatch "/.+/">
     141}}}
     142
     143This will instruct Apache to use mod_python for all locations different from root while having the possibility of placing a custom home page for root in your !DocumentRoot folder.
     144
     145You can also use the same authentication realm for all of the projects using a `<LocationMatch>` directive:
     146{{{#!apache
     147<LocationMatch "/projects/[^/]+/login">
     148  AuthType Basic
     149  AuthName "Trac"
     150  AuthUserFile /var/trac/.htpasswd
     151  Require valid-user
     152</LocationMatch>
     153}}}
     154
     155=== Virtual Host Configuration
     156
     157Below is the sample configuration required to set up your Trac as a virtual server, ie when you access it at the URLs like
     158`http://trac.mycompany.com`:
     159
     160{{{#!apache
     161<VirtualHost *>
     162    DocumentRoot /var/www/myproject
     163    ServerName trac.mycompany.com
     164    <Location />
     165        SetHandler mod_python
     166        PythonInterpreter main_interpreter
     167        PythonHandler trac.web.modpython_frontend
     168        PythonOption TracEnv /var/trac/myproject
     169        PythonOption TracUriRoot /
     170    </Location>
     171    <Location /login>
     172        AuthType Basic
     173        AuthName "MyCompany Trac Server"
     174        AuthUserFile /var/trac/myproject/.htpasswd
     175        Require valid-user
     176    </Location>
     177</VirtualHost>
     178}}}
     179
     180This does not seem to work in all cases. What you can do if it does not:
     181 * Try using `<LocationMatch>` instead of `<Location>`.
     182 * `<Location />` may, in your server setup, refer to the complete host instead of simple the root of the server. This means that everything (including the login directory referenced below) will be sent to Python and authentication does not work, ie you get the infamous Authentication information missing error. If this is the case, try using a sub-directory for Trac instead of the root, ie /web/ and /web/login instead of / and /login.
     183 * Depending on apache's `NameVirtualHost` configuration, you may need to use `<VirtualHost *:80>` instead of `<VirtualHost *>`.
     184
     185For a virtual host that supports multiple projects replace `TracEnv /var/trac/myproject` with `TracEnvParentDir /var/trac`.
     186
     187'''Note''': !DocumentRoot should not point to your Trac project env. As Asmodai wrote on #trac: "suppose there's a webserver bug that allows disclosure of !DocumentRoot they could then leech the entire Trac environment".
     188
     189== Troubleshooting
     190
     191If you get server error pages, you can either check the Apache error log, or enable the `PythonDebug` option:
     192{{{#!apache
     193<Location /projects/myproject>
     194  ...
     195  PythonDebug on
     196</Location>
     197}}}
     198
     199For multiple projects, try restarting the server as well.
     200
     201=== Login Not Working
     202
     203If you've used `<Location />` directive, it will override any other directives, as well as `<Location /login>`.
     204The workaround is to use negation expression as follows (for multi project setups):
     205{{{#!apache
     206#this one for other pages
     207<Location ~ "/*(?!login)">
     208   SetHandler mod_python
     209   PythonHandler trac.web.modpython_frontend
     210   PythonOption TracEnvParentDir /projects
     211   PythonOption TracUriRoot /
     212</Location>
     213
     214#this one for login page
     215<Location ~ "/[^/]+/login">
     216   SetHandler mod_python
     217   PythonHandler trac.web.modpython_frontend
     218   PythonOption TracEnvParentDir /projects
     219   PythonOption TracUriRoot /
     220
     221   #remove these if you don't want to force SSL
     222   RewriteEngine On
     223   RewriteCond %{HTTPS} off
     224   RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI}
     225
     226   AuthType Basic
     227   AuthName "Trac"
     228   AuthUserFile /projects/.htpasswd
     229   Require valid-user
     230</Location>
     231}}}
     232
     233=== Expat-related segmentation faults === #expat
     234
     235This problem will most certainly hit you on Unix when using Python 2.4.
     236In Python 2.4, some version of [http://expat.sourceforge.net/ Expat] (an XML parser library written in C) is used and if Apache is using another version, this results in segmentation faults.
     237As Trac 0.11 is using Genshi, which will indirectly use Expat, that problem can now hit you even if everything was working fine before with Trac 0.10. This problem has not been reported for Python 2.5+, so best to upgrade.
     238
     239=== Form submission problems
     240
     241If you're experiencing problems submitting some of the forms in Trac (a common problem is that you get redirected to the start page after submission), check whether your {{{DocumentRoot}}} contains a folder or file with the same path that you mapped the mod_python handler to. For some reason, mod_python gets confused when it is mapped to a location that also matches a static resource.
     242
     243=== Problem with virtual host configuration
     244
     245If the <Location /> directive is used, setting the `DocumentRoot` may result in a ''403 (Forbidden)'' error. Either remove the `DocumentRoot` directive, or make sure that accessing the directory it points is allowed, in a corresponding `<Directory>` block.
     246
     247Using <Location /> together with `SetHandler` resulted in having everything handled by mod_python, which leads to not being able to download any CSS or images/icons. Use <Location /trac> `SetHandler None` </Location> to circumvent the problem, though this may not be the most elegant solution.
     248
     249=== Problem with zipped egg
     250
     251It's possible that your version of mod_python will not import modules from zipped eggs. If you encounter an `ImportError: No module named trac` in your Apache logs but you think everything is where it should be, this might be your problem. Look in your site-packages directory; if the Trac module appears as a ''file'' rather than a ''directory'', then this might be your problem. To rectify this, try installing Trac using the `--always-unzip` option:
     252
     253{{{#!sh
     254easy_install --always-unzip Trac-0.12b1.zip
     255}}}
     256
     257=== Using .htaccess
     258
     259Although it may seem trivial to rewrite the above configuration as a directory in your document root with a `.htaccess` file, this does not work. Apache will append a "/" to any Trac URLs, which interferes with its correct operation.
     260
     261It may be possible to work around this with mod_rewrite, but I failed to get this working. In all, it is more hassle than it is worth.
     262
     263This also works out-of-box, with following trivial config:
     264{{{#!apache
     265SetHandler mod_python
     266PythonInterpreter main_interpreter
     267PythonHandler trac.web.modpython_frontend
     268PythonOption TracEnv /system/path/to/this/directory
     269PythonOption TracUriRoot /path/on/apache
     270
     271AuthType Basic
     272AuthName "ProjectName"
     273AuthUserFile /path/to/.htpasswd
     274Require valid-user
     275}}}
     276
     277The `TracUriRoot` is obviously the path you need to enter to the browser to get to Trac, eg `domain.tld/projects/trac`.
     278
     279=== Additional .htaccess help
     280
     281If you are using the .htaccess method you may have additional problems if your Trac directory is inheriting .htaccess directives from another. This may also help to add to your .htaccess file:
     282
     283{{{#!apache
     284<IfModule mod_rewrite.c>
     285  RewriteEngine Off
     286</IfModule>
     287}}}
     288
     289=== Platform specific issues
     290==== Win32 Issues
     291
     292If you run Trac with mod_python < 3.2 on Windows, uploading attachments will '''not''' work. This problem is resolved in mod_python 3.1.4 or later, so please upgrade mod_python to fix this.
     293
     294==== OS X issues
     295
     296When using mod_python on OS X you will not be able to restart Apache using `apachectl restart`. This is apparently fixed in mod_python 3.2, so please upgrade mod_python to fix this.
     297
     298==== SELinux issues
     299
     300If Trac reports something like: `Cannot get shared lock on db.lock`, then the security context on the repository may need to be set:
     301
     302{{{#!sh
     303chcon -R -h -t httpd_sys_content_t PATH_TO_REPOSITORY
     304}}}
     305
     306See also [http://subversion.apache.org/faq.html#reposperms How do I set repository permissions correctly?]
     307
     308==== FreeBSD issues
     309
     310The FreeBSD ports have both the new and old versions of mod_python and SQLite, but earlier versions of pysqlite and mod_python won't integrate:
     311 * pysqlite requires threaded support in Python
     312 * mod_python requires a threadless install.
     313
     314Apache2 does not automatically support threads on FreeBSD. You could force thread support when running `./configure` for Apache, using `--enable-threads`, but this isn´t recommended.
     315The best option [http://modpython.org/pipermail/mod_python/2006-September/021983.html seems to be] adding to /usr/local/apache2/bin/ennvars the line:
     316
     317{{{#!sh
     318export LD_PRELOAD=/usr/lib/libc_r.so
     319}}}
     320
     321==== Fedora 7 Issues
     322
     323Make sure you install the 'python-sqlite2' package as it seems to be required for TracModPython, but not for tracd.
     324
     325=== Subversion issues
     326
     327If you get the following Trac error `Unsupported version control system "svn"` only under mod_python, though it works well on the command-line and even with TracStandalone, chances are that you forgot to add the path to the Python bindings with the [TracModPython#ConfiguringPythonPath PythonPath] directive. A better way is to add a link to the bindings in the Python `site-packages` directory, or create a `.pth` file in that directory.
     328
     329If this is not the case, it's possible that you are using Subversion libraries that are binary incompatible with the Apache ones and an incompatibility of the `apr` libraries is usually the cause. In that case, you also won't be able to use the svn modules for Apache (`mod_dav_svn`).
     330
     331You also need a recent version of `mod_python` in order to avoid a runtime error ({{{argument number 2: a 'apr_pool_t *' is expected}}}) due to the default usage of multiple sub-interpreters. Version 3.2.8 ''should'' work, though it's probably better to use the workaround described in [trac:#3371 #3371], in order to force the use of the main interpreter:
     332{{{#!apache
     333PythonInterpreter main_interpreter
     334}}}
     335
     336This is also the recommended workaround for other issues seen when using the Python bindings for Subversion within mod_python ([trac:#2611 #2611], [trac:#3455 #3455]). See in particular Graham Dumpleton's comment in [trac:comment:9:ticket:3455 #3455] explaining the issue.
     337
     338=== Page layout issues
     339
     340If the formatting of the Trac pages look weird, chances are that the style sheets governing the page layout are not handled properly by the web server. Try adding the following lines to your Apache configuration:
     341{{{#!apache
     342Alias /myproject/css "/usr/share/trac/htdocs/css"
     343<Location /myproject/css>
     344    SetHandler None
     345</Location>
     346}}}
     347
     348'''Note''': For the above configuration to have any effect it must be put after the configuration of your project root location, ie {{{<Location /myproject />}}}.
     349
     350Also, setting `PythonOptimize On` seems to mess up the page headers and footers, in addition to hiding the documentation for macros and plugins (see #Trac8956). Considering how little effect the option has, leave it `Off`.
     351
     352=== HTTPS issues
     353
     354If you want to run Trac fully under https you might find that it tries to redirect to plain http. In this case just add the following line to your Apache configuration:
     355{{{#!apache
     356<VirtualHost *>
     357    DocumentRoot /var/www/myproject
     358    ServerName trac.mycompany.com
     359    SetEnv HTTPS 1
     360    ....
     361</VirtualHost>
     362}}}
     363
     364=== Segmentation fault with php5-mhash or other php5 modules
     365
     366You may encounter segfaults (reported on Debian etch) if php5-mhash module is installed. Try to remove it to see if this solves the problem. See [http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=411487 Debian bug report].
     367
     368Some people also have troubles when using PHP5 compiled with its own third party libraries instead of system libraries. Check [http://www.djangoproject.com/documentation/modpython/#if-you-get-a-segmentation-fault Django segmentation fault].
     369
     370----
     371See also: TracGuide, TracInstall, [wiki:TracModWSGI ModWSGI], [wiki:TracFastCgi FastCGI], [trac:TracNginxRecipe]

  • wiki/pages/TracModWSGI

    r40221 r40226  
     1= Trac and mod_wsgi
     2
     3[https://github.com/GrahamDumpleton/mod_wsgi mod_wsgi] is an Apache module for running WSGI-compatible Python applications directly on top of the Apache webserver. The mod_wsgi adapter is written completely in C and provides very good performance.
     4
     5[[PageOutline(2-3,Overview,inline)]]
     6
     7== The `trac.wsgi` script
     8
     9Trac can be run on top of mod_wsgi with the help of an application script, which is just a Python file saved with a `.wsgi` extension.
     10
     11A robust and generic version of this file can be created using the `trac-admin <env> deploy <dir>` command which automatically substitutes the required paths, see TracInstall#cgi-bin. The script should be sufficient for most installations and users not wanting more information can proceed to [#Mappingrequeststothescript configuring Apache].
     12
     13If you are using Trac with multiple projects, you can specify their common parent directory using the `TRAC_ENV_PARENT_DIR` in trac.wsgi:
     14{{{#!python
     15def application(environ, start_request):
     16    # Add this to config when you have multiple projects                                             
     17    environ.setdefault('trac.env_parent_dir', '/usr/share/trac/projects') 
     18    ..
     19}}}
     20
     21=== A very basic script
     22In its simplest form, the script could be:
     23
     24{{{#!python
     25import os
     26
     27os.environ['TRAC_ENV'] = '/usr/local/trac/mysite'
     28os.environ['PYTHON_EGG_CACHE'] = '/usr/local/trac/mysite/eggs'
     29
     30import trac.web.main
     31application = trac.web.main.dispatch_request
     32}}}
     33
     34The `TRAC_ENV` variable should naturally be the directory for your Trac environment, and the `PYTHON_EGG_CACHE` should be a directory where Python can temporarily extract Python eggs. If you have several Trac environments in a directory, you can also use `TRAC_ENV_PARENT_DIR` instead of `TRAC_ENV`.
     35
     36On Windows:
     37 - If run under the user's session, the Python Egg cache can be found in `%AppData%\Roaming`, for example:
     38{{{#!python
     39os.environ['PYTHON_EGG_CACHE'] = r'C:\Users\Administrator\AppData\Roaming\Python-Eggs'
     40}}}
     41 - If run under a Window service, you should create a directory for Python Egg cache:
     42{{{#!python
     43os.environ['PYTHON_EGG_CACHE'] = r'C:\Trac-Python-Eggs'
     44}}}
     45
     46=== A more elaborate script
     47
     48If you are using multiple `.wsgi` files (for example one per Trac environment) you must ''not'' use `os.environ['TRAC_ENV']` to set the path to the Trac environment. Using this method may lead to Trac delivering the content of another Trac environment, as the variable may be filled with the path of a previously viewed Trac environment.
     49
     50To solve this problem, use the following `.wsgi` file instead:
     51{{{#!python
     52import os
     53
     54os.environ['PYTHON_EGG_CACHE'] = '/usr/local/trac/mysite/eggs'
     55
     56import trac.web.main
     57def application(environ, start_response):
     58  environ['trac.env_path'] = '/usr/local/trac/mysite'
     59  return trac.web.main.dispatch_request(environ, start_response)
     60}}}
     61
     62For clarity, you should give this file a `.wsgi` extension. You should probably put the file in its own directory, since you will expose it to Apache.
     63
     64If you have installed Trac and Python eggs in a path different from the standard one, you should add that path by adding the following code at the top of the wsgi script:
     65
     66{{{#!python
     67import site
     68site.addsitedir('/usr/local/trac/lib/python2.4/site-packages')
     69}}}
     70
     71Change it according to the path you installed the Trac libs at.
     72
     73== Mapping requests to the script
     74
     75After preparing your .wsgi script, add the following to your Apache configuration file, typically `httpd.conf`:
     76
     77{{{#!apache
     78WSGIScriptAlias /trac /usr/local/trac/mysite/apache/mysite.wsgi
     79
     80<Directory /usr/local/trac/mysite/apache>
     81    WSGIApplicationGroup %{GLOBAL}
     82    Order deny,allow
     83    Allow from all
     84</Directory>
     85}}}
     86
     87Here, the script is in a subdirectory of the Trac environment.
     88
     89If you followed the directions [TracInstall#cgi-bin Generating the Trac cgi-bin directory], your Apache configuration file should look like following:
     90
     91{{{#!apache
     92WSGIScriptAlias /trac /usr/share/trac/cgi-bin/trac.wsgi
     93
     94<Directory /usr/share/trac/cgi-bin>
     95    WSGIApplicationGroup %{GLOBAL}
     96    Order deny,allow
     97    Allow from all
     98</Directory>
     99}}}
     100
     101In order to let Apache run the script, access to the directory in which the script resides is opened up to all of Apache. Additionally, the `WSGIApplicationGroup` directive ensures that Trac is always run in the first Python interpreter created by mod_wsgi. This is necessary because the Subversion Python bindings, which are used by Trac, don't always work in other sub-interpreters and may cause requests to hang or cause Apache to crash. After adding this configuration, restart Apache, and then it should work.
     102
     103To test the setup of Apache, mod_wsgi and Python itself (ie. without involving Trac and dependencies), this simple wsgi application can be used to make sure that requests gets served (use as only content in your `.wsgi` script):
     104
     105{{{#!python
     106def application(environ, start_response):
     107        start_response('200 OK',[('Content-type','text/html')])
     108        return ['<html><body>Hello World!</body></html>']
     109}}}
     110
     111For more information about using the mod_wsgi specific directives, see the [http://code.google.com/p/modwsgi/wiki/ mod_wsgi's wiki] and more specifically the [http://code.google.com/p/modwsgi/wiki/IntegrationWithTrac IntegrationWithTrac] page.
     112
     113== Configuring Authentication
     114
     115The following sections describe different methods for setting up authentication. See also [http://httpd.apache.org/docs/2.2/howto/auth.html Authentication, Authorization and Access Control] in the Apache guide.
     116
     117=== Using Basic Authentication
     118
     119The simplest way to enable authentication with Apache is to create a password file. Use the `htpasswd` program as follows:
     120{{{#!sh
     121$ htpasswd -c /somewhere/trac.htpasswd admin
     122New password: <type password>
     123Re-type new password: <type password again>
     124Adding password for user admin
     125}}}
     126
     127After the first user, you don't need the "-c" option anymore:
     128{{{#!sh
     129$ htpasswd /somewhere/trac.htpasswd john
     130New password: <type password>
     131Re-type new password: <type password again>
     132Adding password for user john
     133}}}
     134
     135  ''See the man page for `htpasswd` for full documentation.''
     136
     137After you've created the users, you can set their permissions using TracPermissions.
     138
     139Now, you need to enable authentication against the password file in the Apache configuration:
     140{{{#!apache
     141<Location "/trac/login">
     142  AuthType Basic
     143  AuthName "Trac"
     144  AuthUserFile /somewhere/trac.htpasswd
     145  Require valid-user
     146</Location>
     147}}}
     148
     149If you are hosting multiple projects, you can use the same password file for all of them:
     150{{{#!apache
     151<LocationMatch "/trac/[^/]+/login">
     152  AuthType Basic
     153  AuthName "Trac"
     154  AuthUserFile /somewhere/trac.htpasswd
     155  Require valid-user
     156</LocationMatch>
     157}}}
     158Note that neither a file nor a directory named 'login' needs to exist.[[BR]]
     159See also the [http://httpd.apache.org/docs/2.2/mod/mod_auth_basic.html mod_auth_basic] documentation.
     160
     161=== Using Digest Authentication
     162
     163For better security, it is recommended that you either enable SSL or at least use the “digest” authentication scheme instead of “Basic”.
     164
     165You have to create your `.htpasswd` file with the `htdigest` command instead of `htpasswd`, as follows:
     166{{{#!sh
     167$ htdigest -c /somewhere/trac.htpasswd trac admin
     168}}}
     169
     170The "trac" parameter above is the "realm", and will have to be reused in the Apache configuration in the !AuthName directive:
     171
     172{{{#!apache
     173<Location "/trac/login">
     174  AuthType Digest
     175  AuthName "trac"
     176  AuthDigestDomain /trac
     177  AuthUserFile /somewhere/trac.htpasswd
     178  Require valid-user
     179</Location>
     180}}}
     181
     182For multiple environments, you can use the same `LocationMatch` as described with the previous method.
     183
     184'''Note: `Location` cannot be used inside .htaccess files, but must instead live within the main httpd.conf file. If you are on a shared server, you therefore will not be able to provide this level of granularity. '''
     185
     186Don't forget to activate the mod_auth_digest. For example, on a Debian 4.0r1 (etch) system:
     187{{{#!apache
     188  LoadModule auth_digest_module /usr/lib/apache2/modules/mod_auth_digest.so
     189}}}
     190
     191See also the [http://httpd.apache.org/docs/2.2/mod/mod_auth_digest.html mod_auth_digest] documentation.
     192
     193=== Using LDAP Authentication
     194
     195Configuration for [http://httpd.apache.org/docs/2.2/mod/mod_ldap.html mod_ldap] authentication in Apache is more involved (httpd 2.2.x and OpenLDAP: slapd 2.3.19).
     196
     1971. You need to load the following modules in Apache httpd.conf:
     198{{{#!apache
     199  LoadModule ldap_module modules/mod_ldap.so
     200  LoadModule authnz_ldap_module modules/mod_authnz_ldap.so
     201}}}
     2021. Your httpd.conf also needs to look something like:
     203{{{#!apache
     204<Location /trac/>
     205  # (if you're using it, mod_python specific settings go here)
     206  Order deny,allow
     207  Deny from all
     208  Allow from 192.168.11.0/24
     209  AuthType Basic
     210  AuthName "Trac"
     211  AuthBasicProvider "ldap"
     212  AuthLDAPURL "ldap://127.0.0.1/dc=example,dc=co,dc=ke?uid?sub?(objectClass=inetOrgPerson)"
     213  authzldapauthoritative Off
     214  Require valid-user
     215</Location>
     216}}}
     2171. You can use the LDAP interface as a way to authenticate to a Microsoft Active Directory. Use the following as your LDAP URL:
     218{{{#!apache
     219  AuthLDAPURL "ldap://directory.example.com:3268/DC=example,DC=com?sAMAccountName?sub?(objectClass=user)"
     220}}}
     221 You will also need to provide an account for Apache to use when checking credentials. As this password will be listed in plaintext in the config, you need to use an account specifically for this task:
     222{{{#!apache
     223  AuthLDAPBindDN ldap-auth-user@example.com
     224  AuthLDAPBindPassword "password"
     225}}}
     226 The whole section looks like:
     227{{{#!apache
     228<Location /trac/>
     229  # (if you're using it, mod_python specific settings go here)
     230  Order deny,allow
     231  Deny from all
     232  Allow from 192.168.11.0/24
     233  AuthType Basic
     234  AuthName "Trac"
     235  AuthBasicProvider "ldap"
     236  AuthLDAPURL "ldap://adserver.company.com:3268/DC=company,DC=com?sAMAccountName?sub?(objectClass=user)"
     237  AuthLDAPBindDN       ldap-auth-user@company.com
     238  AuthLDAPBindPassword "the_password"
     239  authzldapauthoritative Off
     240  # require valid-user
     241  Require ldap-group CN=Trac Users,CN=Users,DC=company,DC=com
     242</Location>
     243}}}
     244
     245Note 1: This is the case where the LDAP search will get around the multiple OUs, conecting to the Global Catalog Server portion of AD. Note the port is 3268, not the normal LDAP 389. The GCS is basically a "flattened" tree which allows searching for a user without knowing to which OU they belong.
     246
     247Note 2: You can also require the user be a member of a certain LDAP group, instead of just having a valid login:
     248{{{#!apache
     249  Require ldap-group CN=Trac Users,CN=Users,DC=example,DC=com
     250}}}
     251
     252See also:
     253 - [http://httpd.apache.org/docs/2.2/mod/mod_authnz_ldap.html mod_authnz_ldap], documentation for mod_authnz_ldap.   
     254 - [http://httpd.apache.org/docs/2.2/mod/mod_ldap.html mod_ldap], documentation for mod_ldap, which provides connection pooling and a shared cache.
     255 - [http://trac-hacks.org/wiki/LdapPlugin TracHacks:LdapPlugin] for storing TracPermissions in LDAP.
     256
     257=== Using SSPI Authentication
     258
     259If you are using Apache on Windows, you can use mod_auth_sspi to provide single-sign-on. Download the module from the !SourceForge [http://sourceforge.net/projects/mod-auth-sspi/ mod-auth-sspi project] and then add the following to your !VirtualHost:
     260{{{#!apache
     261<Location /trac/login>
     262  AuthType SSPI
     263  AuthName "Trac Login"
     264  SSPIAuth On
     265  SSPIAuthoritative On
     266  SSPIDomain MyLocalDomain
     267  SSPIOfferBasic On
     268  SSPIOmitDomain Off
     269  SSPIBasicPreferred On
     270  Require valid-user
     271</Location>
     272}}}
     273
     274Using the above, usernames in Trac will be of the form `DOMAIN\username`, so you may have to re-add permissions and such. If you do not want the domain to be part of the username, set `SSPIOmitDomain On` instead.
     275
     276Some common problems with SSPI authentication: [trac:#1055], [trac:#1168] and [trac:#3338].
     277
     278See also [trac:TracOnWindows/Advanced].
     279
     280=== Using Apache authentication with the Account Manager plugin's Login form ===
     281
     282To begin with, see the basic instructions for using the Account Manager plugin's [http://trac-hacks.org/wiki/AccountManagerPlugin/Modules#LoginModule Login module] and its [http://trac-hacks.org/wiki/AccountManagerPlugin/AuthStores#HttpAuthStore HttpAuthStore authentication module].
     283
     284'''Note:''' If is difficult to get !HttpAuthStore to work with WSGI when using any Account Manager version prior to acct_mgr-0.4. Upgrading is recommended.
     285
     286Here is an example (from the !HttpAuthStore link) using acct_mgr-0.4 for hosting a single project:
     287{{{#!ini
     288[components]
     289; be sure to enable the component
     290acct_mgr.http.HttpAuthStore = enabled
     291
     292[account-manager]
     293; configure the plugin to use a page that is secured with http authentication
     294authentication_url = /authFile
     295password_store = HttpAuthStore
     296}}}
     297This will generally be matched with an Apache config like:
     298{{{#!apache
     299<Location /authFile>
     300   …HTTP authentication configuration…
     301   Require valid-user
     302</Location>
     303}}}
     304Note that '''authFile''' need not exist (unless you are using Account Manager older than 0.4). See the !HttpAuthStore link above for examples where multiple Trac projects are hosted on a server.
     305
     306=== Example: Apache/mod_wsgi with Basic Authentication, Trac being at the root of a virtual host
     307
     308Per the mod_wsgi documentation linked to above, here is an example Apache configuration that:
     309 - serves the Trac instance from a virtualhost subdomain
     310 - uses Apache basic authentication for Trac authentication.
     311
     312If you want your Trac to be served from e.g. !http://trac.my-proj.my-site.org, then from the folder e.g. `/home/trac-for-my-proj`, if you used the command `trac-admin the-env initenv` to create a folder `the-env`, and you used `trac-admin the-env deploy the-deploy` to create a folder `the-deploy`, then first:
     313
     314Create the htpasswd file:
     315{{{#!sh
     316cd /home/trac-for-my-proj/the-env
     317htpasswd -c htpasswd firstuser
     318### and add more users to it as needed:
     319htpasswd htpasswd seconduser
     320}}}
     321Keep the file above your document root for security reasons.
     322
     323Create this file e.g. (ubuntu) `/etc/apache2/sites-enabled/trac.my-proj.my-site.org.conf` with the following content:
     324
     325{{{#!apache
     326<Directory /home/trac-for-my-proj/the-deploy/cgi-bin/trac.wsgi>
     327  WSGIApplicationGroup %{GLOBAL}
     328  Order deny,allow
     329  Allow from all
     330</Directory>
     331
     332<VirtualHost *:80>
     333  ServerName trac.my-proj.my-site.org
     334  DocumentRoot /home/trac-for-my-proj/the-env/htdocs/
     335  WSGIScriptAlias / /home/trac-for-my-proj/the-deploy/cgi-bin/trac.wsgi
     336  <Location '/'>
     337    AuthType Basic
     338    AuthName "Trac"
     339    AuthUserFile /home/trac-for-my-proj/the-env/htpasswd
     340    Require valid-user
     341  </Location>
     342</VirtualHost>
     343
     344}}}
     345
     346Note: for subdomains to work you would probably also need to alter `/etc/hosts` and add A-Records to your host's DNS.
     347
     348== Troubleshooting
     349
     350=== Use a recent version
     351
     352Please use either version 1.6, 2.4 or later of `mod_wsgi`. Versions prior to 2.4 in the 2.X branch have problems with some Apache configurations that use WSGI file wrapper extension. This extension is used in Trac to serve up attachments and static media files such as style sheets. If you are affected by this problem, attachments will appear to be empty and formatting of HTML pages will appear not to work due to style sheet files not loading properly. Another frequent symptom is that binary attachment downloads are truncated. See mod_wsgi tickets [http://code.google.com/p/modwsgi/issues/detail?id=100 #100] and [http://code.google.com/p/modwsgi/issues/detail?id=132 #132].
     353
     354''Note: using mod_wsgi 2.5 and Python 2.6.1 gave an Internal Server Error on my system (Apache 2.2.11 and Trac 0.11.2.1). Upgrading to Python 2.6.2 (as suggested [http://www.mail-archive.com/modwsgi@googlegroups.com/msg01917.html here]) solved this for me[[BR]]-- Graham Shanks''
     355
     356If you plan to use `mod_wsgi` in embedded mode on Windows or with the MPM worker on Linux, then you will need version 3.4 or greater. See [trac:#10675] for details.
     357
     358=== Getting Trac to work nicely with SSPI and 'Require Group'
     359
     360If you have set Trac up on Apache, Win32 and configured SSPI, but added a 'Require group' option to your apache configuration, then the SSPIOmitDomain option is probably not working. If it is not working, your usernames in Trac probably look like 'DOMAIN\user' rather than 'user'.
     361
     362This WSGI script 'fixes' that:
     363{{{#!python
     364import os
     365import trac.web.main
     366
     367os.environ['TRAC_ENV'] = '/usr/local/trac/mysite'
     368os.environ['PYTHON_EGG_CACHE'] = '/usr/local/trac/mysite/eggs'
     369
     370def application(environ, start_response):
     371    if "\\" in environ['REMOTE_USER']:
     372        environ['REMOTE_USER'] = environ['REMOTE_USER'].split("\\", 1)[1]
     373    return trac.web.main.dispatch_request(environ, start_response)
     374}}}
     375
     376=== Trac with PostgreSQL
     377
     378When using the mod_wsgi adapter with multiple Trac instances and PostgreSQL (or MySQL?) as the database, the server ''may'' create a lot of open database connections and thus PostgreSQL processes.
     379
     380A somewhat brutal workaround is to disable connection pooling in Trac. This is done by setting `poolable = False` in `trac.db.postgres_backend` on the `PostgreSQLConnection` class.
     381
     382But it is not necessary to edit the source of Trac. The following lines in `trac.wsgi` will also work:
     383
     384{{{#!python
     385import trac.db.postgres_backend
     386trac.db.postgres_backend.PostgreSQLConnection.poolable = False
     387}}}
     388
     389or
     390
     391{{{#!python
     392import trac.db.mysql_backend
     393trac.db.mysql_backend.MySQLConnection.poolable = False
     394}}}
     395
     396Now Trac drops the connection after serving a page and the connection count on the database will be kept low.
     397
     398//This is not a recommended approach though. See also the notes at the bottom of the [http://code.google.com/p/modwsgi/wiki/IntegrationWithTrac mod_wsgi's IntegrationWithTrac] wiki page.//
     399
     400=== Other resources
     401
     402For more troubleshooting tips, see also the [TracModPython#Troubleshooting mod_python troubleshooting] section, as most Apache-related issues are quite similar, plus discussion of potential [http://code.google.com/p/modwsgi/wiki/ApplicationIssues application issues] when using mod_wsgi. The wsgi page also has a [http://code.google.com/p/modwsgi/wiki/IntegrationWithTrac Integration With Trac] document.
     403
     404----
     405See also: TracGuide, TracInstall, [wiki:TracFastCgi FastCGI], [wiki:TracModPython ModPython], [trac:TracNginxRecipe TracNginxRecipe]

  • wiki/pages/TracNavigation

    r40221 r40226  
     1= Trac Navigation
     2
     3The main and meta navigation entries can be customized in some basic ways. The `[mainnav]` and `[metanav]` configuration sections can be used to customize the navigation item text and link, change the ordering of the navigation items, or even disable them.
     4
     5=== `[mainnav]` #mainnav-bar
     6`[mainnav]` corresponds to the '''main navigation bar''', the one containing entries such as ''Wiki'', ''Timeline'', ''Roadmap'', ''Browse Source'' and so on. This navigation bar is meant to access the default page of the main modules enabled in Trac that are accessible for the current user.
     7
     8
     9** [=#Example Example] **
     10
     11In the following example we rename the link to WikiStart //Home//, and make the //View Tickets// entry link to a specific report.
     12{{{#!ini
     13[mainnav]
     14wiki.label = Home
     15tickets.href = /report/24
     16}}}
     17
     18=== `[metanav]` #metanav-bar
     19`[metanav]` corresponds to the '''meta navigation bar''', by default positioned above the main navigation bar and below the ''Search'' box. It contains the ''Login'', ''Logout'', ''!Help/Guide'' etc. entries. This navigation bar is meant to access some global information about the Trac project and the current user.
     20
     21There is one special entry in the  `[metanav]` section: `logout.redirect` is the page the user sees after hitting the logout button.  The ''!Help/Guide'' link is also hidden in the following example.
     22[[comment(see also #Trac3808)]]
     23
     24** Example **
     25
     26{{{#!ini
     27[metanav]
     28help = disabled
     29logout.redirect = wiki/Logout
     30}}}
     31
     32
     33=== URL Formats
     34Possible URL formats for `.href` or `.redirect`:
     35|| '''config''' || '''redirect to''' ||
     36|| `wiki/Logout` || `/projects/env/wiki/Logout` ||
     37|| `http://hostname/` || `http://hostname/` ||
     38|| `/projects` || `/projects` ||
     39
     40
     41=== Ordering #nav-order
     42The `order` attribute specifies the order in which the navigation items are displayed. This can be particularly useful for plugins that add navigation items.
     43
     44Non-negative floating point values may be used for the `order` attribute. The navigation items will be arranged from left to right in increasing order. Navigation items without an `order` attribute are sorted alphabetically by name.
     45
     46The default values are:
     47{{{#!ini
     48[mainnav]
     49browser.order = 4
     50newticket.order = 6
     51roadmap.order = 3
     52search.order = 7
     53tickets.order = 5
     54timeline.order = 2
     55wiki.order = 1
     56
     57[metanav]
     58about.order = 5
     59help.order = 4
     60login.order = 1
     61logout.order = 2
     62prefs.order = 3
     63}}}
     64
     65=== Context Navigation #ctxtnav-bar
     66
     67Note that it is still not possible to customize the '''contextual navigation bar''', ie the one usually placed below the main navigation bar.
     68
     69----
     70See also: TracInterfaceCustomization, and the [http://trac-hacks.org/wiki/NavAddPlugin TracHacks:NavAddPlugin] or [http://trac-hacks.org/wiki/MenusPlugin TracHacks:MenusPlugin] (still needed for adding entries)

  • wiki/pages/TracNotification

    r40221 r40226  
     1= Email Notification of Ticket Changes
     2[[TracGuideToc]]
     3
     4Trac supports notification of ticket changes via email.
     5
     6Email notification is useful to keep users up-to-date on tickets/issues of interest, and also provides a convenient way to post all ticket changes to a dedicated mailing list. For example, this is how the [http://lists.edgewall.com/archive/trac-tickets/ Trac-tickets] mailing list is set up.
     7
     8Disabled by default, notification can be activated and configured in [wiki:TracIni trac.ini].
     9
     10== Receiving Notification Mails
     11When reporting a new ticket or adding a comment, enter a valid email address or your Trac username in the ''reporter'', ''assigned to/owner'' or ''cc'' field. Trac will automatically send you an email when changes are made to the ticket, depending on how notification is configured.
     12
     13=== How to use your username to receive notification mails
     14
     15To receive notification mails, you can either enter a full email address or your Trac username. To get notified with a simple username or login, you need to specify a valid email address in the ''Preferences'' page.
     16
     17Alternatively, a default domain name ('''`smtp_default_domain`''') can be set in the TracIni file, see [#ConfigurationOptions Configuration Options] below. In this case, the default domain will be appended to the username, which can be useful for an "Intranet" kind of installation.
     18
     19When using apache and mod_kerb for authentication against Kerberos / Active Directory, usernames take the form ('''`username@EXAMPLE.LOCAL`'''). To avoid this being interpreted as an email address, add the Kerberos domain to  ('''`ignore_domains`''').
     20
     21=== Ticket attachment notifications
     22
     23Since 1.0.3 Trac will send notifications when a ticket attachment is added or deleted. Usually attachment notifications will be enabled in an environment by default. To disable the attachment notifications for an environment the `TicketAttachmentNotifier` component must be disabled:
     24{{{#!ini
     25[components]
     26trac.ticket.notification.TicketAttachmentNotifier = disabled
     27}}}
     28
     29== Configuring SMTP Notification
     30
     31'''Important:''' For TracNotification to work correctly, the `[trac] base_url` option must be set in [wiki:TracIni trac.ini].
     32
     33=== Configuration Options
     34These are the available options for the `[notification]` section in trac.ini:
     35
     36[[TracIni(notification)]]
     37
     38=== Example Configuration (SMTP)
     39{{{#!ini
     40[notification]
     41smtp_enabled = true
     42smtp_server = mail.example.com
     43smtp_from = notifier@example.com
     44smtp_replyto = myproj@projects.example.com
     45smtp_always_cc = ticketmaster@example.com, theboss+myproj@example.com
     46}}}
     47
     48=== Example Configuration (`sendmail`)
     49{{{#!ini
     50[notification]
     51smtp_enabled = true
     52email_sender = SendmailEmailSender
     53sendmail_path = /usr/sbin/sendmail
     54smtp_from = notifier@example.com
     55smtp_replyto = myproj@projects.example.com
     56smtp_always_cc = ticketmaster@example.com, theboss+myproj@example.com
     57}}}
     58
     59=== Subscriber Configuration
     60The default subscriptions are configured in the `[notification-subscriber]` section in trac.ini:
     61
     62[[TracIni(notification-subscriber)]]
     63
     64Each user can override these defaults in his ''Notifications'' preferences.
     65
     66For example to unsubscribe from notifications for one's own changes and comments, the rule "Never notify: I update a ticket" should be added above other subscription rules.
     67
     68=== Customizing the e-mail subject
     69The e-mail subject can be customized with the `ticket_subject_template` option, which contains a [http://genshi.edgewall.org/wiki/Documentation/text-templates.html Genshi text template] snippet. The default value is:
     70{{{#!genshi
     71$prefix #$ticket.id: $summary
     72}}}
     73The following variables are available in the template:
     74
     75 * `env`: The project environment (see [trac:source:/trunk/trac/env.py env.py]).
     76 * `prefix`: The prefix defined in `smtp_subject_prefix`.
     77 * `summary`: The ticket summary, with the old value if the summary was edited.
     78 * `ticket`: The ticket model object (see [trac:source:/trunk/trac/ticket/model.py model.py]). Individual ticket fields can be addressed by appending the field name separated by a dot, eg `$ticket.milestone`.
     79
     80=== Customizing the e-mail content
     81
     82The notification e-mail content is generated based on `ticket_notify_email.txt` in `trac/ticket/templates`. You can add your own version of this template by adding a `ticket_notify_email.txt` to the templates directory of your environment. The default looks like this:
     83
     84{{{#!genshi
     85$ticket_body_hdr
     86$ticket_props
     87{% choose ticket.new %}\
     88{%   when True %}\
     89$ticket.description
     90{%   end %}\
     91{%   otherwise %}\
     92{%     if changes_body %}\
     93${_('Changes (by %(author)s):', author=change.author)}
     94
     95$changes_body
     96{%     end %}\
     97{%     if changes_descr %}\
     98{%       if not changes_body and not change.comment and change.author %}\
     99${_('Description changed by %(author)s:', author=change.author)}
     100{%       end %}\
     101$changes_descr
     102--
     103{%     end %}\
     104{%     if change.comment %}\
     105
     106${changes_body and _('Comment:') or _('Comment (by %(author)s):', author=change.author)}
     107
     108$change.comment
     109{%     end %}\
     110{%   end %}\
     111{% end %}\
     112
     113--
     114${_('Ticket URL: <%(link)s>', link=ticket.link)}
     115$project.name <${project.url or abs_href()}>
     116$project.descr
     117}}}
     118
     119== Sample Email
     120{{{
     121#42: testing
     122---------------------------+------------------------------------------------
     123       Id:  42             |      Status:  assigned               
     124Component:  report system  |    Modified:  Fri Apr  9 00:04:31 2004
     125 Severity:  major          |   Milestone:  0.9                     
     126 Priority:  lowest         |     Version:  0.6                     
     127    Owner:  anonymous      |    Reporter:  jonas@example.com               
     128---------------------------+------------------------------------------------
     129Changes:
     130  * component:  changeset view => search system
     131  * priority:  low => highest
     132  * owner:  jonas => anonymous
     133  * cc:  daniel@example.com =>
     134         daniel@example.com, jonas@example.com
     135  * status:  new => assigned
     136
     137Comment:
     138I'm interested too!
     139
     140--
     141Ticket URL: <http://example.com/trac/ticket/42>
     142My Project <http://myproj.example.com/>
     143}}}
     144
     145== Customizing e-mail content for MS Outlook
     146
     147MS Outlook normally presents plain text e-mails with a variable-width font, and as a result the ticket properties table will most certainly look like a mess in MS Outlook. This can be fixed with some customization of the [#Customizingthee-mailcontent e-mail template].
     148
     149Replace the following second row in the template:
     150{{{
     151$ticket_props
     152}}}
     153
     154with this (requires Python 2.6 or later):
     155{{{
     156--------------------------------------------------------------------------
     157{% with
     158   pv = [(a[0].strip(), a[1].strip()) for a in [b.split(':') for b in
     159         [c.strip() for c in
     160          ticket_props.replace('|', '\n').splitlines()[1:-1]] if ':' in b]];
     161   sel = ['Reporter', 'Owner', 'Type', 'Status', 'Priority', 'Milestone',
     162          'Component', 'Severity', 'Resolution', 'Keywords'] %}\
     163${'\n'.join('%s\t%s' % (format(p[0]+':', ' <12'), p[1]) for p in pv if p[0] in sel)}
     164{% end %}\
     165--------------------------------------------------------------------------
     166}}}
     167
     168The table of ticket properties is replaced with a list of a selection of the properties. A tab character separates the name and value in such a way that most people should find this more pleasing than the default table when using MS Outlook.
     169{{{#!div style="margin: 1em 1.75em; border:1px dotted"
     170{{{#!html
     171#42: testing<br />
     172--------------------------------------------------------------------------<br />
     173<table cellpadding=0>
     174<tr><td>Reporter:</td><td>jonas@example.com</td></tr>
     175<tr><td>Owner:</td><td>anonymous</td></tr>
     176<tr><td>Type:</td><td>defect</td></tr>
     177<tr><td>Status:</td><td>assigned</td></tr>
     178<tr><td>Priority:</td><td>lowest</td></tr>
     179<tr><td>Milestone:</td><td>0.9</td></tr>
     180<tr><td>Component:</td><td>report system</td></tr>
     181<tr><td>Severity:</td><td>major</td></tr>
     182<tr><td>Resolution:</td><td> </td></tr>
     183<tr><td>Keywords:</td><td> </td></tr>
     184</table>
     185--------------------------------------------------------------------------<br />
     186Changes:<br />
     187<br />
     188&nbsp;&nbsp;* component: &nbsp;changeset view =&gt; search system<br />
     189&nbsp;&nbsp;* priority: &nbsp;low =&gt; highest<br />
     190&nbsp;&nbsp;* owner: &nbsp;jonas =&gt; anonymous<br />
     191&nbsp;&nbsp;* cc: &nbsp;daniel@example.com =&gt;<br />
     192&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;daniel@example.com, jonas@example.com<br />
     193&nbsp;&nbsp;* status: &nbsp;new =&gt; assigned<br />
     194<br />
     195Comment:<br />
     196I'm interested too!<br />
     197<br />
     198--<br />
     199Ticket URL: &lt;http://example.com/trac/ticket/42&gt;<br />
     200My Project &lt;http://myproj.example.com/&gt;<br />
     201}}}
     202}}}
     203
     204**Important**: Only those ticket fields that are listed in `sel` are part of the HTML mail. If you have defined custom ticket fields which are to be part of the mail, then they have to be added to `sel`. Example:
     205{{{
     206   sel = ['Reporter', ..., 'Keywords', 'Custom1', 'Custom2']
     207}}}
     208
     209However, the solution is still a workaround to an automatically HTML-formatted e-mail.
     210
     211== Using GMail as the SMTP relay host
     212
     213Use the following configuration snippet:
     214{{{#!ini
     215[notification]
     216smtp_enabled = true
     217use_tls = true
     218mime_encoding = base64
     219smtp_server = smtp.gmail.com
     220smtp_port = 587
     221smtp_user = user
     222smtp_password = password
     223}}}
     224
     225where ''user'' and ''password'' match an existing GMail account, ie the ones you use to log in on [http://gmail.com].
     226
     227Alternatively, you can use `smtp_port = 25`.[[br]]
     228You should not use `smtp_port = 465`. Doing so may deadlock your ticket submission. Port 465 is reserved for the SMTPS protocol, which is not supported by Trac. See [trac:comment:2:ticket:7107 #7107] for details.
     229
     230== Troubleshooting
     231
     232If you cannot get the notification working, first make sure the log is activated and have a look at the log to find if an error message has been logged. See TracLogging for help about the log feature.
     233
     234Notification errors are not reported through the web interface, so the user who submits a change or a new ticket never gets notified about a notification failure. The Trac administrator needs to look at the log to find the error trace.
     235
     236=== ''Permission denied'' error
     237
     238Typical error message:
     239{{{#!sh
     240  ...
     241  File ".../smtplib.py", line 303, in connect
     242    raise socket.error, msg
     243  error: (13, 'Permission denied')
     244}}}
     245
     246This error usually comes from a security settings on the server: many Linux distributions do not allow the web server (Apache, ...) to post email messages to the local SMTP server.
     247
     248Many users get confused when their manual attempts to contact the SMTP server succeed:
     249{{{#!sh
     250telnet localhost 25
     251}}}
     252This is because a regular user may connect to the SMTP server, but the web server cannot:
     253{{{#!sh
     254sudo -u www-data telnet localhost 25
     255}}}
     256
     257In such a case, you need to configure your server so that the web server is authorized to post to the SMTP server. The actual settings depend on your Linux distribution and current security policy. You may find help in the Trac [trac:MailingList MailingList] archive.
     258
     259Relevant ML threads:
     260 * SELinux: http://article.gmane.org/gmane.comp.version-control.subversion.trac.general/7518
     261
     262For SELinux in Fedora 10:
     263{{{#!sh
     264$ setsebool -P httpd_can_sendmail 1
     265}}}
     266
     267=== ''Suspected spam'' error
     268
     269Some SMTP servers may reject the notification email sent by Trac.
     270
     271The default Trac configuration uses Base64 encoding to send emails to the recipients. The whole body of the email is encoded, which sometimes trigger ''false positive'' spam detection on sensitive email servers. In such an event, change the default encoding to "quoted-printable" using the `mime_encoding` option.
     272
     273Quoted printable encoding works better with languages that use one of the Latin charsets. For Asian charsets, stick with the Base64 encoding.
     274
     275----
     276See also: TracTickets, TracIni, TracGuide, [trac:TracDev/NotificationApi]

  • wiki/pages/TracPermissions

    r40221 r40226  
     1= Trac Permissions
     2[[TracGuideToc]]
     3
     4Trac uses a simple, case sensitive, permission system to control what users can and can't access.
     5
     6Permission privileges are managed using the [TracAdmin trac-admin] tool or the ''General / Permissions'' panel in the ''Admin'' tab of the web interface.
     7
     8In addition to the default permission policy described in this page, it is possible to activate additional permission policies by enabling plugins and listing them in the `[trac] permission_policies` configuration entry in the TracIni. See TracFineGrainedPermissions for more details.
     9
     10Non-authenticated users accessing the system are assigned the name "anonymous". Assign permissions to the "anonymous" user to set privileges for anonymous/guest users. The parts of Trac that a user does not have the privileges for will not be displayed in the navigation.
     11In addition to these privileges, users can be granted additional individual rights in effect when authenticated and logged into the system. All logged in users belong to the virtual group "authenticated", which inherits permissions from "anonymous".
     12
     13== Graphical Admin Tab
     14
     15To access this tab, a user must have one of the following permissions: `TRAC_ADMIN`, `PERMISSION_ADMIN`, `PERMISSION_GRANT`, `PERMISSION_REVOKE`. The permissions can be granted using the `trac-admin` command (more on `trac-admin` below):
     16{{{
     17  $ trac-admin /path/to/projenv permission add bob TRAC_ADMIN
     18}}}
     19
     20Then, the user `bob` will be able to see the Admin tab, and can then access the permissions menu. This menu will allow you to perform all the following actions, but from the browser without requiring root access to the server (just the correct permissions for your user account). '''Use at least one lowercase character in user names, as all-uppercase names are reserved for permissions.'''
     21
     22 1. [[Image(htdocs:../common/guide/admin.png)]]
     23 1. [[Image(htdocs:../common/guide/admin-permissions.png)]]
     24 1. [[Image(htdocs:../common/guide/admin-permissions-TICKET_ADMIN.png)]]
     25
     26An easy way to quickly secure a new Trac install is to run the above command on the anonymous user, install the [http://trac-hacks.org/wiki/AccountManagerPlugin AccountManagerPlugin], create a new admin account graphically and then remove the TRAC_ADMIN permission from the anonymous user.
     27
     28From the graphical admin tab, users with `PERMISSION_GRANT` will only be allowed to grant permissions that they possess, and users with `PERMISSION_REVOKE` will only be allowed to revoke permissions that they possess. For example, a user cannot grant `MILESTONE_ADMIN` unless they have `PERMISSION_GRANT` and `MILESTONE_ADMIN`, and they cannot revoke `MILESTONE_ADMIN` unless they have `PERMISSION_REVOKE` and `MILESTONE_ADMIN`. `PERMISSION_ADMIN` just grants the user both `PERMISSION_GRANT` and `PERMISSION_REVOKE`, and users with `TRAC_ADMIN` can grant or revoke any permission.
     29
     30== Available Privileges
     31
     32To enable all privileges for a user, use the `TRAC_ADMIN` permission. Having `TRAC_ADMIN` is like being `root` on a *NIX system: it will allow you to perform any operation.
     33
     34Otherwise, individual privileges can be assigned to users for the various different functional areas of Trac ('''note that the privilege names are case-sensitive'''):
     35
     36=== Repository Browser
     37
     38|| `BROWSER_VIEW` || View directory listings in the [wiki:TracBrowser repository browser] ||
     39|| `LOG_VIEW` || View revision logs of files and directories in the [wiki:TracBrowser repository browser] ||
     40|| `FILE_VIEW` || View files in the [wiki:TracBrowser repository browser] ||
     41|| `CHANGESET_VIEW` || View [wiki:TracChangeset repository check-ins] ||
     42
     43=== Ticket System
     44
     45|| `TICKET_VIEW` || View existing [wiki:TracTickets tickets] and perform [wiki:TracQuery ticket queries] ||
     46|| `TICKET_CREATE` || Create new [wiki:TracTickets tickets] ||
     47|| `TICKET_APPEND` || Add comments or attachments to [wiki:TracTickets tickets] ||
     48|| `TICKET_CHGPROP` || Modify [wiki:TracTickets ticket] properties (priority, assignment, keywords, etc.) with the following exceptions: edit description field, add/remove other users from cc field when logged in, and set email to pref ||
     49|| `TICKET_MODIFY` || Includes both `TICKET_APPEND` and `TICKET_CHGPROP`, and in addition allows resolving [wiki:TracTickets tickets]. Tickets can be assigned to users through a [TracTickets#Assign-toasDrop-DownList drop-down list] when the list of possible owners has been restricted. ||
     50|| `TICKET_EDIT_CC` || Full modify cc field ||
     51|| `TICKET_EDIT_DESCRIPTION` || Modify description field ||
     52|| `TICKET_EDIT_COMMENT` || Modify another user's comments. Any user can modify their own comments by default. ||
     53|| `TICKET_BATCH_MODIFY` || [wiki:TracBatchModify Batch modify] tickets ||
     54|| `TICKET_ADMIN` || All `TICKET_*` permissions, deletion of ticket attachments and modification of the reporter field, which grants ability to create a ticket on behalf of another user (it will appear that another user created the ticket). It also allows managing ticket properties through the web administration module. ||
     55
     56Attention: the "view tickets" button appears with the `REPORT_VIEW` permission.
     57
     58=== Roadmap
     59
     60|| `MILESTONE_VIEW` || View milestones and assign tickets to milestones. ||
     61|| `MILESTONE_CREATE` || Create a new milestone ||
     62|| `MILESTONE_MODIFY` || Modify existing milestones ||
     63|| `MILESTONE_DELETE` || Delete milestones ||
     64|| `MILESTONE_ADMIN` || All `MILESTONE_*` permissions ||
     65|| `ROADMAP_VIEW` || View the [wiki:TracRoadmap roadmap] page, is not (yet) the same as MILESTONE_VIEW, see [trac:#4292 #4292] ||
     66|| `ROADMAP_ADMIN` || to be removed with [trac:#3022 #3022], replaced by MILESTONE_ADMIN ||
     67
     68=== Reports
     69
     70|| `REPORT_VIEW` || View [wiki:TracReports reports], i.e. the "view tickets" link. ||
     71|| `REPORT_SQL_VIEW` || View the underlying SQL query of a [wiki:TracReports report] ||
     72|| `REPORT_CREATE` || Create new [wiki:TracReports reports] ||
     73|| `REPORT_MODIFY` || Modify existing [wiki:TracReports reports] ||
     74|| `REPORT_DELETE` || Delete [wiki:TracReports reports] ||
     75|| `REPORT_ADMIN` || All `REPORT_*` permissions ||
     76
     77=== Wiki System
     78
     79|| `WIKI_VIEW` || View existing [wiki:TracWiki wiki] pages ||
     80|| `WIKI_CREATE` || Create new [wiki:TracWiki wiki] pages ||
     81|| `WIKI_MODIFY` || Change [wiki:TracWiki wiki] pages ||
     82|| `WIKI_RENAME` || Rename [wiki:TracWiki wiki] pages ||
     83|| `WIKI_DELETE` || Delete [wiki:TracWiki wiki] pages and attachments ||
     84|| `WIKI_ADMIN` || All `WIKI_*` permissions, plus the management of ''readonly'' pages. ||
     85
     86=== Permissions
     87
     88|| `PERMISSION_GRANT` || add/grant a permission ||
     89|| `PERMISSION_REVOKE` || remove/revoke a permission ||
     90|| `PERMISSION_ADMIN` || All `PERMISSION_*` permissions ||
     91
     92=== Others
     93
     94|| `TIMELINE_VIEW` || View the [wiki:TracTimeline timeline] page ||
     95|| `SEARCH_VIEW` || View and execute [wiki:TracSearch search] queries ||
     96|| `CONFIG_VIEW` || Enables additional pages on ''About Trac'' that show the current configuration or the list of installed plugins ||
     97|| `EMAIL_VIEW` || Shows email addresses even if [wiki:TracIni#trac-section trac show_email_addresses] configuration option is false ||
     98
     99== Creating New Privileges
     100
     101To create custom permissions, for example to be used in a custom workflow, enable the optional [trac:ExtraPermissionsProvider tracopt.perm.config_perm_provider.ExtraPermissionsProvider] component in the "Plugins" admin panel, and add the desired permissions to the `[extra-permissions]` section in your [wiki:TracIni#extra-permissions-section trac.ini]. For more information, please refer to the documentation  on the [wiki:TracIni#extra-permissions-section TracIni] page after enabling the component.
     102
     103== Granting Privileges
     104
     105You grant privileges to users using [wiki:TracAdmin trac-admin]. The current set of privileges can be listed with the following command:
     106{{{
     107  $ trac-admin /path/to/projenv permission list
     108}}}
     109
     110This command will allow the user ''bob'' to delete reports:
     111{{{
     112  $ trac-admin /path/to/projenv permission add bob REPORT_DELETE
     113}}}
     114
     115The `permission add` command also accepts multiple privilege names:
     116{{{
     117  $ trac-admin /path/to/projenv permission add bob REPORT_DELETE WIKI_CREATE
     118}}}
     119
     120Or add all privileges:
     121{{{
     122  $ trac-admin /path/to/projenv permission add bob TRAC_ADMIN
     123}}}
     124
     125== Permission Groups
     126
     127There are two built-in groups, "authenticated" and "anonymous".
     128Any user who has not logged in is automatically in the "anonymous" group.
     129Any user who has logged in is also in the "authenticated" group.
     130The "authenticated" group inherits permissions from the "anonymous" group.
     131For example, if the "anonymous" group has permission WIKI_MODIFY,
     132it is not necessary to add the WIKI_MODIFY permission to the "authenticated" group as well.
     133
     134Custom groups may be defined that inherit permissions from the two built-in groups.
     135
     136Permissions can be grouped together to form roles such as ''developer'', ''admin'', etc.
     137{{{
     138  $ trac-admin /path/to/projenv permission add developer WIKI_ADMIN
     139  $ trac-admin /path/to/projenv permission add developer REPORT_ADMIN
     140  $ trac-admin /path/to/projenv permission add developer TICKET_MODIFY
     141  $ trac-admin /path/to/projenv permission add bob developer
     142  $ trac-admin /path/to/projenv permission add john developer
     143}}}
     144
     145Group membership can be checked by doing a {{{permission list}}} with no further arguments; the resulting output will include group memberships. '''Use at least one lowercase character in group names, as all-uppercase names are reserved for permissions'''.
     146
     147== Adding a New Group and Permissions
     148Permission groups can be created by assigning a user to a group you wish to create, then assign permissions to that group.
     149
     150The following will add ''bob'' to the new group called ''beta_testers'' and then will assign WIKI_ADMIN permissions to that group. (Thus, ''bob'' will inherit the WIKI_ADMIN permission)
     151{{{
     152   $ trac-admin /path/to/projenv permission add bob beta_testers
     153   $ trac-admin /path/to/projenv permission add beta_testers WIKI_ADMIN
     154
     155}}}
     156
     157== Removing Permissions
     158
     159Permissions can be removed using the 'remove' command. For example:
     160
     161This command will prevent the user ''bob'' from deleting reports:
     162{{{
     163  $ trac-admin /path/to/projenv permission remove bob REPORT_DELETE
     164}}}
     165
     166Just like `permission add`, this command accepts multiple privilege names.
     167
     168You can also remove all privileges for a specific user:
     169{{{
     170  $ trac-admin /path/to/projenv permission remove bob '*'
     171}}}
     172
     173Or one privilege for all users:
     174{{{
     175  $ trac-admin /path/to/projenv permission remove '*' REPORT_ADMIN
     176}}}
     177
     178== Default Permissions
     179
     180By default on a new Trac installation, the `anonymous` user will have ''view'' access to everything in Trac, but will not be able to create or modify anything.
     181On the other hand, the `authenticated` users will have the permissions to ''create and modify tickets and wiki pages''.
     182
     183'''anonymous'''
     184{{{
     185 BROWSER_VIEW
     186 CHANGESET_VIEW
     187 FILE_VIEW
     188 LOG_VIEW
     189 MILESTONE_VIEW
     190 REPORT_SQL_VIEW
     191 REPORT_VIEW
     192 ROADMAP_VIEW
     193 SEARCH_VIEW
     194 TICKET_VIEW
     195 TIMELINE_VIEW
     196 WIKI_VIEW
     197}}}
     198
     199'''authenticated'''
     200{{{
     201 TICKET_CREATE
     202 TICKET_MODIFY
     203 WIKI_CREATE
     204 WIKI_MODIFY 
     205}}}
     206----
     207See also: TracAdmin, TracGuide and TracFineGrainedPermissions

  • wiki/pages/TracPlugins

    r40221 r40226  
     1[[PageOutline(2-5,Contents,pullout)]]
     2
     3= Trac plugins
     4
     5Trac is extensible with [trac:PluginList plugins]. Plugin functionality is based on the [trac:TracDev/ComponentArchitecture component architecture], with special cases described in the [trac:TracDev/PluginDevelopment plugin development] page.
     6
     7== Plugin discovery
     8
     9From the user's point of view, a plugin is either a standalone .py file or an .egg package. Trac looks for plugins in Python's `site-packages` directory, the [TracIni#GlobalConfiguration global shared] `plugins` directory and the [TracEnvironment project environment] `plugins` directory. Components defined in globally-installed plugins must be explicitly enabled in the [[TracIni#components-section| [components] ]] section of the `trac.ini` file. Components defined in the `plugins` directory of the project environment are enabled, unless explicitly disabled in the `[components]` section of the `trac.ini` file.
     10
     11== Requirements for Trac eggs
     12
     13To use egg-based plugins in Trac, you need to have [http://peak.telecommunity.com/DevCenter/setuptools setuptools] (version >= 0.6) installed.
     14
     15To install `setuptools`, download the bootstrap module [http://peak.telecommunity.com/dist/ez_setup.py ez_setup.py] and execute it as follows:
     16
     17{{{#!sh
     18$ python ez_setup.py
     19}}}
     20
     21If the `ez_setup.py` script fails to install the setuptools release, you can download it from [pypi:setuptools PyPI] and install it manually.
     22
     23Plugins can also consist of a single `.py` file dropped directly into either the project's or the shared `plugins` directory.
     24
     25== Installing a Trac plugin
     26
     27=== For a single project
     28
     29Plugins are typically packaged as [http://peak.telecommunity.com/DevCenter/PythonEggs Python eggs]. That means they are .zip archives with the file extension `.egg`.
     30
     31If you have downloaded a source distribution of a plugin, and want to build the `.egg` file:
     32
     33 * Unpack the source. It should provide `setup.py`.
     34 * Run:
     35 {{{#!sh
     36$ python setup.py bdist_egg
     37}}}
     38
     39You should now have an *.egg file. Examine the output of running Python to find where this was created.
     40
     41Once you have the plugin archive, copy it into the `plugins` directory of the [wiki:TracEnvironment project environment]. Also, make sure that the web server has sufficient permissions to read the plugin egg. Then restart the web server. If you are running as a [wiki:TracStandalone "tracd" standalone server], restart tracd, ie kill the process and run again.
     42
     43To uninstall a plugin installed this way, remove the egg from the `plugins` directory and restart the web server.
     44
     45'''Note''': the Python version that the egg is built with ''must'' match the Python version with which Trac is run. For example, if you are running Trac under Python 2.6, but have upgraded your standalone Python to 2.7, the eggs won't be recognized.
     46
     47'''Note''': in a multi-project setup, a pool of Python interpreter instances will be dynamically allocated to projects based on need; since plugins occupy a place in Python's module system, the first version of any given plugin to be loaded will be used for all projects. In other words, you cannot use different versions of a single plugin in two projects of a multi-project setup. It may be safer to install plugins for all projects (see below), and then enable them selectively on a project-by-project basis.
     48
     49=== For all projects
     50
     51==== With an .egg file
     52
     53Some plugins, such as [trac:SpamFilter SpamFilter], are downloadable as an `.egg` file that can be installed with `easy_install` or `pip`:
     54{{{#!sh
     55$ easy_install TracSpamFilter
     56$ pip install TracSpamFilter
     57}}}
     58
     59If `easy_install` is not on your system, see the Requirements section above to install it. Windows users will need to add the `Scripts` directory of their Python installation (for example, `C:\Python27\Scripts`) to their `PATH` environment variable, or use the full path to `easy_install` (for example, `C:\Python27\Scripts\easy_install.py`). See [http://peak.telecommunity.com/DevCenter/EasyInstall#windows-notes easy_install Windows notes] for more information.
     60
     61`pip` is included in Python 2.7.9. In earlier versions of Python it can be installed through the package manager of your OS (e.g. `apt-get install python-pip`) or using the [https://pip.pypa.io/en/latest/installing.html#install-pip get_pip.py].
     62
     63If Trac reports permission errors after installing a zipped egg, and you would rather not bother providing an egg cache directory writable by the web server, you can get around it by simply unzipping the egg. Just pass `--always-unzip` to `easy_install`:
     64{{{#!sh
     65$ easy_install --always-unzip TracSpamFilter-0.4.1_r10106-py2.6.egg
     66}}}
     67You should end up with a directory having the same name as the zipped egg, complete with `.egg` extension, and containing its uncompressed contents.
     68
     69Trac also searches for plugins installed in the shared plugins directory, see TracIni#GlobalConfiguration. This is a convenient way to share the installation of plugins across several, but not all, environments.
     70
     71==== From source
     72
     73`easy_install` makes installing from source a snap. Just give it the URL to either a Subversion repository or a tarball/zip of the source:
     74{{{#!sh
     75$ easy_install http://svn.edgewall.com/repos/trac/plugins/0.12/spam-filter-captcha
     76}}}
     77
     78==== Enabling the plugin
     79
     80Unlike plugins installed per environment, you'll have to explicitly enable globally installed plugins via [wiki:TracIni trac.ini]. This also applies to plugins installed in the shared plugins directory, ie the path specified in the `[inherit] plugins_dir` configuration option.
     81
     82This is done in the `[components]` section of the configuration file `trac.ini`. For example:
     83{{{#!ini
     84[components]
     85tracspamfilter.* = enabled
     86}}}
     87
     88The name of the option is the Python package of the plugin. This should be specified in the documentation of the plugin, but can also be easily discovered by looking at the source: look for a top-level directory that contains a file named `__init__.py`.
     89
     90After installing the plugin, you must restart your web server.
     91
     92==== Uninstalling
     93
     94Neither `easy_install` nor `python setup.py` have an uninstall feature. However, it is usually trivial to remove a globally installed egg and reference:
     95
     96 1. Do `easy_install -m [plugin name]` to remove references from `$PYTHONLIB/site-packages/easy-install.pth` when the plugin installed by setuptools.
     97 1. Delete executables from `/usr/bin`, `/usr/local/bin`, or `C:\\Python*\Scripts`. To find what executables are involved, refer to the `[console-script]` section of `setup.py`.
     98 1. Delete the .egg file or folder from where it's installed, usually inside `$PYTHONLIB/site-packages/`.
     99 1. Restart the web server.
     100
     101If you are uncertain about the location of the egg file, you can try to locate it by replacing `myplugin` with whatever namespace the plugin uses (as used when enabling the plugin):
     102{{{#!pycon
     103>>> import myplugin
     104>>> print myplugin.__file__
     105/opt/local/python24/lib/site-packages/myplugin-0.4.2-py2.4.egg/myplugin/__init__.pyc
     106}}}
     107
     108== Setting up the plugin cache
     109
     110Some plugins will need to be extracted by the Python egg's runtime (`pkg_resources`), so that their contents are actual files on the file system. The directory in which they are extracted defaults to `.python-eggs` in the home directory of the current user, which may or may not be a problem. You can, however, override the default location using the `PYTHON_EGG_CACHE` environment variable.
     111
     112To do this from the Apache configuration, use the `SetEnv` directive:
     113{{{#!apache
     114SetEnv PYTHON_EGG_CACHE /path/to/dir
     115}}}
     116
     117This works whether you're using the [wiki:TracCgi CGI] or the [wiki:TracModPython mod_python] front-end. Put this directive next to where you set the path to the [wiki:TracEnvironment Trac environment], ie in the same `<Location>` block.
     118
     119For example for CGI:
     120{{{#!apache
     121 <Location /trac>
     122   SetEnv TRAC_ENV /path/to/projenv
     123   SetEnv PYTHON_EGG_CACHE /path/to/dir
     124 </Location>
     125}}}
     126
     127Or for mod_python:
     128{{{#!apache
     129 <Location /trac>
     130   SetHandler mod_python
     131   ...
     132   SetEnv PYTHON_EGG_CACHE /path/to/dir
     133 </Location>
     134}}}
     135
     136'''Note''': !SetEnv requires the `mod_env` module, which needs to be activated for Apache. In this case the !SetEnv directive can also be used in the `mod_python` Location block.
     137
     138For [wiki:TracFastCgi FastCGI], you'll need to `-initial-env` option, or whatever is provided by your web server for setting environment variables.
     139
     140'''Note''': if you already use -initial-env to set the project directory for either a single project or parent, you will need to add an additional -initial-env directive to the !FastCgiConfig directive:
     141
     142{{{#!apache
     143FastCgiConfig -initial-env TRAC_ENV=/var/lib/trac -initial-env PYTHON_EGG_CACHE=/var/lib/trac/plugin-cache
     144}}}
     145
     146=== About hook scripts
     147
     148If you have set up some Subversion hook scripts that call the Trac engine, such as the post-commit hook script provided in the `/contrib` directory, make sure you define the `PYTHON_EGG_CACHE` environment variable within these scripts as well.
     149
     150== Web-based plugin administration
     151
     152The [trac:WebAdmin] interface offers limited support for plugin configuration through the web to users with `TRAC_ADMIN` permission:
     153
     154* en/disabling installed plugins
     155* installing plugins by uploading them as eggs
     156
     157If you wish to disable the second function for security reasons, add the following to your `trac.ini` file:
     158{{{#!ini
     159[components]
     160trac.admin.web_ui.PluginAdminPanel = disabled
     161}}}
     162This disables the whole panel, so the first function will no longer be available either.
     163
     164== Troubleshooting
     165
     166=== Is setuptools properly installed?
     167
     168Try this from the command line:
     169{{{#!sh
     170$ python -c "import pkg_resources"
     171}}}
     172
     173If you get '''no output''', setuptools '''is''' installed. Otherwise, you'll need to install it before plugins will work in Trac.
     174
     175=== Did you get the correct version of the Python egg?
     176
     177Python eggs have the Python version encoded in their filename. For example, `MyPlugin-1.0-py2.5.egg` is an egg for Python 2.5, and will '''not''' be loaded if you're running a different Python version (such as 2.4 or 2.6).
     178
     179Also, verify that the egg file you downloaded is indeed a .zip archive. If you downloaded it from a Trac site, chances are you downloaded the HTML preview page instead.
     180
     181=== Is the plugin enabled?
     182
     183If you install a plugin globally, ie ''not'' inside the `plugins` directory of the Trac project environment, you must explicitly enable it in [TracIni trac.ini]. Make sure that:
     184
     185 * you actually added the necessary line(s) to the `[components]` section.
     186 * the package/module names are correct and do not contain typos.
     187 * the value is "enabled", not "enable" or "Enable".
     188 * the section name is "components", not "component".
     189
     190=== Check the permissions on the .egg file
     191
     192Trac must be able to read the .egg file.
     193
     194=== Check the log files
     195
     196Enable [wiki:TracLogging logging] and set the log level to `DEBUG`, then watch the log file for messages about loading plugins.
     197
     198=== Verify you have the proper permissions
     199
     200Some plugins require you have special permissions in order to use them. [trac:WebAdmin WebAdmin], for example, requires the user to have `TRAC_ADMIN` permissions for it to show up on the navigation bar.
     201
     202=== Is the wrong version of the plugin loading?
     203
     204If you put your plugins inside plugins directories, and certainly if you have more than one project, you need to make sure that the correct version of the plugin is loading. Here are some basic rules:
     205
     206 * Only one version of the plugin can be loaded for each running Trac server, ie each Python process. The Python namespaces and module list will be shared, and it cannot handle duplicates. Whether a plugin is `enabled` or `disabled` makes no difference.
     207 * A globally installed plugin (typically `setup.py install`) will override any version in the global or project plugins directories. A plugin from the global plugins directory will be located ''before'' any project plugins directory.
     208 * If your Trac server hosts more than one project (as with `TRAC_ENV_PARENT_DIR` setups), having two versions of a plugin in two different projects will give unpredicatable results. Only one of them will load, and the one loaded will be shared by both projects. Trac will load the first plugin found, usually from the project that receives the first request.
     209 * Having more than one version listed inside Python site-packages is fine, ie installed with `setup.py install`, because setuptools will make sure you get the version installed most recently. However, don't store more than one version inside a global or project plugins directory: neither the version number nor the installed date will matter at all. There is no way to determine which one will be located first when Trac searches the directory for plugins.
     210
     211=== If all of the above failed
     212
     213Okay, so the logs don't mention plugins, the egg is readable, the Python version is correct, ''and'' the egg has been installed globally (and is enabled in trac.ini)... and it ''still'' doesn't work or give any error messages or any other indication as to why. Hop on the [trac:IrcChannel IrcChannel] and ask away!
     214
     215----
     216See also TracGuide, [trac:PluginList plugin list], [trac:TracDev/ComponentArchitecture component architecture].

  • wiki/pages/TracQuery

    r40221 r40226  
     1= Trac Ticket Queries
     2[[TracGuideToc]]
     3
     4In addition to [wiki:TracReports reports], Trac provides support for ''custom ticket queries'', which can be used to display tickets that meet specified criteria.
     5
     6To configure and execute a custom query, switch to the ''View Tickets'' module from the navigation bar, and select the ''Custom Query'' link.
     7
     8== Filters
     9
     10When you first go to the query page, the default filter will display tickets relevant to you:
     11 * If logged in then all open tickets, it will display open tickets assigned to you.
     12 * If not logged in but you have specified a name or email address in the preferences, then it will display all open tickets where your email (or name if email not defined) is in the CC list.
     13 * If not logged in and no name/email is defined in the preferences, then all open issues are displayed.
     14
     15Current filters can be removed by clicking the button to the left with the minus sign on the label. New filters are added from the pulldown lists at the bottom corners of the filters box; 'And' conditions on the left, 'Or' conditions on the right.  Filters with either a text box or a pulldown menu of options can be added multiple times to perform an ''Or'' on the criteria.
     16
     17You can use the fields just below the filters box to group the results based on a field, or display the full description for each ticket.
     18
     19After you have edited your filters, click the ''Update'' button to refresh your results.
     20
     21== Navigating Tickets
     22
     23Clicking on one of the query results will take you to that ticket. You can navigate through the results by clicking the ''Next Ticket'' or ''Previous Ticket'' links just below the main menu bar, or click the ''Back to Query'' link to return to the query page. 
     24
     25You can safely edit any of the tickets and continue to navigate through the results using the ''!Next/Previous/Back to Query'' links after saving your results. When you return to the query ''any tickets which were edited'' will be displayed with italicized text. If one of the tickets was edited such that [[html(<span style="color: grey">it no longer matches the query criteria </span>)]], the text will also be greyed. Lastly, if '''a new ticket matching the query criteria has been created''', it will be shown in bold.
     26
     27The query results can be refreshed and cleared of these status indicators by clicking the ''Update'' button again.
     28
     29== Saving Queries
     30
     31Trac allows you to save the query as a named query accessible from the reports module. To save a query ensure that you have ''Updated'' the view and then click the ''Save query'' button displayed beneath the results.
     32You can also save references to queries in Wiki content, as described below.
     33
     34'''Note:''' one way to easily build queries like the ones below, you can build and test the queries in the Custom report module and when ready - click ''Save query''. This will build the query string for you. All you need to do is remove the extra line breaks.
     35
     36'''Note:''' you must have the '''REPORT_CREATE''' permission in order to save queries to the list of default reports. The ''Save query'' button will only appear if you are logged in as a user that has been granted this permission. If your account does not have permission to create reports, you can still use the methods below to save a query.
     37
     38=== Using TracLinks
     39
     40You may want to save some queries so that you can come back to them later. You can do this by making a link to the query from any Wiki page.
     41{{{
     42[query:status=new|assigned|reopened&version=1.0 Active tickets against 1.0]
     43}}}
     44
     45Which is displayed as:
     46  [query:status=new|assigned|reopened&version=1.0 Active tickets against 1.0]
     47
     48This uses a very simple query language to specify the criteria, see [wiki:TracQuery#QueryLanguage Query Language].
     49
     50Alternatively, you can copy the query string of a query and paste that into the Wiki link, including the leading `?` character:
     51{{{
     52[query:?status=new&status=assigned&status=reopened&group=owner Assigned tickets by owner]
     53}}}
     54
     55Which is displayed as:
     56  [query:?status=new&status=assigned&status=reopened&group=owner Assigned tickets by owner]
     57
     58=== Customizing the ''table'' format
     59
     60You can also customize the columns displayed in the table format (''format=table'') by using ''col=<field>''. You can specify multiple fields and what order they are displayed in by placing pipes (`|`) between the columns:
     61{{{
     62[[TicketQuery(max=3,status=closed,order=id,desc=1,format=table,col=resolution|summary|owner|reporter)]]
     63}}}
     64
     65This is displayed as:
     66[[TicketQuery(max=3,status=closed,order=id,desc=1,format=table,col=resolution|summary|owner|reporter)]]
     67
     68==== Full rows
     69
     70In ''table'' format you can also have full rows by using ''rows=<field>'':
     71{{{
     72[[TicketQuery(max=3,status=closed,order=id,desc=1,format=table,col=resolution|summary|owner|reporter,rows=description)]]
     73}}}
     74
     75This is displayed as:
     76[[TicketQuery(max=3,status=closed,order=id,desc=1,format=table,col=resolution|summary|owner|reporter,rows=description)]]
     77
     78== Query Language
     79
     80`query:` TracLinks and the `[[TicketQuery]]` macro both use a mini “query language” for specifying query filters. Filters are separated by ampersands (`&`). Each filter consists of the ticket field name, an operator and one or more values. More than one value are separated by a pipe (`|`), meaning that the filter matches any of the values. To include a literal `&` or `|` in a value, escape the character with a backslash (`\`).
     81
     82The available operators are:
     83|| '''`=`''' || the field content exactly matches one of the values ||
     84|| '''`~=`''' || the field content contains one or more of the values ||
     85|| '''`^=`''' || the field content starts with one of the values ||
     86|| '''`$=`''' || the field content ends with one of the values ||
     87
     88All of these operators can also be negated:
     89|| '''`!=`''' || the field content matches none of the values ||
     90|| '''`!~=`''' || the field content does not contain any of the values ||
     91|| '''`!^=`''' || the field content does not start with any of the values ||
     92|| '''`!$=`''' || the field content does not end with any of the values ||
     93
     94The date fields `created` and `modified` can be constrained by using the `=` operator and specifying a value containing two dates separated by two dots (`..`). Either end of the date range can be left empty, meaning that the corresponding end of the range is open. The date parser understands a few natural date specifications like "3 weeks ago", "last month" and "now", as well as Bugzilla-style date specifications like "1d", "2w", "3m" or "4y" for 1 day, 2 weeks, 3 months and 4 years, respectively. Spaces in date specifications can be omitted to avoid having to quote the query string.
     95|| '''`created=2007-01-01..2008-01-01`''' || query tickets created in 2007 ||
     96|| '''`created=lastmonth..thismonth`''' || query tickets created during the previous month ||
     97|| '''`modified=1weekago..`''' || query tickets that have been modified in the last week ||
     98|| '''`modified=..30daysago`''' || query tickets that have been inactive for the last 30 days ||
     99
     100----
     101See also: TracTickets, TracReports, TracGuide, TicketQuery

  • wiki/pages/TracReports

    r40221 r40226  
     1= Trac Reports =
     2[[TracGuideToc]]
     3
     4The Trac reports module provides a simple, yet powerful reporting facility
     5to present information about tickets in the Trac database.
     6
     7Rather than have its own report definition format, TracReports relies on standard SQL
     8`SELECT` statements for custom report definition.
     9
     10  '''Note:''' ''The report module is being phased out in its current form because it seriously limits the ability of the Trac team to make adjustments to the underlying database schema. We believe that the [wiki:TracQuery query module] is a good replacement that provides more flexibility and better usability. While there are certain reports that cannot yet be handled by the query module, we intend to further enhance it so that at some point the reports module can be completely removed. This also means that there will be no major enhancements to the report module anymore.''
     11
     12  ''You can already completely replace the reports module by the query module simply by disabling the former in [wiki:TracIni trac.ini]:''
     13  {{{
     14  [components]
     15  trac.ticket.report.* = disabled
     16  }}}
     17  ''This will make the query module the default handler for the “View Tickets” navigation item. We encourage you to try this configuration and report back what kind of features of reports you are missing, if any.''
     18
     19A report consists of these basic parts:
     20 * '''ID''' — Unique (sequential) identifier
     21 * '''Title''' — Descriptive title
     22 * '''Description''' — A brief description of the report, in WikiFormatting text.
     23 * '''Report Body''' — List of results from report query, formatted according to the methods described below.
     24 * '''Footer''' — Links to alternative download formats for this report.
     25
     26== Changing Sort Order ==
     27Simple reports - ungrouped reports to be specific - can be changed to be sorted by any column simply by clicking the column header.
     28
     29If a column header is a hyperlink (red), click the column you would like to sort by. Clicking the same header again reverses the order.
     30
     31== Changing Report Numbering ==
     32There may be instances where you need to change the ID of the report, perhaps to organize the reports better. At present this requires changes to the trac database. The ''report'' table has the following schema:
     33 * id integer PRIMARY KEY
     34 * author text
     35 * title text
     36 * query text
     37 * description text
     38Changing the ID changes the shown order and number in the ''Available Reports'' list and the report's perma-link. This is done by running something like:
     39{{{
     40update report set id=5 where id=3;
     41}}}
     42Keep in mind that the integrity has to be maintained (i.e., ID has to be unique, and you don't want to exceed the max, since that's managed by SQLite someplace).
     43
     44You may also need to update or remove the report number stored in the report or query.
     45
     46== Navigating Tickets ==
     47Clicking on one of the report results will take you to that ticket. You can navigate through the results by clicking the ''Next Ticket'' or ''Previous Ticket'' links just below the main menu bar, or click the ''Back to Report'' link to return to the report page.
     48
     49You can safely edit any of the tickets and continue to navigate through the results using the ''!Next/Previous/Back to Report'' links after saving your results, but when you return to the report, there will be no hint about what has changed, as would happen if you were navigating a list of tickets obtained from a query (see TracQuery#NavigatingTickets).
     50
     51== Alternative Download Formats ==
     52Aside from the default HTML view, reports can also be exported in a number of alternative formats.
     53At the bottom of the report page, you will find a list of available data formats. Click the desired link to
     54download the alternative report format.
     55
     56=== Comma-delimited - CSV (Comma Separated Values) ===
     57Export the report as plain text, each row on its own line, columns separated by a single comma (',').
     58'''Note:''' The output is fully escaped so carriage returns, line feeds, and commas will be preserved in the output.
     59
     60=== Tab-delimited ===
     61Like above, but uses tabs (\t) instead of comma.
     62
     63=== RSS - XML Content Syndication ===
     64All reports support syndication using XML/RSS 2.0. To subscribe to an RSS feed, click the orange 'XML' icon at the bottom of the page. See TracRss for general information on RSS support in Trac.
     65
     66----
     67
     68== Creating Custom Reports ==
     69
     70''Creating a custom report requires a comfortable knowledge of SQL.''
     71
     72'''Note that you need to set up [TracPermissions#Reports permissions] in order to see the buttons for adding or editing reports.'''
     73
     74A report is basically a single named SQL query, executed and presented by
     75Trac.  Reports can be viewed and created from a custom SQL expression directly
     76in the web interface.
     77
     78Typically, a report consists of a SELECT-expression from the 'ticket' table,
     79using the available columns and sorting the way you want it.
     80
     81== Ticket columns ==
     82The ''ticket'' table has the following columns:
     83 * id
     84 * type
     85 * time
     86 * changetime
     87 * component
     88 * severity 
     89 * priority
     90 * owner
     91 * reporter
     92 * cc
     93 * version
     94 * milestone
     95 * status
     96 * resolution
     97 * summary
     98 * description
     99 * keywords
     100
     101See TracTickets for a detailed description of the column fields.
     102
     103Example: '''All active tickets, sorted by priority and time'''
     104{{{
     105SELECT id AS ticket, status, severity, priority, owner,
     106       time AS created, summary FROM ticket
     107  WHERE status IN ('new', 'assigned', 'reopened')
     108  ORDER BY priority, time
     109}}}
     110
     111Dynamic variables can also be used in the report title and description (since 1.1.1).
     112
     113== Advanced Reports: Dynamic Variables ==
     114For more flexible reports, Trac supports the use of ''dynamic variables'' in report SQL statements.
     115In short, dynamic variables are ''special'' strings that are replaced by custom data before query execution.
     116
     117=== Using Variables in a Query ===
     118The syntax for dynamic variables is simple, any upper case word beginning with '$' is considered a variable.
     119
     120Example:
     121{{{
     122SELECT id AS ticket,summary FROM ticket WHERE priority=$PRIORITY
     123}}}
     124
     125To assign a value to $PRIORITY when viewing the report, you must define it as an argument in the report URL, leaving out the leading '$'.
     126
     127Example:
     128{{{
     129 http://trac.edgewall.org/reports/14?PRIORITY=high
     130}}}
     131
     132To use multiple variables, separate them with an '&'.
     133
     134Example:
     135{{{
     136 http://trac.edgewall.org/reports/14?PRIORITY=high&SEVERITY=critical
     137}}}
     138
     139
     140=== !Special/Constant Variables ===
     141There is one dynamic variable whose value is set automatically (the URL does not have to be changed) to allow practical reports.
     142
     143 * $USER — Username of logged in user.
     144
     145Example (''List all tickets assigned to me''):
     146{{{
     147SELECT id AS ticket,summary FROM ticket WHERE owner=$USER
     148}}}
     149
     150
     151
     152== Advanced Reports: Custom Formatting ==
     153Trac is also capable of more advanced reports, including custom layouts,
     154result grouping and user-defined CSS styles. To create such reports, we'll use
     155specialized SQL statements to control the output of the Trac report engine.
     156
     157=== Special Columns ===
     158To format reports, TracReports looks for 'magic' column names in the query
     159result. These 'magic' names are processed and affect the layout and style of the
     160final report.
     161
     162=== Automatically formatted columns ===
     163 * '''ticket''' — Ticket ID number. Becomes a hyperlink to that ticket.
     164 * '''id''' — same as '''ticket''' above when '''realm''' is not set
     165 * '''realm''' — together with '''id''', can be used to create links to other resources than tickets (e.g. a realm of ''wiki'' and an ''id'' to a page name will create a link to that wiki page)
     166   - for some kind of resources, it may be necessary to specify their ''parent'' resources (e.g. for ''changeset'', which ''repos'') and this can be achieved using the '''parent_realm''' and '''parent_id''' columns
     167 * '''created, modified, date, time''' — Format cell as a date and/or time.
     168 * '''description''' — Ticket description field, parsed through the wiki engine.
     169
     170'''Example:'''
     171{{{
     172SELECT id AS ticket, created, status, summary FROM ticket
     173}}}
     174
     175Those columns can also be defined but marked as hidden, see [#column-syntax below].
     176
     177See trac:wiki/CookBook/Configuration/Reports for some example of creating reports for realms other than ''ticket''.
     178
     179=== Custom formatting columns ===
     180Columns whose names begin and end with 2 underscores (Example: '''`__color__`''') are
     181assumed to be ''formatting hints'', affecting the appearance of the row.
     182 
     183 * '''`__group__`''' — Group results based on values in this column. Each group will have its own header and table.
     184 * '''`__grouplink__`''' — Make the header of each group a link to the specified URL. The URL is taken from the first row of each group.
     185 * '''`__color__`''' — Should be a numeric value ranging from 1 to 5 to select a pre-defined row color. Typically used to color rows by issue priority.
     186{{{
     187#!html
     188<div style="margin-left:7.5em">Defaults:
     189<span style="border: none; color: #333; background: transparent;  font-size: 85%; background: #fdc; border-color: #e88; color: #a22">Color 1</span>
     190<span style="border: none; color: #333; background: transparent;  font-size: 85%; background: #ffb; border-color: #eea; color: #880">Color 2</span>
     191<span style="border: none; color: #333; background: transparent;  font-size: 85%; background: #fbfbfb; border-color: #ddd; color: #444">Color 3</span>
     192<span style="border: none; color: #333; background: transparent; font-size: 85%; background: #e7ffff; border-color: #cee; color: #099">Color 4</span>
     193<span style="border: none; color: #333; background: transparent;  font-size: 85%; background: #e7eeff; border-color: #cde; color: #469">Color 5</span>
     194</div>
     195}}}
     196 * '''`__style__`''' — A custom CSS style expression to use on the `<tr>` element of the current row.
     197 * '''`__class__`''' — Zero or more space-separated CSS class names to be set on the `<tr>` element of the current row. These classes are added to the class name derived from `__color__` and the odd / even indicator.
     198
     199'''Example:''' ''List active tickets, grouped by milestone, group header linked to milestone page, colored by priority''
     200{{{
     201SELECT p.value AS __color__,
     202     t.milestone AS __group__,
     203     '../milestone/' || t.milestone AS __grouplink__,
     204     (CASE owner WHEN 'daniel' THEN 'font-weight: bold; background: red;' ELSE '' END) AS __style__,
     205       t.id AS ticket, summary
     206  FROM ticket t,enum p
     207  WHERE t.status IN ('new', 'assigned', 'reopened')
     208    AND p.name=t.priority AND p.type='priority'
     209  ORDER BY t.milestone, p.value, t.severity, t.time
     210}}}
     211
     212'''Note:''' A table join is used to match ''ticket'' priorities with their
     213numeric representation from the ''enum'' table.
     214
     215=== Changing layout of report rows === #column-syntax
     216By default, all columns on each row are display on a single row in the HTML
     217report, possibly formatted according to the descriptions above. However, it's
     218also possible to create multi-line report entries.
     219
     220 * '''`column_`''' — ''Break row after this''. By appending an underscore ('_') to the column name, the remaining columns will be continued on a second line.
     221
     222 * '''`_column_`''' — ''Full row''. By adding an underscore ('_') both at the beginning and the end of a column name, the data will be shown on a separate row.
     223
     224 * '''`_column`''' — ''Hide data''. Prepending an underscore ('_') to a column name instructs Trac to hide the contents from the HTML output. This is useful for information to be visible only if downloaded in other formats (like CSV or RSS/XML).
     225   This can be used to hide any kind of column, even important ones required for identifying the resource, e.g. `id as _id` will hide the '''Id''' column but the link to the ticket will be present.
     226
     227'''Example:''' ''List active tickets, grouped by milestone, colored by priority, with  description and multi-line layout''
     228
     229{{{
     230SELECT p.value AS __color__,
     231       t.milestone AS __group__,
     232       (CASE owner
     233          WHEN 'daniel' THEN 'font-weight: bold; background: red;'
     234          ELSE '' END) AS __style__,
     235       t.id AS ticket, summary AS summary_,             -- ## Break line here
     236       component,version, severity, milestone, status, owner,
     237       time AS created, changetime AS modified,         -- ## Dates are formatted
     238       description AS _description_,                    -- ## Uses a full row
     239       changetime AS _changetime, reporter AS _reporter -- ## Hidden from HTML output
     240  FROM ticket t,enum p
     241  WHERE t.status IN ('new', 'assigned', 'reopened')
     242    AND p.name=t.priority AND p.type='priority'
     243  ORDER BY t.milestone, p.value, t.severity, t.time
     244}}}
     245
     246=== Reporting on custom fields ===
     247
     248If you have added custom fields to your tickets (see TracTicketsCustomFields), you can write a SQL query to cover them. You'll need to make a join on the ticket_custom table, but this isn't especially easy.
     249
     250If you have tickets in the database ''before'' you declare the extra fields in trac.ini, there will be no associated data in the ticket_custom table. To get around this, use SQL's "LEFT OUTER JOIN" clauses. See [trac:TracIniReportCustomFieldSample TracIniReportCustomFieldSample] for some examples.
     251
     252=== A note about SQL rewriting #rewriting
     253
     254Beyond the relatively trivial replacement of dynamic variables, the SQL query is also altered in order to support two features of the reports:
     255 1. [#sort-order changing the sort order]
     256 2. pagination support (limitation of the number of result rows displayed on each page)
     257In order to support the first feature, the sort column is inserted in the `ORDER BY` clause in the first position or in the second position if a `__group__` column is specified (an `ORDER BY` clause is created if needed). In order to support pagination, a `LIMIT ... OFFSET ...` clause is appended.
     258The query might be too complex for the automatic rewrite to work correctly, resulting in an erroneous query. In this case you still have the possibility to control exactly how the rewrite is done by manually inserting the following tokens:
     259 - `@SORT_COLUMN@`, the place where the name of the selected sort column will be inserted,
     260 - `@LIMIT_OFFSET@`, the place where the pagination support clause will be added
     261Note that if you write them after an SQL comment, `--`, you'll effectively disable rewriting if this is what you want!
     262
     263Let's take an example, consider the following SQL query:
     264{{{
     265-- ## 4: Assigned, Active Tickets by Owner ## --
     266
     267--
     268-- List assigned tickets, group by ticket owner, sorted by priority.
     269--
     270
     271SELECT p.value AS __color__,
     272   owner AS __group__,
     273   id AS ticket, summary, component, milestone, t.type AS type, severity, time AS created,
     274   changetime AS _changetime, description AS _description,
     275   reporter AS _reporter
     276  FROM ticket t,enum p
     277  WHERE status = 'assigned'
     278AND p.name=t.priority AND p.type='priority'
     279  ORDER BY __group__, p.value, severity, time
     280}}}
     281
     282The automatic rewrite will be the following (4 rows per page, page 2, sorted by `component`):
     283{{{
     284SELECT p.value AS __color__,
     285   owner AS __group__,
     286   id AS ticket, summary, component, milestone, t.type AS type, severity, time AS created,
     287   changetime AS _changetime, description AS _description,
     288   reporter AS _reporter
     289  FROM ticket t,enum p
     290  WHERE status = 'assigned'
     291AND p.name=t.priority AND p.type='priority'
     292  ORDER BY __group__ ASC, `component` ASC,  __group__, p.value, severity, time
     293 LIMIT 4 OFFSET 4
     294}}}
     295
     296The equivalent SQL query with the rewrite tokens would have been:
     297{{{
     298SELECT p.value AS __color__,
     299   owner AS __group__,
     300   id AS ticket, summary, component, milestone, t.type AS type, severity, time AS created,
     301   changetime AS _changetime, description AS _description,
     302   reporter AS _reporter
     303  FROM ticket t,enum p
     304  WHERE status = 'assigned'
     305AND p.name=t.priority AND p.type='priority'
     306  ORDER BY __group__, @SORT_COLUMN@, p.value, severity, time
     307@LIMIT_OFFSET@
     308}}}
     309
     310If you want to always sort first by priority and only then by the user selected sort column, simply use the following `ORDER BY` clause:
     311{{{
     312  ORDER BY __group__, p.value, @SORT_COLUMN@, severity, time
     313}}}
     314
     315----
     316See also: TracTickets, TracQuery, TracGuide, [http://www.sqlite.org/lang_expr.html Query Language Understood by SQLite]

  • wiki/pages/TracRepositoryAdmin

    r40221 r40226  
     1= Repository Administration
     2[[PageOutline(2-3)]]
     3
     4== Quick start #QuickStart
     5
     6 * Enable the repository connector(s) for the version control system(s) that you will use.
     7 * Add repositories through the //Repositories// admin panel, with `trac-admin` or in the `[repositories]` section of [wiki:TracIni#repositories-section trac.ini].
     8 * Set up a call to `trac-admin $ENV changeset added $REPO $REV` in the post-commit hook of each repository. Additionally, add a call to `trac-admin $ENV changeset modified $REPO $REV` in the post-revprop-change hook of repositories allowing revision property changes.
     9 * Make sure the user under which your hooks are run has write access to the Trac environment, or use a tool like `sudo` to temporarily elevate privileges.
     10
     11== Enabling the components
     12
     13Support for version control systems is provided by optional components distributed with Trac, which are disabled by default //(since 1.0)//. Subversion and Git must be explicitly enabled if you wish to use them.
     14
     15The version control systems can be enabled by adding the following to the `[components]` section of your [TracIni#components-section trac.ini], or enabling the components in the //Plugins// admin panel.
     16
     17{{{#!ini
     18tracopt.versioncontrol.svn.* = enabled
     19}}}
     20
     21{{{#!ini
     22tracopt.versioncontrol.git.* = enabled
     23}}}
     24
     25== Specifying repositories #Repositories
     26Trac supports multiple repositories per environment, and the repositories may be for different version control system types. Each repository must be defined in a repository configuration provider, the two supported by default are the [#ReposDatabase database store] and the [#ReposTracIni trac.ini configuration file]. A repository should not be defined in multiple configuration providers.
     27
     28It is possible to define aliases of repositories, that act as "pointers" to real repositories. This can be useful when renaming a repository, to avoid breaking links to the old name.
     29
     30A number of attributes can be associated with each repository. The attributes define the repository's location, type, name and how it is displayed in the source browser. The following attributes are supported:
     31
     32||='''Attribute''' =||='''Description''' =||
     33||`alias` ||\
     34||A repository having an `alias` attribute is an alias to a real repository. All TracLinks referencing the alias resolve to the aliased repository. Note that multiple indirection is not supported, so an alias must always point to a real repository. The `alias` and `dir` attributes are mutually exclusive. ||
     35||`description` ||\
     36||The text specified in the `description` attribute is displayed below the top-level entry for the repository in the source browser. It supports WikiFormatting. ||
     37||`dir` ||\
     38||The `dir` attribute specifies the location of the repository in the filesystem. It corresponds to the value previously specified in the option `[trac] repository_dir`. The `alias` and `dir` attributes are mutually exclusive. ||
     39||`hidden` ||When set to `true`, the repository is hidden from the repository index page in the source browser. Browsing the repository is still possible, and links referencing the repository remain valid. ||
     40||`sync_per_request`||When set to `true` the repository will be synced on every request. This is not recommended, instead a post-commit hook should be configured to provide [#ExplicitSync explicit synchronization] and `sync_per_request` should be set to `false`.||
     41||`type` ||The `type` attribute sets the type of version control system used by the repository. Trac supports Subversion and Git out-of-the-box, and plugins add support for many other systems. If `type` is not specified, it defaults to the value of the `[trac] repository_type` option. ||
     42||`url` ||The `url` attribute specifies the root URL to be used for checking out from the repository. When specified, a "Repository URL" link is added to the context navigation links in the source browser, that can be copied into the tool used for creating the working copy. ||
     43
     44A repository `name` and one of `alias` or `dir` attributes are mandatory. All others are optional.
     45
     46For some version control systems, it is possible to specify not only the path to the repository in the `dir` attribute, but also a ''scope'' within the repository. Trac will then only show information related to the files and changesets below that scope. The Subversion backend for Trac supports this. For other types, check the corresponding plugin's documentation.
     47
     48After adding a repository, the cache for that repository must be re-synchronized once with the `trac-admin $ENV repository resync` command.
     49
     50 `repository resync <repos>`::
     51   Re-synchronize Trac with a repository.
     52
     53
     54=== In `trac.ini` #ReposTracIni
     55Repositories and repository attributes can be specified in the `[repositories]` section of [wiki:TracIni#repositories-section trac.ini]. Every attribute consists of a key structured as `{name}.{attribute}` and the corresponding value separated with an equal sign (`=`). The name of the default repository is empty.
     56
     57The main advantage of specifying repositories in `trac.ini` is that they can be inherited from a global configuration (see the [wiki:TracIni#GlobalConfiguration global configuration] section of TracIni). One drawback is that, due to limitations in the `ConfigParser` class used to parse `trac.ini`, the repository name is always all-lowercase.
     58
     59The following example defines two Subversion repositories named `project` and `lib`, and an alias to `project` as the default repository. This is a typical use case where a Trac environment previously had a single repository (the `project` repository), and was converted to multiple repositories. The alias ensures that links predating the change continue to resolve to the `project` repository.
     60{{{#!ini
     61[repositories]
     62project.dir = /var/repos/project
     63project.description = This is the ''main'' project repository.
     64project.type = svn
     65project.url = http://example.com/svn/project
     66project.hidden = true
     67
     68lib.dir = /var/repos/lib
     69lib.description = This is the secondary library code.
     70lib.type = svn
     71lib.url = http://example.com/svn/lib
     72
     73.alias = project
     74}}}
     75Note that `name.alias = target` makes `name` an alias for the `target` repo, not the other way around.
     76
     77=== In the database #ReposDatabase
     78Repositories can also be specified in the database, using either the "Repositories" admin panel under "Version Control", or the `trac-admin $ENV repository` commands.
     79
     80The admin panel shows the list of all repositories defined in the Trac environment. It allows adding repositories and aliases, editing repository attributes and removing repositories. Note that repositories defined in `trac.ini` are displayed but cannot be edited.
     81
     82The following [wiki:TracAdmin trac-admin] commands can be used to perform repository operations from the command line.
     83
     84 `repository add <repos> <dir> [type]`::
     85   Add a repository `<repos>` located at `<dir>`, and optionally specify its type.
     86
     87 `repository alias <name> <target>`::
     88   Create an alias `<name>` for the repository `<target>`.
     89
     90 `repository remove <repos>`::
     91   Remove the repository `<repos>`.
     92
     93 `repository set <repos> <key> <value>`::
     94   Set the attribute `<key>` to `<value>` for the repository `<repos>`.
     95
     96Note that the default repository has an empty name, so it will likely need to be quoted when running `trac-admin` from a shell. Alternatively, the name "`(default)`" can be used instead, for example when running `trac-admin` in interactive mode.
     97
     98== Repository caching
     99
     100The Subversion and Git repository connectors support caching, which improves the performance browsing the repository, viewing logs and viewing changesets. Cached repositories must be [#Synchronization synchronized]; either explicit or implicit synchronization can be used. When searching changesets, only cached repositories are searched.
     101
     102Subversion repositories are cached unless the type is `direct-svnfs`. Git repositories are cached when `[git]` [wiki:TracIni#git-section cached_repository] is `true`.
     103
     104== Repository synchronization #Synchronization
     105Prior to 0.12, Trac synchronized its cache with the repository on every HTTP request. This approach is not very efficient and not practical anymore with multiple repositories. For this reason, explicit synchronization through post-commit hooks was added.
     106
     107There is also new functionality in the form of a repository listener extension point ''(IRepositoryChangeListener)'' that is triggered by the post-commit hook when a changeset is added or modified, and can be used by plugins to perform actions on commit.
     108
     109=== Mercurial Repositories
     110Please note that at the time of writing, no initial resynchronization or any hooks are necessary for Mercurial repositories - see [trac:#9485] for more information.
     111
     112=== Explicit synchronization #ExplicitSync
     113This is the preferred method of repository synchronization. It requires setting the `sync_per_request` attribute to `false`, and adding a call to `trac-admin` in the `post-commit` hook of each repository. Additionally, if a repository allows changing revision metadata, a call to `trac-admin` must be added to the `post-revprop-change` hook as well.
     114
     115 `changeset added <repos> <rev> [...]`::
     116   Notify Trac that one or more changesets have been added to a repository.
     117
     118 `changeset modified <repos> <rev> [...]`::
     119   Notify Trac that metadata on one or more changesets in a repository has been modified.
     120
     121The `<repos>` argument can be either a repository name (use "`(default)`" for the default repository) or the path to the repository.
     122
     123Note that you may have to set the environment variable `PYTHON_EGG_CACHE` to the same value as was used for the web server configuration before calling `trac-admin`, if you changed it from its default location. See [wiki:TracPlugins Trac Plugins] for more information.
     124
     125==== Subversion
     126
     127The following examples are complete post-commit and post-revprop-change scripts for Subversion. They should be edited for the specific environment, marked executable (where applicable) and placed in the `hooks` directory of each repository. On Unix (`post-commit`):
     128{{{#!sh
     129#!/bin/sh
     130export PYTHON_EGG_CACHE="/path/to/dir"
     131/usr/bin/trac-admin /path/to/env changeset added "$1" "$2"
     132}}}
     133Note: Check with `whereis trac-admin`, whether `trac-admin` is really installed under `/usr/bin/` or maybe under `/usr/local/bin/` and adapt the path.
     134On Windows (`post-commit.cmd`):
     135{{{#!bat
     136@C:\Python26\Scripts\trac-admin.exe C:\path\to\env changeset added "%1" "%2"
     137}}}
     138
     139The post-revprop-change hook for Subversion is very similar. On Unix (`post-revprop-change`):
     140{{{#!sh
     141#!/bin/sh
     142export PYTHON_EGG_CACHE="/path/to/dir"
     143/usr/bin/trac-admin /path/to/env changeset modified "$1" "$2"
     144}}}
     145On Windows (`post-revprop-change.cmd`):
     146{{{#!bat
     147@C:\Python26\Scripts\trac-admin.exe C:\path\to\env changeset modified "%1" "%2"
     148}}}
     149
     150The Unix variants above assume that the user running the Subversion commit has write access to the Trac environment, which is the case in the standard configuration where both the repository and Trac are served by the web server. If you access the repository through another means, for example `svn+ssh://`, you may have to run `trac-admin` with different privileges, for example by using `sudo`.
     151
     152Note that calling `trac-admin` in your Subversion hooks can slow down the commit and log editing operations on the client side. You might want to use the [trac:source:trunk/contrib/trac-svn-hook contrib/trac-svn-hook] script which starts `trac-admin` in an asynchronous way. The script also comes with a number of safety checks and usage advices which should make it easier to set up and test your hooks. There's no equivalent `trac-svn-hook.bat` for Windows yet, but the script can be run by Cygwin's bash.
     153
     154See the [http://svnbook.red-bean.com/en/1.5/svn.reposadmin.create.html#svn.reposadmin.create.hooks section about hooks] in the Subversion book for more information. Other repository types will require different hook setups.
     155
     156==== Git
     157
     158Git hooks can be used in the same way for explicit syncing of Git repositories.  If your git repository is one that gets committed to directly on the machine that hosts trac, add the following to the `hooks/post-commit` file in your git repo (note: this will do nothing if you only update the repo by pushing to it):
     159{{{#!sh
     160#!/bin/sh
     161REV=$(git rev-parse HEAD)
     162trac-admin /path/to/env changeset added <repos> $REV
     163}}}
     164
     165Alternately, if your repository is one that only gets pushed to, add the following to the `hooks/post-receive` file in the repo:
     166{{{#!sh
     167#!/bin/sh
     168tracenv=/path/to/env     # change with your Trac environment's path
     169repos=                   # change with your repository's name
     170while read oldrev newrev refname; do
     171    if [ "$oldrev" = 0000000000000000000000000000000000000000 ]; then
     172        git rev-list --reverse "$newrev" --
     173    else
     174        git rev-list --reverse "$newrev" "^$oldrev" --
     175    fi | xargs trac-admin "$tracenv" changeset added "$repos"
     176done
     177}}}
     178
     179The `<repos>` argument can be either a repository name (use "`(default)`" for the default repository) or the path to the repository.
     180
     181==== Mercurial
     182