<chapter id="configfile">
<title>Config File</title>
<para>
OTRS has many config options. There are two config files. Kernel/Config.pm and
Kernel/Config/Defaults.pm. 
</para>

<para>
Kernel/Config/Defaults.pm is the default config file which should not be changed. 
You will find all possible config options in this file. Is quite simple to read.
</para>

<para>
Kernel/Config.pm.dist is the example file for Kernel/Config.pm (custom config file) 
which must be copied (cp Kernel/Config.pm.dist Kernel/Config.pm).
</para>

<para>
How it works! The Kernel/Config/Defaults.pm (default config settings) is loaded at 
first, then the Kernel/Config.pm (custom config file). So if you want to change the 
default config settings, copy (copy and paste) the needed options from 
Kernel/Config/Defaults.pm into Kernel/Config.pm and change the values like you want. 
</para>

<para>
Now we will descripe some config features in this chapter (of course not all!).
</para>

<section id="configfile-tickethook">
<title>TicketHook</title>
<para>
Your can configure the value of the TicketHook which is the first part of the subject of each e-mail (e.g. [MyTicket: 007]).
</para>
<example>
<title>Kernel/Config.pm - TicketHook</title>
<programlisting>
[...]
    # TicketHook
    # (To set the Ticket identifier. Some people want to  
    # set this to e. g. 'Call#', 'MyTicket#' or 'Ticket#'.)     
    $Self->{TicketHook} = 'Ticket#',              
[...]
</programlisting>
</example>
<para>
Note: Don't use only 2-character like 'TN', because MS Outlook is replacing 
"TN: 54968797" with "RE: 54968797" (any 2-character with :) and then you 
will run in trouble. 
</para>
</section>

<section id="configfile-fqdn">
<title>FQDN</title>
<para>
The OTRS full qualified domain name. Will be used for email messages id's.
</para>
<example>
<title>Kernel/Config.pm - FQDN</title>
<programlisting>
[...]
    # FQDN
    # (Full qualified domain name of your system.)
    $Self->{FQDN} = 'yourhost.example.com';
[...]
</programlisting>
</example>
</section>

<section id="configfile-utf8">
<title>utf-8</title>
<para>
OTRS is able to store and work with unicode utf-8. Just set the default
charset to utf-8 and OTRS works in force utf-8 mode (frontend and backend).
</para>
<example>
<title>Kernel/Config.pm - utf-8</title>
<programlisting>
[...]
    # default charset
    # (default frontend charset - "utf-8" is a multi chatset for all possible 
    # charsets - e. g. "iso-8859-1" is also possible for single charset) 
    # [default: iso-8859-1] 
#    $Self->{DefaultCharset} = 'iso-8859-1';
    $Self->{DefaultCharset} = 'utf-8';
[...]
</programlisting>
</example>
</section>

<section id="configfile-log">
<title>Log</title>
<para>
The OTRS log method. 
</para>
<example>
<title>Kernel/Config.pm - LogModule</title>
<programlisting>
[...]
    # ----------------------------------------------------#
    # log settings                                        #
    # ----------------------------------------------------#

    # LogModule
    # (log backend module)
    $Self->{LogModule} = 'Kernel::System::Log::SysLog';
#    $Self->{LogModule} = 'Kernel::System::Log::File';

    # param for LogModule Kernel::System::Log::File (required!)
#    $Self->{'LogModule::LogFile'} = '/tmp/otrs.log'; 
    # param if the date (yyyy-mm) should be added as suffix to 
    # logfile [0|1]
#    $Self->{'LogModule::LogFile::Date'} = 0;
[...]
</programlisting>
</example>
</section>

<section id="configfile-checkemail">
<title>Check Email Options</title>
<para>
There are two options to check the used emails in the OTRS frontend.
</para>
<para>
<example>
<title>Kernel/Config.pm - CheckEmailAddresses</title>
<programlisting>
[...]
    # CheckEmailAddresses
    # (Check syntax of used email addresses)
    $Self->{CheckEmailAddresses} = 1;
[...]
</programlisting>
</example>

