From 6587f6ba7d047ddc1686c080090afe7d53365bd4 Mon Sep 17 00:00:00 2001 From: Ivan Kohler Date: Tue, 24 Apr 2012 11:35:56 -0700 Subject: first pass RT4 merge, RT#13852 --- rt/docs/UPGRADING-2.0 | 7 + rt/docs/UPGRADING-3.0 | 18 + rt/docs/UPGRADING-3.2 | 11 + rt/docs/UPGRADING-3.4 | 12 + rt/docs/UPGRADING-3.6 | 49 + rt/docs/UPGRADING-3.8 | 192 + rt/docs/UPGRADING-4.0 | 108 + rt/docs/UPGRADING.mysql | 85 + rt/docs/customizing/articles_introduction.pod | 155 + rt/docs/customizing/templates.pod | 132 + rt/docs/customizing/timezones_in_charts.pod | 88 + rt/docs/extending/clickable_links.pod | 184 + rt/docs/extending/external_custom_fields.pod | 90 + rt/docs/extending/using_forms_widgets.pod | 113 + rt/docs/full_text_indexing.pod | 174 + rt/docs/glossary.pod | 30 + rt/docs/hacking.pod | 301 ++ rt/docs/network-diagram.svg | 6095 +++++++++++++++++++++++++ rt/docs/schema.dot | 99 + rt/docs/security.pod | 77 + rt/docs/web_deployment.pod | 233 + 21 files changed, 8253 insertions(+) create mode 100644 rt/docs/UPGRADING-2.0 create mode 100644 rt/docs/UPGRADING-3.0 create mode 100644 rt/docs/UPGRADING-3.2 create mode 100644 rt/docs/UPGRADING-3.4 create mode 100644 rt/docs/UPGRADING-3.6 create mode 100644 rt/docs/UPGRADING-3.8 create mode 100644 rt/docs/UPGRADING-4.0 create mode 100644 rt/docs/UPGRADING.mysql create mode 100644 rt/docs/customizing/articles_introduction.pod create mode 100644 rt/docs/customizing/templates.pod create mode 100644 rt/docs/customizing/timezones_in_charts.pod create mode 100644 rt/docs/extending/clickable_links.pod create mode 100644 rt/docs/extending/external_custom_fields.pod create mode 100644 rt/docs/extending/using_forms_widgets.pod create mode 100644 rt/docs/full_text_indexing.pod create mode 100644 rt/docs/glossary.pod create mode 100644 rt/docs/hacking.pod create mode 100644 rt/docs/network-diagram.svg create mode 100644 rt/docs/schema.dot create mode 100644 rt/docs/security.pod create mode 100644 rt/docs/web_deployment.pod (limited to 'rt/docs') diff --git a/rt/docs/UPGRADING-2.0 b/rt/docs/UPGRADING-2.0 new file mode 100644 index 000000000..a935552b5 --- /dev/null +++ b/rt/docs/UPGRADING-2.0 @@ -0,0 +1,7 @@ +UPGRADING FROM 2.x: + +The core RT distribution does not contain the tool to upgrade RT from +version 2.0; the tool, can be downloaded from CPAN at +http://search.cpan.org/dist/RT-Extension-RT2toRT3/ + +Further instructions may be found in that distribution's README file. diff --git a/rt/docs/UPGRADING-3.0 b/rt/docs/UPGRADING-3.0 new file mode 100644 index 000000000..625ca4baf --- /dev/null +++ b/rt/docs/UPGRADING-3.0 @@ -0,0 +1,18 @@ +UPGRADING FROM 3.0.x - Changes: + += Installation = + +We recommend you move your existing /opt/rt3 tree completely out +of the way before installing the new version of RT, to make sure +that you don't inadvertently leave old files hanging around. + += Rights changes = + +Now, if you want RT to automatically create new users upon ticket +submission, you MUST grant 'Everyone' the right to create tickets. +Granting this right only to "Unprivileged Users" is now insufficient. + += Web server configuration + +The configuration for RT's web interface has changed. Please refer to +docs/web_deployment.pod for instructions. diff --git a/rt/docs/UPGRADING-3.2 b/rt/docs/UPGRADING-3.2 new file mode 100644 index 000000000..c0b8cebae --- /dev/null +++ b/rt/docs/UPGRADING-3.2 @@ -0,0 +1,11 @@ +UPGRADING FROM 3.2 and earlier - Changes: + += Rights changes = + +Now, if you want any user to be able to access the Admin tools (a.k.a. +the Configuration tab), you must grant that user the "ShowConfigTab" +right. Making the user a privileged user is no longer sufficient. + +"SuperUser" users are no longer automatically added to the list of users +who can own tickets in a queue. You now need to explicitly give them the +"OwnTicket" right. diff --git a/rt/docs/UPGRADING-3.4 b/rt/docs/UPGRADING-3.4 new file mode 100644 index 000000000..4dca0451f --- /dev/null +++ b/rt/docs/UPGRADING-3.4 @@ -0,0 +1,12 @@ +UPGRADING FROM 3.3.14 and earlier - Changes: + +The "ModifyObjectCustomFieldValues" right name was too long. It has been +changed to "ModifyCustomField" + + +UPGRADING FROM 3.3.11 and earlier - Changes: + +Custom Fields now have an additional right, "ModifyCustomField". This +right governs whether a user can modify an object's custom field values +for a particular custom field. This includes adding, deleting and +changing values. diff --git a/rt/docs/UPGRADING-3.6 b/rt/docs/UPGRADING-3.6 new file mode 100644 index 000000000..3c27709cb --- /dev/null +++ b/rt/docs/UPGRADING-3.6 @@ -0,0 +1,49 @@ +UPGRADING FROM 3.6.X and earlier - Changes: + +As there are a large number of code changes, it is highly recommended +that you install RT into a fresh directory, and then reinstall your +customizations. + +The database schema has changed significantly for mysql 4.1 and above; +please read UPGRADING.mysql for more details. + +The configuration format has been made stricter. All options MUST be set +using the Set function; the historical "@XXX = (...) unless @XXX;" is no +longer allowed. + +The RTx::Shredder extension has been integrated into core, and several +features have been added, so you MUST uninstall it before upgrading. + +A new interface for making links in text clickable, and doing other +arbitrary text replacements, has been integrated into RT. You can read +more in `perldoc docs/extending/clickable_links.pod`. + +A new feature has been added that allows users to forward +messages. There is a new option in the config ($ForwardFromUser), new +rights, and a new template. + +New global templates have been added with "Error: " prefixed to the name +to make it possible to configure error messages sent to users. + +You can read about the new GnuPG integration in `perldoc +lib/RT/Crypt/GnuPG.pm`. + +New scrip conditions 'On Close' and 'On Reopen' have been added. + + +UPGRADING FROM 3.5.7 and earlier - Changes: + +Scrips are now prepared and committed in order alphanumerically by +description. This means that you can prepend a number (00, 07, 15, 24) +to the beginning of each scrip's description, and they will run in that +order. Depending on your database, the old ordering may have been by +scrip id number -- if that is the case, simply prepend the scrip id +number to the beginning of its description. + + +UPGRADING FROM 3.5.1 and earlier - Changes: + +The default for $RedistributeAutoGeneratedMessages has changed to +'privileged', to make out-of-the-box installations more resistant to +mail loops. If you rely on the old default of redistributing to all +watchers, you'll need to set it explicitly now. diff --git a/rt/docs/UPGRADING-3.8 b/rt/docs/UPGRADING-3.8 new file mode 100644 index 000000000..cb53030e4 --- /dev/null +++ b/rt/docs/UPGRADING-3.8 @@ -0,0 +1,192 @@ +UPGRADING FROM 3.8.8 and earlier - Changes: + +Previous versions of RT used a password hashing scheme which was too +easy to reverse, which could allow attackers with read access to the RT +database to possibly compromise users' passwords. Even if RT does no +password authentication itself, it may still store these weak password +hashes -- using ExternalAuth does not guarantee that you are not +vulnerable! To upgrade stored passwords to a stronger hash, run: + + perl etc/upgrade/vulnerable-passwords + +We have also proved that it's possible to delete a notable set of +records from Transactions table without losing functionality. To delete +these records, run the following script: + + perl -I /opt/rt4/local/lib -I /opt/rt4/lib etc/upgrade/shrink_transactions_table.pl + +If you chose not to run the shrink_cgm_table.pl script when you upgraded +to 3.8, you should read more about it below and run it at this point. + +The default for $MessageBoxWrap is now SOFT and $MessageBoxWidth is now +unset by default. This means the message box will expand to fill all +the available width. $MessageBoxWrap is also overridable by the user +now. These changes accommodate the new default two column layout for +ticket create and update pages. You may turn this layout off by setting +$UseSideBySideLayout to 0. To retain the original behavior, set +$MessageBoxWrap to HARD and $MessageBoxWidth to 72. + + +UPGRADING FROM 3.8.7 and earlier - Changes: + +RT's ChartFont option has been changed from a string to a hash which +lets you specify per-language fonts. RT now comes with a better default +font for charts, too. You should either update your 'ChartFont' option +to match the new format, or consider trying the new default. + +RT now gives you more precise control over the order in which custom +fields are displayed. This change requires some small changes to your +currently saved custom field orders. RT will automatically clean up +your existing custom fields when you run the standard database upgrade +steps. After that cleanup, you should make sure that custom fields are +ordered in a way that you and your users find pleasing. + + +UPGRADING FROM 3.8.6 and earlier - Changes: + +For MySQL and Oracle users: +If you upgraded from a version of RT earlier than 3.7.81, you should +already have a CachedGroupMembers3 index on your CachedGroupMembers +table. If you did a clean install of RT somewhere in the 3.8 release +series, you most likely don't have this index. You can add it manually +with: + + CREATE INDEX CachedGroupMembers3 on CachedGroupMembers (MemberId, ImmediateParentId); + + +UPGRADING FROM 3.8.5 and earlier - Changes: + +You can now forward an entire Ticket history (in addition to specific +transactions) but this requires a new Template called "Forward Ticket". +This template will be added as part of the standard database upgrade +step. + +Custom fields with categories can optionally be split out into +hierarchical custom fields. If you wish to convert your old +category-based custom fields, run: + + perl etc/upgrade/split-out-cf-categories + +It will prompt you for each custom field with categories that it finds, +and the name of the custom field to create to store the categories. + +If you were using the LocalizedDateTime RT::Date formatter from custom +code, and passing a DateFormat or TimeFormat argument, you need to +switch from the strftime methods to the cldr methods; that is, +'full_date_format' becomes 'date_format_full'. + +You may also have done this from your RT_SiteConfig.pm, using: + Set($DateTimeFormat, { + Format => 'LocalizedDateTime', + DateFormat => 'medium_date_format', + ); +Which would need to be changed to: + Set($DateTimeFormat, { + Format => 'LocalizedDateTime', + DateFormat => 'date_format_medium', + ); + + +UPGRADING FROM 3.8.3 and earlier - Changes: + +Arguments to the NotifyGroup Scrip Action will be updated as part of the +standard database upgrade process. + + +UPGRADING FROM 3.8.2 and earlier - Changes: + +A new scrip condition, 'On Reject', has been added. + + +UPGRADING FROM 3.8.1 and earlier - Changes: + +When using Oracle, $DatabaseName is now used as SID, so RT can connect +without environment variables or tnsnames.ora file. Because of this +change, your RT instance may loose its ability to connect to your DB; to +resolve this, you will need to update RT's configuration and restart +your web server. Example configuration: + + Set($DatabaseType, 'Oracle'); + Set($DatabaseHost, '192.168.0.1'); + # undefined port => will try both 1526 and 1521 + Set($DatabasePort, undef); + # ORACLE SID + Set($DatabaseName, 'XE'); + # user for RT in Oracle, RT's tables in his schema + Set($DatabaseUser, 'test'); + # above user's password + Set($DatabasePassword, 'test'); + +If you want a user to be able to access the Approvals tools (a.k.a. the +Approvals tab), you must grant that user the "ShowApprovalsTab" right. + + +UPGRADING FROM 3.8.0 and earlier - Changes: + +The TicketSQL syntax for bookmarked tickets has been changed. +Specifically, the new phrasing is "id = '__Bookmarked__'", rather than +the old "__Bookmarks__". The old form will remain, for backwards +compatibility. The standard database upgrade process will only +automatically change the global 'Bookmarked Tickets' search + + +UPGRADING FROM 3.7.85 and earlier - Changes: + +We have proved that it is possible to delete a large set of records from +the CachedGroupMembers table without losing functionality; in fact, +failing to do so may result in occasional problems where RT miscounts +users, particularly in the chart functionality. To delete these records +run the following script: + + perl -I /opt/rt4/local/lib -I /opt/rt4/lib etc/upgrade/shrink_cgm_table.pl + +After you run this, you will have significantly reduced the number of +records in your CachedGroupMembers table, and may need to tell your +database to refresh indexes/statistics. Please consult your DBA for +specific instructions for your database. + + +UPGRADING FROM 3.7.81 and earlier - Changes: + +RT::Extension::BrandedQueues has been integrated into core, and the +handling of subject tags has changed as a consequence. You will need to +modify any of your email templates which use the $rtname variable, in +order to make them respect the per-queue subject tags. To edit your +templates, log into RT as your administrative user, then click: + + Configuration -> Global -> Templates -> Select -> + +The only template which ships with RT which needs updating is the +"Autoreply" template, which includes this line: + + "There is no need to reply to this message right now. Your ticket + has been assigned an ID of [{$rtname} #{$Ticket->id()}]." + +Change this line to read: + + "There is no need to reply to this message right now. Your ticket + has been assigned an ID of { $Ticket->SubjectTag }." + +If you were previously using RT::Extension::BrandedQueues, you MUST +uninstall it before upgrading. In addition, you must run the +'etc/upgrade/3.8-branded-queues-extension' perl script. This will +convert the extension's configuration into the new format. Finally, in +templates where you were using the Tag method ($Ticket->QueueObj->Tag), +you will need to replace it with $Ticket->SubjectTag + +RT::Action::LinearEscalate extension has been integrated into core, +so you MUST uninstall it before upgrading. + +RT::Extension::iCal has been integrated into core, so you MUST uninstall +it before upgrading. In addition, you must run etc/upgrade/3.8-ical-extension +script to convert old data. + + +UPGRADING FROM 3.7.80 and earlier - Changes: + +Added indexes to CachedGroupMembers for MySQL and Oracle. +If you have previously installed RTx-Shredder, you may already +have these indexes. You can see the indexes by looking at +etc/upgrade/3.7.81/schema.* + +These indexes may take a very long time to create. diff --git a/rt/docs/UPGRADING-4.0 b/rt/docs/UPGRADING-4.0 new file mode 100644 index 000000000..a9301348e --- /dev/null +++ b/rt/docs/UPGRADING-4.0 @@ -0,0 +1,108 @@ +Common Issues + +RT now defaults to a database name of rt4 and an installation root of /opt/rt4. + +If you are upgrading, you will likely want to specify that your database +is still named rt3 (or import a backup of your database as rt4 so that +you can feel more confident making the upgrade). + +You really shouldn't install RT4 into your RT3 source tree (/opt/rt3) +and instead should be using make install to set up a clean environment. +This will allow you to evaluate your local modifications and configuration +changes as you migrate to 4.0. + +If you choose to force RT to install into /opt/rt3, or another existing RT 3.x +install location, you will encounter issues because we removed the _Overlay +files (such as Ticket_Overlay.pm) and relocated other files. You will +need to manually remove these files after the upgrade or RT will fail. +After making a complete backup of your /opt/rt3 install, you might use a +command like the following to remove the _Overlay files: + + find /opt/rt3/lib/ -type f -name '*_Overlay*' -delete + +RT has also changed how web deployment works; you will need to review +docs/web_deployment.pod for current instructions. The old +`fastcgi_server`, `webmux.pl`, and `mason_handler.*` files will not +work with RT 4.0, and should be removed to reduce confusion. + +******* +RT_SiteConfig.pm + +You will need to carefully review your local settings when moving from +3.8 to 4.0. + +If you were adding your own custom statuses in earlier versions of RT, +using ActiveStatus or InactiveStatus you will need to port these to use +the new Lifecycles functionality. You can read more about it in +RT_Config.pm. In most cases, you can do this by extending the default +active and inactive lists. + +******* +Upgrading sessions on MySQL + +In 4.0.0rc2, RT began shipping an updated schema for the sesions table +that specificies a character set as well as making the table InnoDB. As +part of the upgrade process, your sessions table will be dropped and +recreated with the new schema. + +******* +UPGRADING FROM RT 3.8.x and RTFM 2.1 or greater + +RT4 now includes an Articles functionality, merged from RTFM. +You should not install and enable the RT::FM plugin separately on RT 4. +If you have existing data in RTFM, you can use the etc/upgrade/upgrade-articles +script to upgrade that data. + +When running normal upgrade scripts, RT will warn if it finds existing +RTFM tables that contain data and point you to the upgrade-articles script. + +This script should be run from your RT tarball. It will immediately +begin populating your new RT4 tables with data from RTFM. If you have +browsed in the RT4 UI and created new classes and articles, this script +will fail spectacularly. Do *not* run this except on a fresh upgrade of +RT. + +You can run this as + + etc/upgrade/upgrade-articles + +It will ouput a lot of data about what it is changing. You should +review this for errors. + +If you are running RTFM 2.0 with a release of RT, there isn't currently an upgrade +script that can port RTFM's internal CustomField and Transaction data to RT4. + +You must also remove RT::FM from your @Plugins line in RT_SiteConfig.pm. + +******* +The deprecated classes RT::Action::Generic, RT::Condition::Generic and RT::Search::Generic +have been removed, but you shouldn't have been using them anyway. You should have been using +RT::Action, RT::Condition and RT::Search, respectively. + +* The "Rights Delegation" and "Personal Groups" features have been removed. + +* Replace the following code in templates: + + [{$Ticket->QueueObj->SubjectTag || $rtname} #{$Ticket->id}] + +with + + { $Ticket->SubjectTag } + +* Unique names are now enforced for user defined groups. New groups cannot be + created with a duplicate name and existing groups cannot be renamed to an + in-use name. The admin interface will warn about existing groups with + duplicate names. Although the groups will still function, some parts of the + interface (rights management, subgroup membership) may not work as expected + with duplicate names. Running + + /opt/rt4/sbin/rt-validator --check + + will report duplicate group names, and running it with --resolve will fix + duplicates by appending the group id to the name. + + Nota Bene: As a result of differing indexes in the schema files, Postgres and + SQLite RT databases have enforced group name uniqueness for many years at the + database level. + +******* diff --git a/rt/docs/UPGRADING.mysql b/rt/docs/UPGRADING.mysql new file mode 100644 index 000000000..77a6b389f --- /dev/null +++ b/rt/docs/UPGRADING.mysql @@ -0,0 +1,85 @@ +If you did not start by reading the README file, please start there; +these steps do not list the full upgrading process, merely a part which +is sometimes necessary. + +This file applies if either: + + 1) You are upgrading RT from a version prior to 3.8.0, on any version + of MySQL +............. OR ............. + 2) You are migrating from MySQL 4.0 to MySQL 4.1 or above + +If neither of the above cases apply, your should upgrade as per the +instructions in the README. + +These changes are necessary because MySQL 4.1 and greater changed some +aspects of character set handling that may result in RT failures; this +will manifest as multiple login requests, corrupted binary attachments, +and corrupted image custom fields, among others. In order to resolve +this issue, the upgrade process will need to modify the schema. + + 1) If you are moving the database and/or upgrading MySQL + 1a) Dump the database; with MySQL 4.1 and greater be sure to pass + the mysqldump command the --default-character-set=binary option. + This is necessary because the data was originally encoded in + Latin1. + + 1b) Configure the new MySQL to use Latin1 as the default character + set everywhere, not UTF-8. This is necessary so the import in + the next step assumes the data is Latin1. + + 1c) Import the dump made in step 1a into the new MySQL server, using + the --default-character-set=binary option on restore. This will + ensure that the data is imported as bytes, which will be + interpreted as Latin1 thanks to step 1b above. + + 1d) Test that your RT works as expected on this new database. + + 2) Backup RT's database using --default-character-set=binary + Furthermore, test that you can restore from this backup. + + 3) Follow instructions in the README file to step 6b. + + 4) Apply changes described in the README's step 6b, but only up to + version 3.7.87. + + 5) Apply the RT 3.8 schema upgrades. Included in RT is the script + etc/upgrade/upgrade-mysql-schema.pl that will generate the + appropriate SQL queries: + + perl etc/upgrade/upgrade-mysql-schema.pl db user pass > queries.sql + + If your mysql database is on a remote host, you can run the script + like this instead: + + perl etc/upgrade/upgrade-mysql-schema.pl db:host user pass > queries.sql + + 6) Check the sanity of the SQL queries in the queries.sql file + yourself, or consult with your DBA. + + 7) Apply the queries. Note that this step can take a while; it may also + require additional space on your hard drive comparable with size of + your tables. + + mysql -u root -p rt3 < queries.sql + + NOTE that 'rt3' is the default name of the RT database, change it in + the command above if your database is named differently. + + This step should not produce any errors or warnings. If you see any, + restore your database from the backup you made at step 1, and send a + report to the rt-users@lists.bestpractical.com mailing list. + + 8) Re-run the `make upgrade-database` command from step 6b of the + README, applying the rest of the upgrades, starting with 3.7.87, and + follow the README's remaining steps. + + 9) Test everything. The most important parts you have to test: + * binary attachments, like docs, PDFs, and images + * binary custom fields + * everything that may contain characters other than ASCII + +10) If you were upgrading from MySQL 4.0, you may now, if you wish, + reconfigure your newer MySQL instance to use UTF-8 as the default + character set, as step 7 above adjusted the character sets on all + existing tables to contain UTF-8 encoded data, rather than Latin1. diff --git a/rt/docs/customizing/articles_introduction.pod b/rt/docs/customizing/articles_introduction.pod new file mode 100644 index 000000000..ea49b05de --- /dev/null +++ b/rt/docs/customizing/articles_introduction.pod @@ -0,0 +1,155 @@ + +=head1 Articles + +Articles are a way of managing stock answers or frequently asked +questions. Articles are a collection of custom fields whose values can +be easily inserted into ticket replies or searched and browsed within +RT. They are organized into classes and topics. + +=head2 UI + +The user interface to Articles is available from the Tools -> Articles +menu. Admin functionality can be found under Tools -> Configuration -> +Articles. Once configured, articles will become available for searching +on the Reply/Comment page on tickets. There are configuration variables +to make Articles available on ticket creation. + +=head2 Basics + +You will need to make some decisions about how to organize your +articles. Articles will be organized into one Class and multiple +Topics. They will use Custom Fields to store their article data. +These Custom Fields can be configured on a Class by Class basis. +Classes can be made available globally or on a per-Queue basis. + +=head2 Organization + +=head3 Classes + +Classes are equivalent to RT's queues. They can be created by going +to Tools -> Configuration -> Articles -> Classes -> New Class. Articles +are assigned to one Class. When you create Custom Fields for use with +Articles, they will be applied Globally or to a Class, like Custom +Fields are applied to a Queue in RT. Each class also controls what +information is included into a reply (such as the Class header and +footer) and the Article. + +Classes need to be Applied, just like a Custom Field by using the +Applied To link. You can apply them globally or on a queue-by-queue +basis. + +hotlist. + +=head3 Topics + +You can also use Topics to organize your Articles. While editing a +Class, there is a Topic tab for Class specific Topics. You can create +global Topics from the Global tab under Tools -> Configuration. + +When editing Topics, type the name (and optionally description) of the +Topic, and then click the button at the appropriate location in the +Topic hierarchy. This should allow you to build a tree of Topics. This +tree of Topics should show up when creating or modifying articles in +the class. These can be arbitrarily nested. + +Global Topics will be available for all Articles, regardless of their +Class. Articles can belong to both global and class-specific Topics. + +Articles topics can be set from the 'Modify' screen for the article -- +simply select as many topics as you desire from the list at the bottom +of the screen. + +=head2 Custom Fields + +Articles don't have a single "body" section for each +article. Everything is a custom field (except for name, summary and +some other basic metadata). So, you need to create some custom +fields to hold the Article body and other data. These Custom Fields +should have "Applies To" be "RTFM Articles". + +Once you've created your custom fields, go into your classes and click +on "Custom Fields" and add the Custom Fields you want to each class. +Alternatively, use the Applies To link from each Custom Field. + +=head2 Creating Articles + +You can create an article from scratch by going to Tools -> Articles -> +New Article and then picking which Class to create the Article under. +The Summary, Description and Custom Fields will all be searchable when +including an Article and you can control what Custom Fields end up in +your Ticket from the Class configuration page. + +=head3 Extracting an Article + +You can extract the body of a ticket into an article. Within RT, you +should now see an "Extract to article" button in the upper right hand +corner of RT's UI when working with tickets. When you click that +button, RT will ask you which Class to create your new article in. +Once you click on a class name, the Ticket's transactions will be +displayed, along with a set of select boxes. For each transaction, you +can pick which Custom Field that transaction should be extracted to. +From there on in, it's just regular article creation. + +=head2 Including an Article + +When replying to or commenting on tickets or creating tickets, there +is a UI widget that lets you search for and include Articles in +your reply. (They're editable, of course). + +Articles can be included by searching for them, knowing the Id of the +article, using the Article Hotlist and using the Queue specific +dropdown. + +=head2 Queue Specific List of Articles + +You can use Topics to organize a set of Queue specific Articles. +Simply create a global Topic called 'Queues' and then create Topics +under Queues named after each of your Queues. Within each Queue named +Topic, create some Topics and then assign Articles to those +sub-topics. This creates a hierarchy like this: + +Queues +\-> General + \-> Topic 1 + \-> Topic 2 + +If you are replying to a Ticket in the General Queue you will be +offered a choice of Topic 1 and Topic 2 along with the searching. +After choosing Topic 1 or Topic 2, you will be given a list of +relevant articles to choose. + +Alternately, you can now implement this by applying a single class to +your queue and using the L
feature described below. + +=head2 Article Hotlist + +If you enable "All articles in this class are on dropdown on ticket +reply page" option, there will be a dropdown on the Create or Update +page which allows users to quickly include Articles. + +=head2 SelfService Interface + +If you grant the Unprivileged user group the right ShowArticle, they +will get a Search box at the top of their interface. This allows users +to look for answer to questions before creating a Ticket. + +=head1 Configuration options + +=head2 ArticleOnTicketCreate + +Set this to a true value to display the Article include interface on the +Ticket Create page in addition to the Reply/Comment page (Create.html +in addition to Update.html) + +=head2 HideArticleSearchOnReplyCreate + +On Ticket Reply (and Create if you set the above config var) +RTFM normally displays a search box and an include box (for +inputting an article id) and configurable dropdowns +of articles. These can be configured using Global Topics or +on the Class page. + +If you set this to a true value, RTFM will only display +dropdowns and hide the search boxes + +=cut diff --git a/rt/docs/customizing/templates.pod b/rt/docs/customizing/templates.pod new file mode 100644 index 000000000..5733f606c --- /dev/null +++ b/rt/docs/customizing/templates.pod @@ -0,0 +1,132 @@ +=head1 Templates + +Each template is split into two sections. A block of headers and a body. These +sections are separated by a blank line. + +Templates are processed by the L module. This module +allows you to embed arbitrary Perl code into your templates. Text wrapped +in curly braces, C<{...}> is interpreted as Perl. See L +for more information. + +=head2 Headers + +Your template may specify arbitrary email headers. Each header is a name, a +colon, then a value. So, for example, to specify a subject, you can use: + + Subject: Thanks for your bug report. + +=head3 Special Headers + +=over + +=item Content-Type: text/html + +The special header "Content-Type: text/html" tells RT that the template should +be parsed as HTML. RT will automatically make the outgoing message multipart. +That way, recipients who can read only plaintext email will receive something +readable, while users with clients which can display HTML will receive the full +experience. Please be aware that HTML support in mail clients varies greatly, +much more so than different web browsers. + +We welcome contributions of HTML-ization of builtin templates. + +=back + +=head2 Template Types + +Templates have a Type which dictates which level of code execution is +allowed. + +Templates of type C are evaluated using L +which allows arbitrary code execution. Only users which have the global +C privilege may write templates of type C. Prior to +RT 4.0, this was the only type of Template available. + +Templates of type C permit only simple variable interpolation. +No special privilege beyond C is needed to write C +templates. + +For both types of templates, text between curly braces C<{ ... }> is +interpolated. For C templates, this text can be any code (see +L). For C templates, only simple variables +are permitted; for example C<{ $TicketSubject }>. + +=head2 Variables + +=head3 Perl templates + +The variables that your templates may use include: + +=over 4 + +=item C<$Transaction> + +The transaction object. + +=item C<$rtname> + +The value of the "rtname" config variable. + +=item C<$Ticket> + +The ticket object. This is only set during a ticket transaction. + +=item C<$Requestor> + +This is not an object, but the name of the first requestor on the ticket. +If this is not what you need, inspect C<< $Ticket->Requestors >>. + +=item C + +A localization function. See L. + +=back + +=head3 Selected Simple template variables + +Since method calls are not allowed in simple templates, many common +method results have been placed into scalar variables for the template's +use. Among them: + +=over 4 + +=item $TicketId + +=item $TicketSubject + +=item $TicketStatus + +=item $TicketQueueName + +=item $TicketOwnerName + +=item $TicketOwnerEmailAddress + +=item $TicketCF(Name) + +For example, C<$TicketCFDepartment>. + +=item $TransactionType + +=item $TransactionField + +=item $TransactionOldValue + +=item $TransactionNewValue + +=item $TransactionData + +=item $TransactionContent + +=item $TransactionDescription + +=item $TransactionBriefDescription + +=item $TransactionCF(Name) + +For example, C<$TransactionCFLocation>. + +=back + +=cut + diff --git a/rt/docs/customizing/timezones_in_charts.pod b/rt/docs/customizing/timezones_in_charts.pod new file mode 100644 index 000000000..47c3a096f --- /dev/null +++ b/rt/docs/customizing/timezones_in_charts.pod @@ -0,0 +1,88 @@ +=head1 INTRODUCTION + +Every date in RT's DB is stored in UTC format. This affects charts +grouped by time periods (Annually, Monthly, etc.), in that they are by +default shown in UTC. To produce charts that are in a specific timezone, +we have to use database-specific functions to convert between timezones; +unsurprisingly, each DB has very different requirements. + +=head1 CONFIGURATION + +This code is experimental; you can enable it using the +C<$ChartsTimezonesInDB> configuration option. + +=head1 DATABASE SPECIFIC NOTES + +=head2 mysql + +The time adjustment cannot simply be converted using a numeric time +shift, as this shift value depends on the daylight saving time +properties of the time zone. + +mysql since 4.1.3 supports named timezones, but you have to fill special +tables with up-to-date timezone data. On modern systems, this is usually +a simple case of: + + mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root mysql + +mysql's doc recommends you restart server after running this; you can +read more about mysql's timezone support at +L + +=head2 PostgreSQL + +PostgreSQL uses your operating system's functions to convert timezones. +Thus, you don't need to do anything in particular except to make sure +that the data in F is up to date. On some systems +this may mean upgrading a system package. + +=head3 Note for users of Pg 7.2 and older or users upgraded from those + +You should be sure that timestamps in RT DB have no TZ set. The +TIMESTAMP column type in PostgreSQL prior to Pg 7.3 had timezone info by +default; this has been removed in more recent versions. If your RT +database has this embedded timezone info, you will need to alter the +columns to remove them before enabling this feature. + +=head2 Other databases + +There is no implementation for Oracle or SQLite at current. + +=head1 FOR DEVELOPERS + +=head2 PostgreSQL + +We use the timestamp type for all datetime fields. It either has +timezone info or not, since by default Pg 7.3 and above have no +timezone. Conversion is kinda tricky: + + timezone('Europe/Moscow', timezone('UTC', column_without_tz_info)) + timezone('to_tz', timezone('from_tz', column_without_tz_info)) + +This function flips the HAS_TZ flag on the argument, and moves the +timestamp to UTC. The first call makes no conversion, but flips the +HAS_TZ flag; the second call flips it back and does actual conversion. + +For more information, See +L +and +L + +=head2 mysql + +Once timezone information is loaded into tables on the server, +we have all the same set of named timezones in the system +and DateTime (DateTime project has copy of the TZ data in a module). + +CONVERT_TZ(TS, from, to) exists since mysql 4.1.3. Note that it takes a +timestamp, so it only supports limitted date range (usuall 1970-2038). + +=head2 Oracle + +Look at FROM_TZ function. + +=head2 SQLite + +Has no apparent timezone support. + +=cut diff --git a/rt/docs/extending/clickable_links.pod b/rt/docs/extending/clickable_links.pod new file mode 100644 index 000000000..91e9eec22 --- /dev/null +++ b/rt/docs/extending/clickable_links.pod @@ -0,0 +1,184 @@ +=head1 MakeClicky extension + +=head2 Description + +I detects various formats of data in headers and email +messages, and makes them into links in RT's web UI. + +=head2 Configuration + +You can configure which actions are enabled from RT config with the +@Active_MakeClicky option, which should contain an ordered list of the +actions you want to apply. + +By default, RT provides two actions: + +=over 4 + +=item C + +Detects C and C URLs and adds an C<[Open URL]> link +after the URL. + +=item C + +Detects URLs as C format, but replaces the URL with a link. + +=back + +RTIR, an RT extension for CERT teams (not installed with core RT), +shipps with several additional actions you can use: C, C, +C, C and C. + +=head2 Order of actions + +The order of the actions is important in situations when you use +multiple actions that could match the same block of text; only the first +matching action from the list is applied. For example, it makes no sense +to use C and C at the same time, as both +actions always match the same pieces of text. + +=head2 How it works + +Each action consists of regular expression and function that does text +replacement. When you open the history of a ticket, RT searches in the +text with the given regular expresion for matches. If it finds a match, +it calls the function with the match as the argument, then replaces the +matched text with the string returned by the function. + +While RT only searches plaintext content, the actions can generate +arbitrary HTML. + +=head2 Writing custom MakeClicky actions + +To extend the list of actions with your own types of data, use the +provided callback. Specifically, create the file +F. + +It will be called with the following arguments: + +=over 4 + +=item types + +An array reference of hash references. Modify this array +reference to add your own types; the first matching type will be +used. Each hashref should contain: + +=over 4 + +=item name + +The name of the data format; this is used in the configuration file to +enable the format. + +=item regex + +A regular expression to match against. + +=item action + +The name of the action to run (see "actions", below) + +=back + +=item actions + +A hash reference of 'actions'. Modify this hash reference to change or +add action types. Values are subroutine references which will get +called when needed. They should return the modified string. Note that +subroutine B HTML. + +=item handler + +A subroutine reference; modify it only if you have to. This can be used +to add pre- or post-processing around all actions. + +=back + +=head2 Actions' arguments + +A hash is passed to the action with two keys that always exist: + +=over 4 + +=item value + +The full match of the regular expression; this is the block of text that +will be replaced with action's result. + +=item all_matches + +And arrayref with all of the match's capturing groups; for example if +your regexp is C, then the first element will be +full match ("ticket #XXX"), the same as in 'value' key, but the second +element of the array will be the id of a ticket (XXX). Using this, you +can avoid reparsing the value in the action. Only the first eight +groups of your regexps are passed to action. + +=back + +=head2 Custom MakeClicky action example + +Create a new file F +with the content: + + <%ARGS> + $types => [] + $actions => {} + + <%INIT> + my $web_path = RT->Config->Get('WebPath'); + + # action that takes ticket ID as argument and returns link to the ticket + $actions->{'link_ticket'} = sub { + my %args = @_; + my $id = $args{'all_matches'}[1]; + return qq{$args{value}}; + }; + + # add action to the list + push @$types, { + # name, that should be used in config to activate action + name => 'short_ticket_link', + # regular expression that matches text 'ticket #xxx' + regex => qr{ticket\s+#(\d+)}i, + # name of the action that should be applied + action => 'link_ticket', + }; + + +That's all; add C to the C<@Active_MakeClicky> option +in your C, and restart your server. Creating a ticket +with "ticket #1" in the body should cause that text to be automatically +linked to the ticket in question. + +=head2 Notes for custom clicky actions writers + +=over + +=item * + +Note that an action B illegal HTML characters with entities +and/or arguments in URLs. + +=item * + +Complex regular expressions could slow down RT, as the conversion is run +each time a user opens a ticket, for every transaction. For long +tickets and complex regular expressions, this can slow down ticket +display notably. + +=item * + +Try to match the shortest expression you need with your regular +expression; otherwise another action may miss its chance to match. + +=item * + +Whenever possible, precalculate values using closures around the +functions. + +=back + +=cut diff --git a/rt/docs/extending/external_custom_fields.pod b/rt/docs/extending/external_custom_fields.pod new file mode 100644 index 000000000..c6730ae4e --- /dev/null +++ b/rt/docs/extending/external_custom_fields.pod @@ -0,0 +1,90 @@ +=head1 External custom fields + +=head2 Description + +C is an extension to custom fields that allow +you to define CFs with dynamic lists of values. Loading values into +these custom fields requires writing a little Perl code to fetch the +data from the external source. + +=head2 Introduction into writing source of values + +For each type of data source that you want, you'll need to put a file in +F (or equivalent if you +installed RT into someplace other than F). To get a sense of +the code that you'll need to write, take a look at the code in +L for a simple example +which just uses RT's API to pull in a list of RT's groups. + +Running C will +show you the documentation for the API that needs to be fulfilled; +copying and editing the C example is probably a fine place to +start. + +Later in this doc we'll describe the example a little bit more. + +=head2 Configuration + +After the custom code is written, you need to tell RT about its +existence by adding something like following to your RT_SiteConfig.pm: + + Set(@CustomFieldValuesSources, "RT::CustomFieldValues::MySource"); + +The value in quotes should be the name of the class that you created. + +Stop and start your web server to enable any config changes. Open the +web interface as an administrative user (such as root), and create new +custom field. Set its type to be a Select or Autocomplete field, and +save the changes. You should now you have ability to select a "source" +for values. Choose the class you wrote from the list and the save +changes. + +=head2 How to write custom source + +You have to implement a subclass of L. +There are two main methods you want to override: + +=over 4 + +=item SourceDescription + +This method should return a string describing the data source; this is +the identifier which the administrator will see in the dropdown in the +web interface. See L. + +=item ExternalValues + +This method should return an array reference of hash references. The +hash references should contain keys for C, C, and +C. C is most important one; the others are optional. + +=back + +Here's a simple static example: + + package RT::CustomFieldValues::MySource; + + # define class inheritance + use base qw(RT::CustomFieldValues::External); + + # admin friendly description, the default valuse is the name of the class + sub SourceDescription { + return 'My Source'; + } + + # actual values provider method + sub ExternalValues { + # return reference to array ([]) + return [ + # each element of the array is a reference to hash that describe a value + # possible keys are name, description and sortorder + { name => 'value1', description => 'external value', sortorder => 1 }, + { name => 'value2', description => 'another external value', sortorder => 2 }, + # values without description are also valid, the default description is empty string + { name => 'value3', sortorder => 3 }, + # you can skip sortorder too, but note that the default sortorder is 0 (zero) + { name => 'value3' }, + ]; + } + + 1; # don't forget to return some true value diff --git a/rt/docs/extending/using_forms_widgets.pod b/rt/docs/extending/using_forms_widgets.pod new file mode 100644 index 000000000..8deb91362 --- /dev/null +++ b/rt/docs/extending/using_forms_widgets.pod @@ -0,0 +1,113 @@ +=head1 Using widgets F + +This widgets was implemented to address several common issues in handling +request arguments and allow developers to avoid reinventing the wheel. + +=head2 General info + +Each component shows widget by default and has two methods: Process and +InputOnly. The first one method process arguments and return new value +of a parametr. The second one is helper that shows only form elements +with minimum of required text labels. + +So you show a widget with: + <& /Widgets/Form/Integer, + Name => 'NameOfInputElement', + Description => 'Input integer', + &> + +You can show only C box using: + <& /Widgets/Form/Integer:InputOnly, + Name => 'NameOfInputElement', + &> + +In such a simple case you even can avoid processing. Yeah, most probably +you want to check if value is really integer, but these widgets don't +do validation for you, but they are more about fetching values from +hash of arguments, showing these values to user and preserving state +of value between form reloads (see below). + +=head2 Processing + +Processing is required when you use L, +such as Default, Multiple or Alternative. + +To process arguments of a request you have to do the following: + $ARGS{'NameOfInputElement'} = $m->comp( + '/Widgets/Form/Integer:Process', + Arguments => \%ARGS, + Name => 'NameOfInputElement', + ); + +The method returns processed value in canonical form. For different widgets +a canonical form is different and depends on activated features, so you must +always activate the same features during showing a widget and processing +results. + +=head2 Extendent features + +=head3 Default value + +If C argument is true then widgets expect that there is some +default value for argument if user fills nothing. 'Nothing' in each +widget is different, for example in select box it's special option +which is always the first one, in integer box string '' means empty +value, but boolean box uses radio buttons in this case with three +options: Yes, No and Default. + +Each widget that supports C feature as well has C and +C arguments. + +=head4 Processing and showing with activated Default feature + +When this option is activated then C method returns undef +value if user selected default value. So for integer box it's empty +string and so on. + +As well when you show a widget you should pass undef as C +to inform widget that the current value is default one. + +As all methods of a widget are consistent in this behaviour so you +shouldn't care much about that, but this allows you to implement +custom actions if processing returned undef, for example delete user's +preference record instead of updating it (default value may change later to). + +=head4 C when C is not active + +DefaultValue argument is still actual in the Process method even if +C is not true. This argument defines intial value. If value +of a key in Arguments is not defined then it's treated as intial state +and the method returns default value. + +=head3 Multiple and Alternative + +These options are only supported by the select widget. + +TODO: Add more info + +=head2 Implementation details + +=head3 Boolean widget + +This widget a little bit tricky. When you use Default option then +things are simple and you see three radio buttons, but in other +case we use a checkbox. But as you know browsers don't pass unchecked +boxes to server, so arguments of a request has no entry for them. + +In the latter case it's hard to figure out case when user unselected +value. Imagine form with a checkbox, you want show it checked by +default and as well form is reloadable (like Reply forms that have +"Add Another File" buttons). User uncheck the box and then upload +file, in this case you want to show user's choice instead of default, +but browser doesn't send any value and you can not figure out if +it's initial state or page reload. To solve this problem we use magic +hidden input field with the same name as the box and value equal to +zero (0). Mason folds arguments with the same name into array refs, so +we get 0 if box is unchecked and [0, 1] if box is checked. An array +reference is true value and 0 is defined value so we know that it's +not initial state and avoid switching back to default. As well this +trick works good in a case when you want show a link to a page and +define default choice for some boolean argument, you don't need +to set argument twice, you just set it to true value (for ex. 1) and +things just work. + diff --git a/rt/docs/full_text_indexing.pod b/rt/docs/full_text_indexing.pod new file mode 100644 index 000000000..0952b4eb9 --- /dev/null +++ b/rt/docs/full_text_indexing.pod @@ -0,0 +1,174 @@ +=head1 NAME + +Full text indexing in RT + +=head1 LIMITATIONS + +While all of the below solutions can search for Unicode characters, they +are not otherwise Unicode aware, and do no case folding, normalization, +or the like. That is, a string that contains C followed by C will not match a +search for C. They also only +know how to tokenize C-ish languages where words are separated +by whitespace or similar characters; as such, support for searching for +Japanese and Chinese content is extremely limited. + +=head1 POSTGRES + +=head2 Creating and configuring the index + +Postgres 8.3 and above support full-text searching natively; to set up +the required C column, and create either a C or C +index on it, run: + + sbin/rt-setup-fulltext-index + +If you have a non-standard database administrator username or password, +you may need to pass the C<--dba> or C<--dba-password> options: + + sbin/rt-setup-fulltext-index --dba postgres --dba-password secret + +This will also output an appropriate C<%FullTextSearch> configuration to +add to your F; you will need to restart your webserver +after making these changes. However, the index will also need to be +filled before it can be used. To update the index initially, run: + + sbin/rt-fulltext-indexer --all + +This will tokenize and index all existing attachments in your database; +it may take quite a while if your database already has a large number of +tickets in it. + +=head2 Updating the index + +To keep the index up-to-date, you will need to run: + + sbin/rt-fulltext-indexer + +...at regular intervals. By default, this will only tokenize up to 100 +tickets at a time; you can adjust this upwards by passing +C<--limit 500>. Larger batch sizes will take longer and +consume more memory. Care should be taken to ensure that multiple +instances of C are not run at the same time. + +=head1 MYSQL + +MySQL does not support full-text indexing natively. However, it does +integrate with the external Sphinx engine, available from +L. Unfortunately, Sphinx integration (using +SphinxSE) does require that you recompile MySQL from source. Most +distribution-provided packages for MySQL do not include SphinxSE +integration, merely the external Sphinx tools; these are not sufficient +for RT's needs. + +=head2 Compiling MySQL and SphinxSE + +SphinxSE requires MySQL 5.0 or 5.1; later versions of MySQL have not +been tested at this time. Sphinx version 2.0.1 has been tested to work, +but version 0.9.9 may work as well. Compilation and installation +instructions for MySQL with SphinxSE can be found at +L. + +=head2 Creating and configuring the index + +Once MySQL has been recompiled with SphinxSE, and Sphinx itself is +installed, you may create the required SphinxSE communication table via: + + sbin/rt-setup-fulltext-index + +If you have a non-standard database administrator username or password, +you may need to pass the C<--dba> or C<--dba-password> options: + + sbin/rt-setup-fulltext-index --dba root --dba-password secret + +This will also provide you with the appropriate C<%FullTextSearch> +configuration to add to your F; you will need to +restart your webserver after making these changes. It will also print a +sample Sphinx configuration, which should be placed in +F, or equivalent. + +To fill the index, you will need to run the C command-line tool +provided by Sphinx: + + indexer rt + +Finally, start the Sphinx search daemon: + + searchd + +=head2 Updating the index + +To keep the index up-to-date, you will need to run: + + indexer rt --rotate + +...at regular intervals in order to pick up new and updated attachments +from RT's database. Failure to do so will result in stale data. + +=head2 Caveats + +Sphinx only returns a finite number of matches to any query; this number +is controlled by C in F and +C<%FullTextSearch>'s C in C, which must be +kept in sync. The default, set during C, is +10000. This limit may lead to false negatives in search results if the +maximum number of matches is reached but the results returned do not +match RT's other criteria. + +Take, for example, the instance where Sphinx is configured to return a +maximum of three results, and tickets 1, 2, 3, 4, and 5 contain the +string "target", but only ticket 5 is in status "Open". A search for +C may return no results, +despite ticket 5 matching those criteria, as Sphinx will only return +tickets 1, 2, and 3 as possible matches. + +After index creation, altering C in C is +insufficient to adjust this limit; both C in +F and C<%FullTextSearch>'s C in +C must be updated. + +=head1 ORACLE + +=head2 Creating and configuring the index + +Oracle supports full-text indexing natively using the Oracle Text +package. Once Oracle Text is installed and configured, run: + + sbin/rt-setup-fulltext-index + +If you have a non-standard database administrator username or password, +you may need to pass the C<--dba> or C<--dba-password> options: + + sbin/rt-setup-fulltext-index --dba sysdba --dba-password secret + +This will create an Oracle CONTEXT index on the Content column in the +Attachments table, as well as several preferences, functions and +triggers to support this index. The script will also output an +appropriate C<%FullTextSearch> configuration to add to your +F. + +=head2 Updating the index + +To update the index, you will need to run the following at regular +intervals: + + sbin/rt-fulltext-indexer + +This, in effect, simply runs: + + begin + ctx_ddl.sync_index('rt_fts_index', '2M'); + end; + +The amount of memory used for the sync can be controlled with the +C<--memory> option: + + rt-fulltext-indexer --memory 10M + +Instead of being run via C, this may instead be run via a +DBMS_JOB; read the B +chapter of Oracle's B for details +how to keep the index optimized, perform garbage collection, and other +tasks. + +=cut diff --git a/rt/docs/glossary.pod b/rt/docs/glossary.pod new file mode 100644 index 000000000..0e058ba02 --- /dev/null +++ b/rt/docs/glossary.pod @@ -0,0 +1,30 @@ +=head1 RT Glossary + +This document is intended to be a glossary of terms used in RT. Currently it +doesn't even scratch the surface, but with time it should be expanded. + +=head2 Right names + +RT uses a handful of (mostly) standard prefixes to create right names of the +form "". The prefixes and their meanings (if not apparent) +are explained here. + +=over 4 + +=item Admin - Create, modify, and delete + +=item Create + +=item Delete + +=item Edit - Create, modify, and delete + +=item Load - See/show + +=item Modify - Change the content, details and/or metadata + +=item See - Allow viewing of + +=item Show - Allow viewing of, or display in the interface + +=back diff --git a/rt/docs/hacking.pod b/rt/docs/hacking.pod new file mode 100644 index 000000000..8aa84fd01 --- /dev/null +++ b/rt/docs/hacking.pod @@ -0,0 +1,301 @@ +=head1 Development of RT + +RT's source code is stored in a C repository. If you are not +familiar with git, see L, below, for a short tutorial +which will give you enough information to get started submitting patches +to RT. + +The rest of this document details conventions and tips surrounding the +organization of RT's version control, source code conventions, and how +to submit patches. + + + +=head1 Organization of rt.git + +The RT source repository is available via git from GitHub; you can +browse it at L or obtain a local +copy via: + + git clone git://github.com/bestpractical/rt.git + +The bleeding-edge development happens in the C branch. When a +major release is anticipated, a "trunk" branch will be branched from +this -- for example, C<4.0-trunk>. This will allow the trunk to +stabilize while feature development continues on C. +Additionally, as a release is impending for a particular series, a +release engineering branch will be created, named, for example +C<4.0.0-releng>. + +New feature development should always be based off of the C +branch. Branches to fix bugs should be based off of whichever trunk the +bug was first found in. If you found the bug in your RT 4.0.0 install, +you'd branch from 4.0-trunk. + +Branches should be named based on the trunk they are branched +from -- which is to say, the earliest branch they might be merged into. +For example, a bugfix branched from C<4.0-trunk> might be named +C<4.0/fail-taint-mode-early>. A feature branched from C when +there exists a C<4.0-trunk> but no C<4.2-trunk> might be named +C<4.2/rename-LogToScreen>. For consistency, branches should use dashes, +not underscores, to separate words. + +Branches should be reviewed by another developer before being merged. +Reviewers should make sure that the branch accomplishes what it claims +to, and does not introduce any unwanted behavior in doing so. Commit +messages explain the B as much as the B of each commit, and +not include extranous changes. + + +=head1 Code conventions + +The RT codebase is more than ten years old; as such, there are sections +which do not (yet) conform to the guidelines below. Please attempt to +follow the guidelines, even if the code surrounding your changes does +not yet. + +RT also includes a F<.perltidyrc> in its top-level which encodes many of +the conventions. + +=over + +=item Indentation + +Each level of indentation should be four spaces; tabs should never be +used for indentation. + +=back + +=head1 Internationalization + +RT has been translated into several dozen languages. We use Launchpad +( https://translations.launchpad.net/rt ) to crowdsource our +translations into C files. RT uses L to +localize its user interface. + +Your first stop on this magical journey of internationalization +is L, which explains the whys of +L. RT uses most of the features developed in that +article. + +Strings that are displayed to users should be passed through the +C function or the C<< <&|/l&>... >> Mason template. +C and C both take parameters, which are used in place of +string interpolation (much like C). It's acceptable to use +HTML in C calls, especially for bold and emphasis. However, you +should limit the amount of HTML that translators must keep exactly +correct, which means avoid including tags that wrap the entire +translatable string, especially C<<

