tc-config-reference.xml

<?xml version="1.0" encoding="UTF-8" ?>
<!--

    All content copyright (c) 2003-2021 Terracotta, Inc., except as may otherwise be noted in a separate copyright notice.  All rights reserved.

-->
<!-- tc-config-reference.xml

This Terracotta configuration file includes
an example and description of every permitted element,
most of which are optional. Required elements are
marked with a (REQUIRED) notation.
-->

<tc:tc-config xmlns:tc="http://www.terracotta.org/config"
              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    >

  <tc-properties>

    <!--
        The optional <tc-properties> block contains tuning 
        properties for the Terracotta cluster. This block is inserted at the
        beginning of the Terracotta configuration file.
        
     
        The properties defined here override default tc.properties but they
        are overridden by those found in a local tc.properties file and by
        those defined using system properties. The order of precedence,
        beginning with the source having least precedence, is:
     
        1. Default tc.properties file located in tc.jar
        2. <tc-properties> block in the Terracotta configuration file
        3. Local tc.properties file
        4. Properties defined using Java system properties
    -->

    <property name="l2.nha.dirtydb.autoDelete" value="true"/>
    <property name="l1.cachemanager.enabled" value="true"/>
    <property name="logging.maxLogFileSize" value="1024"/>
  </tc-properties>


  <!--
      This section defines the servers present in your Terracotta system. You can
      omit this section entirely, in which case it behaves as if there's a
      single server with all values set at their default. You can include exactly
      one server entry, or if you're going to run multiple
      servers for failover, you can include multiple servers.
   
      If you include more than one server, each server needs to know
      which configuration it to use. If you name your servers
      according to the host that they run on (and no host contains more than
      one server), your servers find the hostname automatically.
      
      If you name your servers differently (and there is more than one 'server' 
      element), pass the command-line option "-n <name>" to the start-tc-server script,
      specifying the name of a server configuration from this file.
  -->
  <servers>

    <!-- NOTE: The "servers" element can contain either a list of: 

         <server> elements
    
         *OR* 

         a list of <mirror-group> elements that contain <server> elements

         but not BOTH -->

    <!-- You only need to define <mirror-group>s if configuring an active-active terracotta server array -->
      
    <!-- For example: -->

    <!-- <server/> -->
    <!-- <server/> -->

    <!-- *OR* -->

    <!-- <mirror-group> -->
    <!--   <server/> -->
    <!--   <server/> -->
    <!-- </mirror-group> -->

    <!-- The following <server> element highlights the configuration of a single server element: -->
            
    <!-- The host, symbolic name, and bind address of the server, where host defaults to "%i" (the machine's
         IP address), name defaults to "host:tsa-port" and bind address defaults to "0.0.0.0".
         Expansion parameters can be used in all attributes. -->
    <server host="my.host.name" name="My Server Name" bind="0.0.0.0">
      
      <!-- Where should the server store its persistent data? This value undergoes parameter substitution
           before being used. This allows you to use placeholders like '%h' (for the hostname)
           or '%(com.mycompany.propname)' (to substitute in the value of
           Java system property 'com.mycompany.propname'). Thus, a value
           of 'server-data-%h' would expand to 'server-data-my.host.name' if 
           running on host 'my.host.name'.

           If this is a relative path, it is interpreted relative to
           the current working directory of the server (that is, the directory
           you were in when you started the server). It is recommended that
           you specify an absolute path.
           
           Default: 'data', which places the 'data' directory in the
           directory you were in when you invoked 'start-tc-server'.
      -->
      <data>/opt/terracotta/server-data</data>
      
      <!-- In which directory should the server store its log files? 
           This value undergoes parameter substitution before being used.
           Thus, a value like 'server-logs-%h' would expand to
           'server-logs-my.host.name' if running on host 'my.host.names'.
           
           If this is a relative path, it is interpreted relative to
           the current working directory of the server (that is, the directory
           you were in when you started server). It is recommended that
           you specify an absolute path.
           
           Default: 'logs', which places the 'logs' directory in the
           directory you were in when you invoked 'start-tc-server'.
      -->
      <logs>/opt/terracotta/server-logs</logs>

      <!-- Where should the server store its search index data? This value
           undergoes parameter substitution.

           If this is a relative path, it is interpreted relative to
           the current working directory of the server (that is, the directory
           you were in when you started the server). It is recommended that
           you specify an absolute path.
           
           Default: (none), which stores the index in the same directory
           as the configured <data> location.
      -->
      <index>/opt/terracotta/server-index</index>

      <!-- On what port should the server listen for connections from
           clients? This can be any port, but ports below 1024 typically require 
           'root' privileges on Linux or Solaris. Optionally, you can bind
           the port to a specific interface.
           Default: 9510
      -->
      <tsa-port bind="12.34.56.78">9510</tsa-port>

      <!-- On what port should the server listen for JMX connections?
           This can be any port, but ports below 1024 typically require 'root'
           privileges on Linux or Solaris.
           Optionally, you can bind the port to a specific interface.
           Default: disabled,
           if enabled using jmx-enable attribute at server tag level: 9520
      -->
      <jmx-port bind="12.34.56.78">9520</jmx-port>

      <!-- On what port should the server listen for communication from
           other servers participating in a networked-active-passive setup.
           This can be any port, but ports below 1024 typically require 'root'
           privileges on Linux or Solaris. Optionally, you can bind the port to a 
           specific interface.
           Default: 9530
      -->
      <tsa-group-port bind="12.34.56.78">9530</tsa-group-port>

      <!-- On what port should the server listen for http/https
           communication for management functions. 
           This can be any port, but ports below 1024 typically require 'root'
           privileges on Linux or Solaris. Optionally, you can bind the port to a 
           specific interface.
           Default: 9540
      -->
      <management-port bind="12.34.56.78">9540</management-port>
      
      <!-- Turn on authentication for the Terracotta server. An empty tag
           <authentication> defaults to the standard Java JMX authentication
           mechanism referring to password and access files in:
           $JAVA_HOME/jre/lib/management.
           - $JAVA_HOME/jre/lib/management/jmxremote.password
           - $JAVA_HOME/jre/lib/management/jmxremote.access
           
           You must modify or create these files:
           
           - jmxremote.password: add a line to the end of the file declaring
           your username and password, followed by a caridge return:
           secretusername secretpassword
           
           - jmxremote.access: add the following line (with a caridge return)
           to the end of your file:
           secretusername readwrite
           
           You must also do:
           $ chmod 500 jmxremote.password
           $ chown <user who will execute the tc-server> jmxremote.password
      -->
      <authentication/>
      
      <!-- Turn on authentication for the embedded Terracotta HTTP Server.
           This requires a properties file that contains the users and passwords
           that have access to the HTTP server.
           
           The format of the properties file is:
           username: password [,rolename ...]
           
           The supported roles and protected sections are: 
           - statistics: for the statistics gatherer at /statistics-gatherer
           
           Passwords can be clear text, obfuscated, or checksummed.
           
           To generate obfuscated passwords or password checksums, use the
           com.mortbay.Util.Password class.
      -->
      <http-authentication>
        <user-realm-file>/opt/terracotta/realm.properties</user-realm-file>
      </http-authentication>

      <!-- Information about how servers use off-heap memory.  Note: In 4.1, if you are using the BigMemory Hybrid feature, maxDataSize is deprecated and you would use dataStorage instead, which includes both DRAM and SSD or Flash. -->
      <offheap>
        
        <!-- If 'true', active servers spill cached data to off-heap memory
             before persisting it to disk. Data that is cached off-heap 
             provides faster access than data stored on disk.
             Default: false
        -->
        <enabled>false</enabled>
        
        <!-- Sets the maximum amount of off-heap memory that a server
             can use. Values are given in k (Kilobytes), m (Megabytes)
             or g (Gigabytes). 
             Default: none
        -->
        <maxDataSize>5g</maxDataSize>
      </offheap>
      
      <!-- Information about how servers store data.  Note: This is 
            required for the BigMemory Hybrid feature. Use this 
            instead of offheap element above.
      -->
      
      <!-- size is mandatory and represents the maximum amount of data you plan to store on the server.
      -->
      <dataStorage size="10g">
          <!-- offheap is an optional element that sets the maximum amount of offheap to 
            allocate to the server. 
            If the element is not present, offheap size will default to
            dataStorage size.
          -->
          <offheap size="5g"/>
          <!-- hybrid is an optional element that enables the BigMemorhy Hybrid feature.
          -->
          <hybrid/>
      </dataStorage>
      
    </server>
    
    <!-- A <mirror-group> section lets you divide your servers in groups. Each 
         group can be composed of one or more servers, where one server 
         acts as the Active server. You can omit this section if you want to have only
         1 Active server in the cluster. 
    --> 

    <!-- Each group can also be assigned a group name. Each group has members 
         that are the "name" of the server specified above in the server section.
         More than one member can be present in a mirror group.
    -->
    <!-- <mirror-group group-name="group1" election-time="5"> -->
    <!--   <server/> -->
    <!-- </mirror-group> -->
    <!-- <mirror-group group-name="group2" election-time="5"> -->
    <!--   <server/> -->
    <!-- </mirror-group> -->

    <!-- This element lets you control if and how often the Terracotta server
         checks for update versions of the Terracotta platform.
         
    -->
    <update-check>
      <!-- This element determines if the server checks for updates
           to the version of the Terracotta platform you are using. The server
           contacts the terracotta.org website and compares the version of
           your software with a registry of current releases. Information about
           new versions is logged and displayed on the server's standard
           output.
           Default: 'false'
      -->
      <enabled>true</enabled>
      
      <!-- If update checking is enabled, this element specifies the number of days
           between update checks. When checking is enabled, an update check is performed each
           time the server starts, as well as at the
           specified intervals.
           Default: 7
      -->
      <period-days>10</period-days>
    </update-check>

    <!-- Information about how to perform distributed
         garbage collection on the data underneath your
         application's roots. -->
    <garbage-collection>
      
      <!-- If 'true', distributed garbage collection is enabled.
           Do not set this to 'false' unless you are
           absolutely certain that none of the data underneath
           your roots will ever become garbage. 
           
           An example of an application that can safely disable distributed garbage
           collection is one that writes data into a Map, looks up values in the Map, 
           and never removes data.
           
           A setting of 'false' can also be used if distributed
           garbage collection is triggered externally
           with the 'run-dgc' script.
           
           Default: true
      -->
      <enabled>true</enabled>
      
      <!-- If 'true', the server emits extra information 
           to the log file when it performs distributed garbage
           collection. This can be useful while attempting to tune performance.
           
           Default: false
      -->
      <verbose>false</verbose>
      
        <!-- How often should the server perform distributed
         garbage collection, in seconds?
         
           Default: 3600 (60 minutes)
      -->
      <interval>3600</interval>
    </garbage-collection>
    
    <!-- Configure whether or not all servers should be restartable.
         
         enabled=true, the L2 persists its state to disk.
         
         enabled=false, the L2 does not persist its state to disk.
         
         Note: the L2 keeps everything in memory regardless of the restartable setting.
         
         Default: enabled=false
    -->
    <restartable enabled="false"/>

    <!-- Configure the fail-over priority of the entire cluster.

         AVAILABILITY, high availability of the cluster is required. Automatic fail-over of passive on detecting an active disconnection.

         CONSISTENCY, data consistency is the requirement. No automatic fail-over of passive on detecting an active disconnection.
                      Manual intervention required for fail-over.

         Default: AVAILABILITY
    -->
    <failover-priority>AVAILABILITY</failover-priority>

    
    <!-- How much time (in seconds) should the server, upon restart, allow for previously
         connected clients to reconnect?  After this period, clients will
         not be allowed to reconnect.
         
         Default: 120 seconds
    -->
    <client-reconnect-window>120</client-reconnect-window>    

  </servers>
  
  
  <!-- This section contains settings that affect all clients that connect to the
       system.
       
       Note that while these settings are applied uniformly across all clients,
       this does not prevent you from applying different settings to specific
       clients. There are two ways of doing this:
       
       - 1. Certain parameters ('logs', below) undergo parameter expansion
       before being used by the client. This allows you to use predefined
       substitutions (such as '%h' for host), or a general one
       (%(myprop) to use the value of Java system property 'myprop'), for
       these values.
       2. Expansions are carried out in each client's JVM
       independently.  Parameter expansion is not done for values inside the
       <modules> element.
  -->
  <clients>
    
    <!-- Where should the client write its log files?
         
         This value undergoes parameter substitution before being used.
         Thus, a value like 'client-logs-%h' expands to
         'client-logs-banana' if running on host 'banana'.
         
         If this is a relative path, it is interpreted relative to
         the current working directory of the client (that is, the directory
         you were in when you started the program that uses Terracotta
         services). It is recommended that you specify an absolute
         path.
         
         Default: 'logs-%i', which places the logs in a directory relative
         to the directory you were in when you invoked the program that uses
         Terracotta services (your client), and calls that directory. For example,
         'logs-10.0.0.57' if the machine that the client is on has assigned IP
         address 10.0.0.57.
    -->
    <logs>logs-%i</logs>
    
  </clients>
  
</tc:tc-config>