<example>
<title>Kernel/Config.pm - CheckMXRecord</title>
<programlisting>
[...]
    # CheckMXRecord
    # (Check mx recorde of used email addresses)
    $Self->{CheckMXRecord} = 1;
[...]
</programlisting>
</example>
Disable this if you use OTRS in an network without external DNS lookup.
Or you can't send emails via the agent interface.
</para>
</section>

<section id="configfile-postmaster"> 
<title>Max. Postmaster email</title> 
<para> 
OTRS is able to send automatically email replies. So it's possibe to create 
an email loop (of course we check bulk headers but other strange systems may not!). 
</para>
<example>
<title>Kernel/Config.pm - PostmasterMaxEmails</title>
<programlisting>
[...]
    # PostmasterMaxEmails
    # (Max post master daemon email to own email-address a day.
    # Loop-Protection!) [default: 40]
    $Self->{PostmasterMaxEmails} = 40;
[...]
</programlisting>
</example>
</section>

<section id="configfile-ticketnumberformat">
<title>Ticket number format</title>
<para> 
You can choose between four different OTRS formats. AutoIncrement is default. 
</para>
<example>
<title>Kernel/Config.pm - TicketNumberGenerator</title>
<programlisting>
[...] 
    # TicketNumberGenerator 
    # 
    # Kernel::System::Ticket::Number::AutoIncrement (default) --> auto increment 
    #   ticket numbers "SystemID.Counter" like 1010138 and 1010139.
    #
    # Kernel::System::Ticket::Number::Date --> ticket numbers with date 
    #   "Year.Month.Day.SystemID.Counter" like 200206231010138 and 200206231010139.
    #
    # Kernel::System::Ticket::Number::DateChecksum --> ticket numbers with date and 
    #   check sum the counter will be rotated daily (my favorite) 
    #   "Year.Month.Day.SystemID.Counter.CheckSum" like 2002070110101520 and 2002070110101535.
    #
    # Kernel::System::Ticket::Number::Random -->
    #   random ticket numbers "SystemID.Random" like 100057866352 and 103745394596.

    $Self->{TicketNumberGenerator} = 'Kernel::System::Ticket::Number::AutoIncrement';
[...]
</programlisting>
</example>
<para>
You can also create a new (your own) module. The module needs just two functions  
(the whole abstraction). "CreateTicketNr()" to generate a new ticket number and  
"GetTNByString()" to get a ticket number by string. 
</para>
<para>
A nice example is the <ulink url="http://otrs.org/cgi-bin/cvsweb.cgi/otrs/Kernel/System/Ticket/Number/Random.pm">Kernel::System::Ticket::Number::Random</ulink> module.
</para>
</section>


<section id="configfile-dbstuff">
<title>Database settings</title>
<example>
<title>Kernel/Config.pm - Database settings</title>
<programlisting>
[...]
    # DatabaseHost
    # (The database host.)
    $Self->{DatabaseHost} = 'localhost';

    # Database
    # (The database name.)
    $Self->{Database} = 'otrs';

    # DatabaseUser
    # (The database user.)
    $Self->{DatabaseUser} = 'otrs';

    # DatabasePw
    # (The password of database user.)
    $Self->{DatabasePw} = 'some-pass';

    # DatabaseDSN
    # (The database DSN for MySQL ==> more: "man DBD::mysql") 
    $Self->{DatabaseDSN} = "DBI:mysql:database=$Self->{Database};host=$Self->{DatabaseHost};";

    # (The database DSN for PostgrSQL ==> more: "man DBD::Pg") 
    #$Self->{DatabaseDSN} = "DBI:Pg:dbname=$Self->{Database};";
[...]
</programlisting>
</example>
</section>

<section id="configfile-asp">
<title>ASP (Application Service Provider) options</title>
<para>
Should the agent be able to move tickets into queue which it isn't member of the group
(Helpfully if you use OTRS in ASP (Application Service Provider) mode).
</para>
<example>
<title>Kernel/Config.pm - ChangeOwnerToEveryone</title>
<programlisting>
[...]
    # ChangeOwnerToEveryone -> useful for ASP
    # (Possible to change owner of ticket ot everyone) [0|1]
    $Self->{ChangeOwnerToEveryone} = 0;