>>. + +

<&|/l, $button &>Do not click [_1]

# ok + + <&|/l, $button &>

Do not click [_1]

# not ok + +In a few places in RT we also pass HTML as parameters to C +so that translators do not have to reproduce it exactly, and we can +also change it more freely. For example: + + <&|/l, + '', + '', + &>Distributed under [_1]version 2 of the GNU GPL[_2]. + +F looks for C and +C<< <&|/l&>... >> in our source code to pick out translatable +strings, clean them up, and put them into F files. We use +our C<.po> files not only to populate L's lexicons, +but also to sync new translatable strings and translations with +Launchpad. This Launchpad sync is typically done early during the +freeze of RC releases to give our volunteer translators time to +translate all the new strings which, because of the RC freeze, won't +continue changing. + +Because C and C are used to generate strings for human +eyes, they generally must be used "close to the browser". These are +directly in Mason templates, or in functions that return text that +will be passed through Mason. However, in many places in RT we have +hardcoded strings which need translations. For example, the C<$RIGHTS> +hash in F maps rights' names (which must be +translatable) to their descriptions (which also must be translatable). +However, when we're declaring such structures, we do not want to +translate them straight away. RT uses English internally, including +in its web forms, so we do not want to localize rights' names except +for display, otherwise things might break weirdly when you check +if a user has the "Superusuario" right. Furthermore, when we're +declaring such data structures at compile time, there is no current +user to select which language to use for localization. Thus, we +cannot call C when declaring C<$RIGHTS> and other similar +places. + +For this reason, F lets you +denote translatable strings with comments. That's what the C<#loc_pair> +comments in the C<$RIGHTS> hash in F indicate. +Since we have those comments, our toolchain will put the rights' +names and descriptions into F files, which enables +translation by our lovely volunteers. Later on, when RT displays +information about rights in the web UI, we'll pass the right's name +through C, and L will then be able to find +our "Superusuario". So although we never used a literal +C, we still get its effects thanks to the +C<#loc_pair> comments and using C. + +C<#loc_pair> is used for declaring that the both the key and value +of a particular C<< key => value >> pair are translatable. There +are other markers that you can use. + +C<#loc> is used for declaring that a particular string is translatable. +Its parsing is pretty strict so you can use it to declare that only +the value of a particular C<< key => value >> pair is translatable. + +C<#loc_left_pair> is used for declaring that the I of a +particular C<< key => value >> pair is translatable. This is of +very limited usefulness. + +C<#loc_right_pair> does NOT exist. C<#loc> works in such cases since +its parser does not extend beyond the string at the end of a line. + +=head1 Development tips + +=head2 Setting up a development environment + +=head2 Test suite + +RT also comes with a fairly complete test suite. To run it, you will +need to set environment variables to a database user and password which +can create and drop databases: + + export RT_DBA_USER=root + export RT_DBA_PASSWORD= + +You'll need to configure RT and make sure you have all the dependencies +before running tests. To do this in place without installing: + + ./configure.ac --with-my-user-group --enable-layout=inplace --with-devel-mode + make testdeps + make fixdeps + +Adjust the relevant database options as necessary if you want to test on +Postgres, Oracle, or SQLite. The default is MySQL. + +To run the test suite: + + make test + +If you have multiple processors, you can run the test suite in parallel, +which will be significantly faster: + + make test-parallel + +The C<*-trunk> and C branches are expected to be passing always +be passing all tests. While it is acceptable to break tests in an +intermediate commit, a branch which does not pass tests will not be +merged. Ideally, commits which fix a bug should also include a testcase +which fails before the fix and succeeds after. + + + +=head1 git quickstart + +=over + +=item 1. + +You will first need to obtain a copy of git; this is accomplished via +C in RedHat and derivatives, or C for Debian or Ubuntu. + +=item 2. + +Next, obtain a copy of the RT source from git: + + git clone git://github.com/bestpractical/rt.git + cd rt + +=item 3. + +Configure git to know your name and email address; git uses these when +it makes commits. + + git config user.email your.email@example.com + git config user.name Examp L. Name + +=item 4. + +Switch to the appropriate point to base your work on; this is generally +C followed by the major version, followed by C<-trunk>. For +example, if your bug was observed in version 3.8.9, you would choose +C; if it was in 4.0.0, you would choose +C. New features should be based on C. + + git checkout --track origin/4.0-trunk + +=item 5. + +Give your branch a name based on what you are attempting to accomplish. +We suggest that branch names be lower-case and separate words with +dashes, but this branch name is purely for your own reference. + + git branch -m gnupg-encryption + +=item 6. + +Edit the source tree to make your changes. A few commands you may find +useful in doing so are listed below. + +To see what files you have changed: + + git status + +To see a line-by-line list of changes: + + git diff + +To revert a file to the original version: + + git checkout path/to/file + +To revert only individual parts of a file: + + git checkout -p path/to/file + +See L for more tips for working with the RT codebase. + +=item 7. + +Check that you have no extraneous changes using C, then commit +your changes: + + git commit -a + +You will be prompted to type your commit message. The first line should +be a short (E 80 character) summary of the changes, followed by a +blank line, followed by a longer description, if necessary. The commit +message should not simply restate the diff of which lines were added and +subtracted, but should rather explain B those changes accomplish, +and B they are desired. + +If your changes are easily split into multiple components, you may wish +to split your changes into more than one commit; simply return to step 6 +and repeat the with the next related change. If your changes are B +related to each other, you should submit them separately; finish step 9, +then start over from step 4. + +=item 8. + +Save your commits to patch files: + + git format-patch @{u} + +This will print out the names of the files as it creates them. + +=item 9. + +Attach these files to an email using your standard email client, and +send it to C. + +=back + +If you have another bug or feature to implement, simply restart the +process at step 4. + +=cut diff --git a/rt/docs/network-diagram.svg b/rt/docs/network-diagram.svg new file mode 100644 index 000000000..cbd3fe1d1 --- /dev/null +++ b/rt/docs/network-diagram.svg @@ -0,0 +1,6095 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Users + + + + + + + + + + + + + + + + + + + + + + + + + + + + Mail server + + + + + + + + + + + + + + + + + + + + + + + + + + + Database server + PostgreSQL, MySQL, Oracle + postfix, exim, qmail,sendmail, Exchange, etc. + + RT webserver + Apache, lighttpd, nginx, etc. + + + + + + + + + + + + + + + + + + + + + + + + + + + External authentication + LDAP, Active Directory, externaldatabase, webauth + New tickets and replies via email to RT → + ← Notification emails from RT + Web interface + Optional authentication source + For small installations, the database server can be on the same server as RT. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Example Request Trackernetwork setup + + + + diff --git a/rt/docs/schema.dot b/rt/docs/schema.dot new file mode 100644 index 000000000..d81ceee12 --- /dev/null +++ b/rt/docs/schema.dot @@ -0,0 +1,99 @@ +digraph g { +graph [ +rankdir = "RL", + concentrate = true, +ratio = auto +]; +node [ +fontsize = "18", +shape = record, fontsize = 18 +]; +edge [ +]; + +"Records" [shape = record, fontsize = 18, label = "(Any RT::Record)" ]; +"Records" -> "Principals" [label = "Creator → id"]; +"ACL" [shape = record, fontsize = 18, label = " \N " ]; +"ACL" -> "Principals" [label="PrincipalId → id"]; +"ACL" -> "Records" [label="ObjectId → id"]; + +"Attachments" [shape = record, fontsize = 18, label = " \N " ]; +"Attachments" -> "Transactions" [label="TransactionId → id"]; +"Attachments" -> "Attachments" [label="Parent → id"]; + +"CachedGroupMembers" [shape = record, fontsize = 18, label = " \N " ]; +"CachedGroupMembers" -> "Groups" [label="GroupId → id", weight=2]; +"CachedGroupMembers" -> "Principals" [label="MemberId → id"]; +"CachedGroupMembers" -> "CachedGroupMembers" [label="Via → id"]; +"CachedGroupMembers" -> "Groups" [label="ImmediateParentId → id"]; + +"CustomFields" [shape = record, fontsize = 18, label = " \N " ]; + +"CustomFieldValues" [shape = record, fontsize = 18, label = " \N " ]; +"CustomFieldValues" -> "CustomFields" [label="CustomField → id"]; + +"GroupMembers" [shape = record, fontsize = 18, label = " \N " ]; +"GroupMembers" -> "Groups" [label="GroupId → id", weight=2]; +"GroupMembers" -> "Principals" [label="MemberId → id", weight = 2]; + +"Groups" [shape = record, fontsize = 18, label = " \N " ]; +"Groups" -> "Principals" [label="id → id"]; + +"Links" [shape = record, fontsize = 18, label = " \N " ]; +"Links" -> "Tickets" [label="LocalBase ⇢ id (usually)", style="dotted"]; +"Links" -> "Tickets" [label="LocalTarget ⇢ id (usually)", style="dotted"]; + +"Principals" [shape = record, fontsize = 18, label = " \N " ]; + +"Attributes" [shape = record, fontsize = 18, label = " \N " ]; +"Attributes" -> "Records" [label="ObjectId → id"]; + +"Queues" [shape = record, fontsize = 18, label = " \N " ]; + +"ScripActions" [shape = record, fontsize = 18, label = " \N " ]; + +"ScripConditions" [shape = record, fontsize = 18, label = " \N " ]; + +"Scrips" [shape = record, fontsize = 18, label = " \N " ]; +"Scrips" -> "ScripConditions" [label="ScripCondition → id"]; +"Scrips" -> "ScripActions" [label="ScripAction → id"]; +"Scrips" -> "Templates" [label="Template → id"]; +"Scrips" -> "Queues" [label="Queue → id"]; + +"Templates" [shape = record, fontsize = 18, label = " \N " ]; +"Templates" -> "Queues" [label ="Queue → id" ]; + +"ObjectCustomFields" [shape = record, fontsize = 18, label = " \N " ]; +"ObjectCustomFields" -> "CustomFields" [label="CustomField → id"]; +"ObjectCustomFields" -> "Records" [label="ObjectId → id"]; + +"ObjectCustomFieldValues" [shape = record, fontsize = 18, label = " \N " ]; +"ObjectCustomFieldValues" -> "CustomFields" [label="CustomField → id"]; +"ObjectCustomFieldValues" -> "Records" [label="ObjectId → id"]; + +"Tickets" [shape = record, fontsize = 18, label = " \N " ]; +"Tickets" -> "Tickets" [label="EffectiveId → id"]; +"Tickets" -> "Principals" [label="Owner → id"]; +"Queues" -> "Tickets" [style="invis"]; +"Tickets" -> "Queues" [label="Queue → id"]; + +"Transactions" [shape = record, fontsize = 18, label = " \N " ]; +"Transactions" -> "Records" [label="ObjectId → id"]; + +"Users" [shape = record, fontsize = 18, label = " \N " ]; + +"Users" -> "Principals" [label="id → id"]; + +// "Classes" [shape = record, fontsize = 18 label = " \N " ]; +// "Articles" [shape = record, fontsize = 18 label = " \N " ]; +// "Articles" -> "Classes" [ label="Class → id"]; +// "Articles" -> "Articles" [ label="Parent → id"]; +// "ObjectClasses" [shape = record, fontsize = 18 label = " \N " ]; +// "ObjectClasses" -> "Records" [label="ObjectId → id"]; +// "ObjectClasses" -> "Classes" [label="Class → id"]; +// "Topics" [shape = record, fontsize = 18 label = " \N " ]; +// "ObjectTopics" [shape = record, fontsize = 18 label = " \N " ]; +// "ObjectTopics" -> "Records" [label="ObjectId → id"]; +// "ObjectTopics" -> "Topics" [label="Topic → id"]; + +} diff --git a/rt/docs/security.pod b/rt/docs/security.pod new file mode 100644 index 000000000..b8650e05d --- /dev/null +++ b/rt/docs/security.pod @@ -0,0 +1,77 @@ +=head1 RT Security + +=head2 Reporting security vulnerabilities in RT + +If you believe you've discovered a security issue in RT, please send an +email to with a detailed description of the +issue, and a secure means to respond to you (such as your PGP public +key). + +More information is available at L. + +=head2 Security tips for running RT + +=over + +=item * + +Protect your RT installation by making it only accessible via SSL. This +will protect against users' passwords being sniffed as they go over the +wire, as well as helping prevent phishing attacks. If you use SSL, you +will need to install some additional Perl libraries so that C +can connect. You can use the C<--enable-ssl-mailgate> command to +configure to automate the installation of these dependencies. This is +documented further in step 10 of the README. + +You should use a certificate signed by a reputable authority, or at very +least a certificate signed by a consistent local CA, which you configure +your local systems to trust. If your SSL certificate is self-signed, it +does little to prevent phishing, as users are trained to accept the +unauthorized certificate. See also the C<--no-verify-ssl> flag to +C. + +=item * + +Be sure to change the password for the C user of RT. The default +password is C. This can be changed via the RT web interface +at: Preferences > About me + + +=item * + +Be sure to protect your F file if it contains database +credentials or other sensitive information. This file only needs to be +readable by RT and your web server. One way to accomplish this is to +make the file readable only by root and the group that RT runs as, and +then make sure your web server is a member of that group. Advanced +configuration may be required if other users have the ability to run +CGIs or access the server where RT is running. + + +=item * + +Be sure to protect your database. If it does not need to talk to the +world, then don't allow it to listen for remote connections. With MySQL +this can be accomplished via C. If you use your +database for other things and must allow remote connections, be sure to +use a strong, hard to guess password for RT. + + +=item * + +Apache, lighttpd, and most other web servers support name based virtual +hosts. When possible, configure RT as a name based virtual host to +raise the bar against DNS rebinding attacks. If you see RT when you +visit http://your.servers.ipaddress.here, it means you are likely not +getting this additional protection. + + +=item * + +Use groups to organize RT permissions. Granting permissions per-user +makes them, in general, more easily over-granted and forgotten, and more +likely to diverge from each other, forming a maintenance hassle. + +=back + +=cut diff --git a/rt/docs/web_deployment.pod b/rt/docs/web_deployment.pod new file mode 100644 index 000000000..65065c5cd --- /dev/null +++ b/rt/docs/web_deployment.pod @@ -0,0 +1,233 @@ +=head1 Setting up the web interface + +As of RT 3.9, RT's web interface speaks PSGI +(L) which lets you use RT with any PSGI-supported web +server (which includes Apache, nginx, lighttpd, etc). + +=head2 Standalone + +The standalone RT web server is backed by a pure-Perl server engine +(L). This standalone server is appropriate for development +and testing, but is not appropriate for production use. + +You should not run this server against port 80 (which is the default port) +because that requires root-level privileges and may conflict with any existing +listeners. So choose a high port (for example 8080) and start the standalone +server with: + + /opt/rt4/sbin/rt-server --port 8080 + +You can also run C with any other PSGI server, for example, +to use L, a high performance preforking server: + + /opt/rt4/sbin/rt-server --server Starman --port 8080 + +B: After you run the standalone server as root, you will need to +remove your C directory, or the non-standalone servers +(Apache, etc), which run as a non-privileged user, will not be able to +write to it and will not work. + + +=head2 Apache + +B: Both C and C are known to break RT. +C will cause RT's CSS and JS to not be loaded, making RT +appear unstyled. C will cache cookies, making users be +spontaneously logged in as other users in the system. + +=head3 mod_fastcgi + + # Tell FastCGI to put its temporary files somewhere sane; this may + # be necessary if your distribution doesn't already set it + #FastCgiIpcDir /tmp + + FastCgiServer /opt/rt4/sbin/rt-server.fcgi -processes 5 -idle-timeout 300 + + + ### Optional apache logs for RT + # Ensure that your log rotation scripts know about these files + # ErrorLog /opt/rt4/var/log/apache2.error + # TransferLog /opt/rt4/var/log/apache2.access + # LogLevel debug + + AddDefaultCharset UTF-8 + + Alias /NoAuth/images/ /opt/rt4/share/html/NoAuth/images/ + ScriptAlias / /opt/rt4/sbin/rt-server.fcgi/ + + DocumentRoot "/opt/rt4/share/html" + + Order allow,deny + Allow from all + + Options +ExecCGI + AddHandler fastcgi-script fcgi + + + +=head3 mod_fcgid + + + ### Optional apache logs for RT + # Ensure that your log rotation scripts know about these files + # ErrorLog /opt/rt4/var/log/apache2.error + # TransferLog /opt/rt4/var/log/apache2.access + # LogLevel debug + + AddDefaultCharset UTF-8 + + Alias /NoAuth/images/ /opt/rt4/share/html/NoAuth/images/ + ScriptAlias / /opt/rt4/sbin/rt-server.fcgi/ + + DocumentRoot "/opt/rt4/share/html" + + Order allow,deny + Allow from all + + Options +ExecCGI + AddHandler fcgid-script fcgi + + + +=head3 mod_perl 2.xx + +B + +B: Due to thread-safety limitations, all timestamps will be +presented in the webserver's default time zone when using the C +and C MPMs; the C<$Timezone> setting and the user's timezone +preference are ignored. We suggest the C MPM or FastCGI +deployment if your privileged users are in a different timezone than the +one the server is configured for. + + + ### Optional apache logs for RT + # ErrorLog /opt/rt4/var/log/apache2.error + # TransferLog /opt/rt4/var/log/apache2.access + # LogLevel debug + + AddDefaultCharset UTF-8 + + DocumentRoot "/opt/rt4/share/html" + + Order allow,deny + Allow from all + + SetHandler modperl + PerlResponseHandler Plack::Handler::Apache2 + PerlSetVar psgi_app /opt/rt4/sbin/rt-server + + + use Plack::Handler::Apache2; + Plack::Handler::Apache2->preload("/opt/rt4/sbin/rt-server"); + + + +=head3 mod_perl 1.xx + +B + +To run RT using mod_perl 1.xx please see L for +configuration examples. + + +=head2 nginx + +C requires that you start RT's fastcgi process externally, for +example using C: + + spawn-fcgi -u www-data -g www-data -a 127.0.0.1 -p 9000 \ + -- /opt/rt4/sbin/rt-server.fcgi + +With the nginx configuration: + + server { + listen 80; + server_name rt.example.com; + access_log /var/log/nginx/access.log; + + location / { + fastcgi_param QUERY_STRING $query_string; + fastcgi_param REQUEST_METHOD $request_method; + fastcgi_param CONTENT_TYPE $content_type; + fastcgi_param CONTENT_LENGTH $content_length; + + fastcgi_param SCRIPT_NAME ""; + fastcgi_param PATH_INFO $uri; + fastcgi_param REQUEST_URI $request_uri; + fastcgi_param DOCUMENT_URI $document_uri; + fastcgi_param DOCUMENT_ROOT $document_root; + fastcgi_param SERVER_PROTOCOL $server_protocol; + + fastcgi_param GATEWAY_INTERFACE CGI/1.1; + fastcgi_param SERVER_SOFTWARE nginx/$nginx_version; + + fastcgi_param REMOTE_ADDR $remote_addr; + fastcgi_param REMOTE_PORT $remote_port; + fastcgi_param SERVER_ADDR $server_addr; + fastcgi_param SERVER_PORT $server_port; + fastcgi_param SERVER_NAME $server_name; + fastcgi_pass 127.0.0.1:9000; + } + + location /NoAuth/images { + root /opt/rt4/share/html; + } + } + + +=head2 lighttpd + + server.modules += ( "mod_fastcgi" ) + $HTTP["host"] =~ "^rt.example.com" { + alias.url = ( + "/NoAuth/images/" => "/opt/rt4/share/html/NoAuth/images/", + ) + $HTTP["url"] !~ "^/NoAuth/images/" { + fastcgi.server = ( + "/" => ( + "rt" => ( + "port" => "9000", + "bin-path" => "/opt/rt4/sbin/rt-server.fcgi", + "check-local" => "disable", + "fix-root-scriptname" => "enable", + ) + ) + ) + } + } + + +=head1 Running RT at /rt rather than / + +First you need to tell RT where it's located by setting C<$WebPath> in your +F: + + # Important: don't include a trailing slash here. Read `perldoc + # etc/RT_Config.pm` for more information. + Set($WebPath, "/rt"); + +Then you need to update your Apache configuration to match. Prefix any RT +related C, C and C directives with C. You +should also make sure C is B set to +C, otherwise RT's source will be served from C. + +For example: if you're using the sample FastCGI config above, you might change +the relevant directives to: + + Alias /rt/NoAuth/images/ /opt/rt4/share/html/NoAuth/images/ + ScriptAlias /rt /opt/rt4/sbin/rt-server.fcgi/ + + # Set DocumentRoot as appropriate for the other content you want to serve + DocumentRoot /var/www + + + ... + + +If you're using the sample mod_perl configuration, you only need to change the +C directive. + +If you're not using Apache, please see L or the web +server's own documentation for configuration examples. + -- cgit v1.2.1 From 43a06151e47d2c59b833cbd8c26d97865ee850b6 Mon Sep 17 00:00:00 2001 From: Ivan Kohler Date: Thu, 7 Jun 2012 00:56:06 -0700 Subject: starting to work... --- rt/docs/README.docs | 2 - rt/docs/Security | 12 - rt/docs/creating_external_custom_fields.pod | 97 -- rt/docs/design_docs/3.3-schema-redesign.txt | 57 - rt/docs/design_docs/CARS | 66 -- rt/docs/design_docs/TransactionTypes.txt | 48 - rt/docs/design_docs/acls | 50 - rt/docs/design_docs/approval_notices | 8 - rt/docs/design_docs/approval_template | 25 - rt/docs/design_docs/cf_search | 72 -- rt/docs/design_docs/cli_spec | 31 - rt/docs/design_docs/cvs_integration | 164 --- rt/docs/design_docs/delegation | 115 -- rt/docs/design_docs/evil_plans | 162 --- .../design_docs/gnupg_details_on_output_formats | 1253 -------------------- rt/docs/design_docs/groups_notes | 88 -- rt/docs/design_docs/link-definitions.txt | 143 --- rt/docs/design_docs/realflow.txt | 191 --- .../recursive_group_membership_algorithm | 109 -- rt/docs/design_docs/rql_parser_machine.graphviz | 35 - rt/docs/design_docs/rt-mvc | 32 - rt/docs/design_docs/ruleset-workflow.txt | 158 --- rt/docs/design_docs/subscription-definitions.txt | 113 -- rt/docs/design_docs/ticket_templates | 16 - rt/docs/design_docs/users | 14 - rt/docs/extending_clickable_links.pod | 157 --- rt/docs/gnupg_integration.pod | 1 - rt/docs/perlcritic.pod | 8 - rt/docs/porting.windows | 24 - rt/docs/queue_subject_tag.pod | 79 -- rt/docs/rt3-schema-relationships.dot | 89 -- rt/docs/templates.pod | 65 - rt/docs/timezones_in_charts.pod | 84 -- rt/docs/using_forms_widgets.pod | 113 -- 34 files changed, 3681 deletions(-) delete mode 100755 rt/docs/README.docs delete mode 100644 rt/docs/Security delete mode 100644 rt/docs/creating_external_custom_fields.pod delete mode 100644 rt/docs/design_docs/3.3-schema-redesign.txt delete mode 100755 rt/docs/design_docs/CARS delete mode 100755 rt/docs/design_docs/TransactionTypes.txt delete mode 100644 rt/docs/design_docs/acls delete mode 100644 rt/docs/design_docs/approval_notices delete mode 100644 rt/docs/design_docs/approval_template delete mode 100644 rt/docs/design_docs/cf_search delete mode 100644 rt/docs/design_docs/cli_spec delete mode 100644 rt/docs/design_docs/cvs_integration delete mode 100644 rt/docs/design_docs/delegation delete mode 100644 rt/docs/design_docs/evil_plans delete mode 100644 rt/docs/design_docs/gnupg_details_on_output_formats delete mode 100644 rt/docs/design_docs/groups_notes delete mode 100644 rt/docs/design_docs/link-definitions.txt delete mode 100644 rt/docs/design_docs/realflow.txt delete mode 100644 rt/docs/design_docs/recursive_group_membership_algorithm delete mode 100644 rt/docs/design_docs/rql_parser_machine.graphviz delete mode 100644 rt/docs/design_docs/rt-mvc delete mode 100644 rt/docs/design_docs/ruleset-workflow.txt delete mode 100755 rt/docs/design_docs/subscription-definitions.txt delete mode 100644 rt/docs/design_docs/ticket_templates delete mode 100644 rt/docs/design_docs/users delete mode 100644 rt/docs/extending_clickable_links.pod delete mode 100644 rt/docs/gnupg_integration.pod delete mode 100644 rt/docs/perlcritic.pod delete mode 100644 rt/docs/porting.windows delete mode 100644 rt/docs/queue_subject_tag.pod delete mode 100644 rt/docs/rt3-schema-relationships.dot delete mode 100644 rt/docs/templates.pod delete mode 100644 rt/docs/timezones_in_charts.pod delete mode 100644 rt/docs/using_forms_widgets.pod (limited to 'rt/docs') diff --git a/rt/docs/README.docs b/rt/docs/README.docs deleted file mode 100755 index 38866b357..000000000 --- a/rt/docs/README.docs +++ /dev/null @@ -1,2 +0,0 @@ -Questions about docs should be sent to the RT Documentation Team (rt-docs@fsck.com) -which is led by Meri. diff --git a/rt/docs/Security b/rt/docs/Security deleted file mode 100644 index 51ddfabdb..000000000 --- a/rt/docs/Security +++ /dev/null @@ -1,12 +0,0 @@ -Security tips for running RT3 - -0 Protect your RT installation by making it only accessible via SSL - -1 Be sure to change the password for the root user of RT. The default password is "password". This can be changed via the RT web interface at: Preferences > About me - -2 Be sure to protect your RT_SiteConfig.pm file if it contains database credentials or other sensitive information. This file only needs to be readable by RT and your web server. One way to accomplish this is to make the file readable only by root and the group that RT runs as, and then make sure your web server is a member of that group. Advanced configuration may be required if other users have the ability to run CGIs or access the server where RT is running. Otherwise, those users may have access to become RT superusers. - -3 Be sure to protect your database. If it does not need to talk to the world, then don't allow it to listen for remote connections. With MySQL this can be accomplished via "skip-networking". If you use your database for other things and must allow remote connections, be sure to use a strong, hard to guess password for RT. - -4 Apache, lighttpd, and most other web servers support name based virtual hosts. When possible, configure RT as a name based virtual host to raise the bar against DNS rebinding attacks. Note: If when you visit http://your.servers.ipaddress.here you see RT, it means you are not likely getting this additional protection. - diff --git a/rt/docs/creating_external_custom_fields.pod b/rt/docs/creating_external_custom_fields.pod deleted file mode 100644 index f8eca44fb..000000000 --- a/rt/docs/creating_external_custom_fields.pod +++ /dev/null @@ -1,97 +0,0 @@ -=head1 External custom fields - -=head2 Description - -C is extension to custom fields that allow -you to define CF with a dynamic list of values. Loading values into -this custom fields requires writing a little Perl code to fetch the -data from the external source; the code that we added to RT 3.7 -allows it to load data from arbitrary external sources. - -=head2 Introduction into writing source of values - -For each type of data source that you want, you'll need to put a file -in F (or equivilent if you -installed RT someplace other than F). To get a sense of the -code that you'll need to write, take a look at the code in -L for a simple example -which just uses RT's API to pull in a list of RT's groups. - -Running C will -show you the documentation for the API that needs to be fulfilled, by -copying and editing the C example is probably a fine place to -start. - -Later in this doc we'll describe the example a little bit more. - -=head2 Configuration - -After the custom code is written, you need to tell RT about its -existence by adding something like following to your RT_SiteConfig.pm: -Set(@CustomFieldValuesSources, "RT::CustomFieldValues::MySource"); - -The value in quotes should be the name of the class that you created. - -Stop and start your web server to enable any config changes. Open the web interface with -as an administrative user (such as root) create new custom field. In order to use -a custom source of values, you should select a custom field type -that lets users pick values from a list, for example it could be C box using: - <& /Widgets/Form/Integer:InputOnly, - Name => 'NameOfInputElement', - &> - -In such a simple case you even can avoid processing. Yeah, most probably -you want to check if value is really integer, but these widgets don't -do validation for you, but they are more about fetching values from -hash of arguments, showing these values to user and preserving state -of value between form reloads (see below). - -=head2 Processing - -Processing is required when you use L, -such as Default, Multiple or Alternative. - -To process arguments of a request you have to do the following: - $ARGS{'NameOfInputElement'} = $m->comp( - '/Widgets/Form/Integer:Process', - Arguments => \%ARGS, - Name => 'NameOfInputElement', - ); - -The method returns processed value in canonical form. For different widgets -a canonical form is different and depends on activated features, so you must -always activate the same features during showing a widget and processing -results. - -=head2 Extendent features - -=head3 Default value - -If C argument is true then widgets expect that there is some -default value for argument if user fills nothing. 'Nothing' in each -widget is different, for example in select box it's special option -which is always the first one, in integer box string '' means empty -value, but boolean box uses radio buttons in this case with three -options: Yes, No and Default. - -Each widget that supports C feature as well has C and -C arguments. - -=head4 Processing and showing with activated Default feature - -When this option is activated then C method returns undef -value if user selected default value. So for integer box it's empty -string and so on. - -As well when you show a widget you should pass undef as C -to inform widget that the current value is default one. - -As all methods of a widget are consistent in this behaviour so you -shouldn't care much about that, but this allows you to implement -custom actions if processing returned undef, for example delete user's -preference record instead of updating it (default value may change later to). - -=head4 C when C is not active - -DefaultValue argument is still actual in the Process method even if -C is not true. This argument defines intial value. If value -of a key in Arguments is not defined then it's treated as intial state -and the method returns default value. - -=head3 Multiple and Alternative - -These options are only supported by the select widget. - -TODO: Add more info - -=head2 Implementation details - -=head3 Boolean widget - -This widget a little bit tricky. When you use Default option then -things are simple and you see three radio buttons, but in other -case we use a checkbox. But as you know browsers don't pass unchecked -boxes to server, so arguments of a request has no entry for them. - -In the latter case it's hard to figure out case when user unselected -value. Imagine form with a checkbox, you want show it checked by -default and as well form is reloadable (like Reply forms that have -"Add Another File" buttons). User uncheck the box and then upload -file, in this case you want to show user's choice instead of default, -but browser doesn't send any value and you can not figure out if -it's initial state or page reload. To solve this problem we use magic -hidden input field with the same name as the box and value equal to -zero (0). Mason folds arguments with the same name into array refs, so -we get 0 if box is unchecked and [0, 1] if box is checked. An array -reference is true value and 0 is defined value so we know that it's -not initial state and avoid switching back to default. As well this -trick works good in a case when you want show a link to a page and -define default choice for some boolean argument, you don't need -to set argument twice, you just set it to true value (for ex. 1) and -things just work. - -- cgit v1.2.1 From c24d6e2242ae0e026684b8f95decf156aba6e75e Mon Sep 17 00:00:00 2001 From: Ivan Kohler Date: Thu, 7 Jun 2012 16:55:45 -0700 Subject: rt 4.0.6 --- rt/docs/UPGRADING-4.0 | 23 +++++++++++++++++++++++ rt/docs/hacking.pod | 10 +++++----- rt/docs/security.pod | 15 +++++++++++++++ rt/docs/web_deployment.pod | 13 +++++++++++++ 4 files changed, 56 insertions(+), 5 deletions(-) (limited to 'rt/docs') diff --git a/rt/docs/UPGRADING-4.0 b/rt/docs/UPGRADING-4.0 index a9301348e..4b64d2e72 100644 --- a/rt/docs/UPGRADING-4.0 +++ b/rt/docs/UPGRADING-4.0 @@ -106,3 +106,26 @@ with database level. ******* + +UPGRADING FROM 4.0.5 and earlier - Changes: + +The fix for an attribute truncation bug on MySQL requires a small ALTER TABLE. +Be sure you run `make upgrade-database` to apply this change automatically. +The bug primarily manifested when uploading large logos in the theme editor on +MySQL. Refer to etc/upgrade/4.0.6/schema.mysql for the actual ALTER TABLE that +will be run. + +******* +The web-based query builder now uses Queue limits to restrict the set of +displayed statuses and owners. As part of this change, the %cfqueues +parameter was renamed to %Queues; if you have local modifications to any +of the following Mason templates, this feature will not function +correctly: + + share/html/Elements/SelectOwner + share/html/Elements/SelectStatus + share/html/Prefs/Search.html + share/html/Search/Build.html + share/html/Search/Elements/BuildFormatString + share/html/Search/Elements/PickCFs + share/html/Search/Elements/PickCriteria diff --git a/rt/docs/hacking.pod b/rt/docs/hacking.pod index 8aa84fd01..396c5623d 100644 --- a/rt/docs/hacking.pod +++ b/rt/docs/hacking.pod @@ -186,11 +186,11 @@ which will be significantly faster: make test-parallel -The C<*-trunk> and C branches are expected to be passing always -be passing all tests. While it is acceptable to break tests in an -intermediate commit, a branch which does not pass tests will not be -merged. Ideally, commits which fix a bug should also include a testcase -which fails before the fix and succeeds after. +The C<*-trunk> and C branches are expected to always be passing +all tests. While it is acceptable to break tests in an intermediate +commit, a branch which does not pass tests will not be merged. Ideally, +commits which fix a bug should also include a testcase which fails +before the fix and succeeds after. diff --git a/rt/docs/security.pod b/rt/docs/security.pod index b8650e05d..620f8687c 100644 --- a/rt/docs/security.pod +++ b/rt/docs/security.pod @@ -9,6 +9,21 @@ key). More information is available at L. + +=head2 RT's security process + +After a security vulnerability is reported to Best Practical and +verified, we attempt to resolve it in as timely a fashion as possible. +Best Practical support customers will be notified before we disclose the +information to the public. All security announcements will be sent to +C, which includes +C and C. + +As the tests for security vulnerabilities are often nearly identical to +working exploits, sensitive tests will be embargoed for a period of six +months before being added to the public RT repository. + + =head2 Security tips for running RT =over diff --git a/rt/docs/web_deployment.pod b/rt/docs/web_deployment.pod index 65065c5cd..4c3f73fb5 100644 --- a/rt/docs/web_deployment.pod +++ b/rt/docs/web_deployment.pod @@ -67,6 +67,19 @@ spontaneously logged in as other users in the system. =head3 mod_fcgid +B: Before mod_fcgid 2.3.6, the maximum request size was 1GB. +Starting in 2.3.6, this is now 128Kb. This is unlikely to be large +enough for any RT install that handles attachments. You can read more +about FcgidMaxRequestLen at +L + +Most distributions will have a mod_fcgid.conf or similar file with +mod_fcgid configurations and you should add: + + FcgidMaxRequestLen 1073741824 + +to return to the old default. + ### Optional apache logs for RT # Ensure that your log rotation scripts know about these files -- cgit v1.2.1