[...]
</programlisting>
</example>
</section>

<section id="configfile-customqueue">
<title>Custom Queue</title>
<para>
Some people want to set the "Custom Queue" name (The queue of your favorite queues).
</para>
<example>
<title>Kernel/Config.pm - Custom Queue</title>
<programlisting>
[...]
    # CustomQueue
    # (The name of custom queue.)
    $Self->{CustomQueue} = 'PersonalQueue';
[...]
</programlisting>
</example>
</section>

<section id="configfile-freetext">
<title>Ticket Free Text</title>
<para>
It's possible to set tags to tickets like Key:Product and Value:Pizza.
If a ticket free text is set, then it will be shown in the zoom and queue view.
It's possible to set up to 8 Key:Value Tags for each ticket.
Of course, it's possible to use it in ticket search or generic agent.
</para>
<para>
If you want, set default values for this. If you don't set default values, the 
the agent can set this tags free.
</para>
<example>
<title>Kernel/Config.pm - TicketFree(Key|Text)(1..8)</title>
<programlisting>
[...]
    # --------------------------------------------------- #
    # TicketFreeText                                      #
    # (define free text options for frontend)             #
    # --------------------------------------------------- #
    $Self->{"TicketFreeKey1"} = {
        '' => '-',
        'Product' => 'Product',
    };
    $Self->{"TicketFreeText1"} = {
        '' => '-',
        'PC' => 'PC',
        'Notebook' => 'Notebook',
        'LCD' => 'LCD',
        'Phone' => 'Phone',
    };
    $Self->{"TicketFreeKey2"} = {
        '' => '-',
        'Support' => 'Support',
    };
[...]
</programlisting>
</example>
</section>

<section id="configfile-queuelisttype">
<title>QueueListType</title>
<para>
Do configure the queue selection in your system. Options are 'tree' (which is default) and 'list'.
</para>
<para>
Tree:
<programlisting>
QueueA 
  Queue1
  Queue2
  Queue3
QueueB
  Queue1 
    Queue-a 
    Queue-b 
    Queue-c 
    Queue-d 
  Queue2
    Queue-a 
    Queue-b 
QueueC
  Queue1 
  Queue2
</programlisting>
</para>
<para>
List:
<programlisting>
QueueA
QueueA::Queue1
QueueA::Queue2
QueueA::Queue3
QueueB
QueueB::Queue1
QueueB::Queue2
</programlisting>
</para>
<example>
<title>Kernel/Config.pm - QueueListType</title>
<programlisting>
[...]
    # QueueListType
    # (show queues in system as tree or as list) [tree|list]
    $Self->{QueueListType} = 'tree';
[...]
</programlisting>
</example>
</section>

<section id="configfile-customer-panel">
<title>Customer Panel</title>
<para>
There are config option for the customer panel (http://host/otrs/customer.pl).
</para>
<example>
<title>Kernel/Config.pm - Customer Panel</title>
<programlisting>
[...]
    # CustomerGroupSupport (0 = compat. to OTRS 1.1 or lower)
    # (if this is 1, then you need to set the group &lt;-&gt; customer user
    # relations (ro/rw)! http://host/otrs/index.pl?Action=AdminCustomerUserGroup
    # otherway, each user is ro/rw in each group!)
    $Self->{CustomerGroupSupport} = 0;

    # CustomerGroupAlwaysGroups 
    # (if CustomerGroupSupport is true and you don't want to manage
    # each customer user for this groups, then put the groups
    # for all customer user in there)
    $Self->{CustomerGroupAlwaysGroups} = ['users', 'info'];

    # --------------------------------------------------- #
    # login and logout settings                           #
    # --------------------------------------------------- #
    # CustomerPanelLoginURL
    # (If this is anything other than '', then it is assumed to be the
    # URL of an alternate login screen which will be used in place of 
    # the default one.)
    $Self->{CustomerPanelLoginURL} = '';
#    $Self->{CustomerPanelLoginURL} = 'http://host.example.com/cgi-bin/login.pl';

    # CustomerPanelLogoutURL
    # (If this is anything other than '', it is assumed to be the URL
    # of an alternate logout page which users will be sent to when they
    # logout.)
    $Self->{CustomerPanelLogoutURL} = '';
#    $Self->{CustomerPanelLogoutURL} = 'http://host.example.com/cgi-bin/login.pl';

    # CustomerPanelLostPassword
    # (use lost passowrd feature)
    $Self->{CustomerPanelLostPassword} = 1;

    # CustomerPanelCreateAccount
    # (use create cutomer account self feature)
    $Self->{CustomerPanelCreateAccount} = 1;

    # CustomerPriority
    # (If the customer can set the ticket priority)
    $Self->{CustomerPriority} = 1;
    # CustomerDefaultPriority
    # (default priority of new customer tickets)
    $Self->{CustomerDefaultPriority} = '3 normal';

    # CustomerNextScreenAfterNewTicket
#    $Self->{CustomerNextScreenAfterNewTicket} = 'CustomerZoom';
    $Self->{CustomerNextScreenAfterNewTicket} = 'CustomerTicketOverView';

    # CustomerPanelSelectionType 
    # (To: seection type. Queue => show all queues, SystemAddress => show all system 
    # addresses;) [Queue|SystemAddress]
    $Self->{CustomerPanelSelectionType} = 'Queue';
#    $Self->{CustomerPanelSelectionType} = 'SystemAddress';

    # CustomerPanelSelectionString
    # (String for To: selection.) 
    # use this for CustomerPanelSelectionType = Queue
#    $Self-&gt;{CustomerPanelSelectionString} = 'Queue: &lt;Queue&gt; - &lt;QueueComment&gt;';
    $Self-&gt;{CustomerPanelSelectionString} = '&lt;Queue&gt;';
    # use this for CustomerPanelSelectionType = SystemAddress
#    $Self-&gt;{CustomerPanelSelectionString} = '&lt;Realname&gt; &lt;&lt;Email&gt;&gt; - Queue: &lt;Queue&gt; - &lt;QueueComment&gt;';

    # CustomerPanelOwnSelection
    # (If this is in use, "just this selection is valid" for the CustomMessage.)
#    $Self->{CustomerPanelOwnSelection} = { 
#        # QueueID => String
#        '1' => 'First Queue!',
#        '2' => 'Second Queue!',
#    };

    # --------------------------------------------------- #
    # notification email about new password               #
    # --------------------------------------------------- #
    $Self-&gt;{CustomerPanelSubjectLostPassword} = 'New OTRS Password!';
    $Self-&gt;{CustomerPanelBodyLostPassword} = "
Hi &lt;OTRS_USERFIRSTNAME&gt;,

you or someone impersonating you has requested to change your OTRS
password.  

New Password: &lt;OTRS_NEWPW&gt;

&lt;OTRS_CONFIG_HttpType&gt;://&lt;OTRS_CONFIG_FQDN&gt;/&lt;OTRS_CONFIG_ScriptAlias&gt;customer.pl

Your OTRS Notification Master
";
    # --------------------------------------------------- #
    # notification email about new account                #
    # --------------------------------------------------- #
    $Self-&gt;{CustomerPanelSubjectNewAccount} = 'New OTRS Account!';
    $Self-&gt;{CustomerPanelBodyNewAccount} = "
Hi &lt;OTRS_USERFIRSTNAME&gt;,

you or someone impersonating you has created a new OTRS account for
you (&lt;OTRS_USERFIRSTNAME&gt; &lt;OTRS_USERLASTNAME&gt;).
    
Login: &lt;OTRS_USERLOGIN&gt;
Password: &lt;OTRS_USERPASSWORD&gt;

&lt;OTRS_CONFIG_HttpType&gt;://&lt;OTRS_CONFIG_FQDN&gt;/&lt;OTRS_CONFIG_ScriptAlias&gt;customer.pl

Your OTRS Notification Master
";

[...]
</programlisting>
</example>
</section>

<section id="configfile-session">
<title>Session management</title>
<para>
The OTRS session management. 
</para>
<example>
<title>Kernel/Config.pm - Session management</title>
<programlisting>
[...]
    # ----------------------------------------------------#
    # session settings                                    #
    # ----------------------------------------------------#

    # SessionModule (replace old SessionDriver!!!)
    # (How should be the session-data stored? 
    # Advantage of DB is that you can split the 
    # Frontendserver from the DB-Server. fs is faster.)
    $Self->{SessionModule} = 'Kernel::System::AuthSession::DB';
#    $Self->{SessionModule} = 'Kernel::System::AuthSession::FS';
#    $Self->{SessionModule} = 'Kernel::System::AuthSession::IPC';
    
    # SessionCheckRemoteIP 
    # (If the application is used via a proxy-farm then the 
    # remote ip address is mostly different. In this case,
    # turn of the CheckRemoteID. ) [1|0] 
    $Self->{SessionCheckRemoteIP} = 1;

    # SessionDeleteIfNotRemoteID
    # (Delete session if the session id is used with an 
    # invalied remote IP?) [0|1]
    $Self->{SessionDeleteIfNotRemoteID} = 1;

    # SessionMaxTime
    # (Max valid time of one session id in second (8h = 28800).)
    $Self->{SessionMaxTime} = 28800;

    # SessionDeleteIfTimeToOld
    # (Delete session's witch are requested and to old?) [0|1]
    $Self->{SessionDeleteIfTimeToOld} = 1;

    # SessionUseCookie
    # (Should the session management use html cookies?
    # It's more comfortable to send links -==> if you have a valid 
    # session, you don't have to login again.) [0|1]
    # Note: If the client browser disabled html cookies, the system
    # will work as usual, append SessionID to links!
    $Self->{SessionUseCookie} = 1;

    # SessionUseCookieAfterBrowserClose
    # (store cookies in browser after closing a browser) [0|1]
    $Self->{SessionUseCookieAfterBrowserClose} = 0;
[...]
</programlisting>
</example>
</section>

<section id="configfile-login-logout">
<title>URL login and logout settings</title>
<para>
</para>
<example>
<title>Kernel/Config.pm - URL login and logout settings</title>
<programlisting>
[...]
    # ----------------------------------------------------#
    # URL login and logout settings                       #
    # ----------------------------------------------------#

    # LoginURL
    # (If this is anything other than '', then it is assumed to be the
    # URL of an alternate login screen which will be used in place of 
    # the default one.)
    $Self->{LoginURL} = '';
#    $Self->{LoginURL} = 'http://host.example.com/cgi-bin/login.pl';

    # LogoutURL
    # (If this is anything other than '', it is assumed to be the URL
    # of an alternate logout page which users will be sent to when they
    # logout.)
    $Self->{LogoutURL} = '';
#    $Self->{LogoutURL} = 'http://host.example.com/cgi-bin/login.pl';
[...]
</programlisting>
</example>
</section>

<section id="configfile-agentarea">
<title>agent area default settings</title>
<para>
</para>
<example>
<title>Kernel/Config.pm - agent area default settings</title>
<programlisting>
[...]
    # ----------------------------------------------------#
    # agent area default settings                         #
    # ----------------------------------------------------#

    # ViewableTickets
    # (The default viewable tickets a page.)
    $Self->{ViewableTickets} = 25;

    # ViewableTicketLines
    # (Max viewable ticket lines in the QueueView.)
    $Self->{ViewableTicketLines} = 18;

    # ViewableTicketLinesZoom
    # (Max viewable ticket lines in the QueueZoom.)
    $Self->{ViewableTicketLinesZoom} = 6000;

    # MaxLimit
    # (Max viewable tickets a page.)
    $Self->{MaxLimit} = 150;

    # RefreshOptions
    # (Refresh option list for preferences)
    $Self->{RefreshOptions} = {
        '' => 'off',
        2  => ' 2 minutes',
        5  => ' 5 minutes',
        7  => ' 7 minutes',
        10 => '10 minutes',
        15 => '15 minutes',
    };

    # Highligh*
    # (Set the age and the color for highlighting of old queue
    # in the QueueView.)
    # highlight age1 in min
    $Self->{HighlightAge1} = 1440;
    $Self->{HighlightColor1} = 'orange';
    # highlight age2 in min
    $Self->{HighlightAge2} = 2880;
    $Self->{HighlightColor2} = 'red';

    # ----------------------------------------------------#
    # AgentUtil                                           #
    # ----------------------------------------------------#

    # default limit for Tn search
    $Self->{SearchLimitTn} = 20;

    # default limit for Txt search
    $Self->{SearchLimitTxt} = 20;

    # viewable ticket lines by search util 
    $Self->{ViewableTicketLinesBySearch} = 15;

    # ----------------------------------------------------#
    # Ticket stuff                                        #
    # (Viewable tickets in queue view)                    #
    # ----------------------------------------------------#
    # ViewableLocks 
    # default: ["'unlock'", "'tmp_lock'"]
    $Self->{ViewableLocks} = ["'unlock'", "'tmp_lock'"];

    # ViewableStateType 
    # (see http://yourhost/otrs/index.pl?Action=AdminState -> StateType)
    $Self->{ViewableStateType} = ['new', 'open', 'pending'];

    # ViewableSenderTypes 
    #  default:  ["'customer'"]
    $Self->{ViewableSenderTypes} = ["'customer'"];
[...]
</programlisting>
</example>
</section>

<section id="configfile-spell">
<title>SpellChecker</title>
<para>
The OTRS is able to use a spell checker like 
<ulink url="http://fmg-www.cs.ucla.edu/fmg-members/geoff/ispell.html">ispell</ulink> 
or <ulink url="http://aspell.sourceforge.net/">aspell</ulink>.
</para>
<para>
<example>
<title>Kernel/Config.pm - SpellChecker</title>
<programlisting>
[...]
    # SpellChecker
    # (If ispell or aspell is available, then we will provide a spelling
    # checker) 
#    $Self->{SpellChecker} = '';
    $Self->{SpellChecker} = '/usr/bin/ispell';
    $Self->{SpellCheckerDictDefault} = 'english';

    # SpellCheckerIgnore
    # (A list of ignored words.)
    $Self->{SpellCheckerIgnore} = ['www', 'webmail', 'https', 'http', 'html'];
[...]
</programlisting>
</example>
</para>
<para>
Possible agent dictionaries.
<example>
<title>Kernel/Config.pm - SpellChecker - Agent Preferences</title>
<programlisting>
[...]
    $Self->{PreferencesGroups}->{SpellDict} = {
        Colum => 'Other Options',
        Label => 'Spelling Dictionary',
        Desc => 'Select your default spelling dictionary.',
        Type => 'Generic',
        Data => {
            # installed dict catalog (check your insalled catalogues, 
            # e. g. deutsch -=> german!)
            # dict => frontend
            'english' => 'English',
            'deutsch' => 'Deutsch',
        },
        PrefKey => 'UserSpellDict',
        Activ => 1,
    };
[...]
</programlisting>
</example>
</para>
<para>
Maybe you want that the answer to the customer must be spell checked.
<example>
<title>Kernel/Config.pm - SpellChecker - Must be spell checked</title>
<programlisting>
    # FrontendNeedSpellCheck
    # (compose message must be spell checked)
    $Self->{FrontendNeedSpellCheck} = 0;
</programlisting>
</example>
</para>
</section>

<section id="configfile-responsef">
<title>Response Format (compose answer)</title>
<para>
The OTRS is able to configure the format of std. responses by composing 
answers in the agent interface.
</para>
<para>
<example>
<title>Kernel/Config.pm - ResponseFormat (unix_style)</title>
<programlisting>
[...]
    # unix_style (default)
    $Self->{ResponseFormat} = '$Data{"Salutation"}
$Data{"OrigFrom"} $Text{"wrote"}:
$Data{"Body"}
    
$Data{"StdResponse"}

$Data{"Signature"}
';

[...]
</programlisting>
</example>
</para>
<para>
If you want to change it to ms-style use the following
<example>
<title>Kernel/Config.pm - ResponseFormat (ms_style)</title>
<programlisting>
[...]
    # ms_style
    $Self->{ResponseFormat} = '$Data{"Salutation"}
    
$Data{"StdResponse"}

$Data{"Signature"}

$Data{"OrigFrom"} $Text{"wrote"}:
$Data{"Body"}

';
[...]
</programlisting>
</example>
</para>
</section>

</chapter>
