1.. Licensed to the Apache Software Foundation (ASF) under one
2   or more contributor license agreements.  See the NOTICE file
3   distributed with this work for additional information
4   regarding copyright ownership.  The ASF licenses this file
5   to you under the Apache License, Version 2.0 (the
6   "License"); you may not use this file except in compliance
7   with the License.  You may obtain a copy of the License at
8
9   http://www.apache.org/licenses/LICENSE-2.0
10
11   Unless required by applicable law or agreed to in writing,
12   software distributed under the License is distributed on an
13   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14   KIND, either express or implied.  See the License for the
15   specific language governing permissions and limitations
16   under the License.
17
18.. include:: ../../../common.defs
19
20.. default-domain:: c
21
22.. _ts-overridable-config:
23
24TSHttpOverridableConfig
25***********************
26
27Synopsis
28========
29
30.. code-block:: cpp
31
32    #include <ts/ts.h>
33
34
35.. function:: TSReturnCode TSHttpTxnConfigIntSet(TSHttpTxn txnp, TSOverridableConfigKey key, TSMgmtInt value)
36.. function:: TSReturnCode TSHttpTxnConfigIntGet(TSHttpTxn txnp, TSOverridableConfigKey key, TSMgmtInt* value)
37.. function:: TSReturnCode TSHttpTxnConfigFloatSet(TSHttpTxn txnp, TSOverridableConfigKey key, TSMgmtFloat value)
38.. function:: TSReturnCode TSHttpTxnConfigFloatGet(TSHttpTxn txnp, TSOverridableConfigKey key, TSMgmtFloat* value)
39.. function:: TSReturnCode TSHttpTxnConfigStringSet(TSHttpTxn txnp, TSOverridableConfigKey key, const char* value, int length)
40.. function:: TSReturnCode TSHttpTxnConfigStringGet(TSHttpTxn txnp, TSOverridableConfigKey key, const char** value, int* length)
41.. function:: TSReturnCode TSHttpTxnConfigFind(const char* name, int length, TSOverridableConfigKey* key, TSRecordDataType* type)
42
43Description
44===========
45
46Some of the values that are set in :file:`records.config` can be changed for a
47specific transaction. It is important to note that these functions change the
48configuration values stored for the transaction, which is not quite the same as
49changing the actual operating values of the transaction. The critical effect is
50the value must be changed before it is used by the transaction - after that,
51changes will not have any effect.
52
53All of the ``...Get`` functions store the internal value in the storage
54indicated by the :arg:`value` argument. For strings :arg:`length*` will receive
55the length of the string.
56
57The values are identified by the enumeration :type:`TSOverridableConfigKey`.
58String values can be used indirectly by first passing them to
59:func:`TSHttpTxnConfigFind` which, if the string matches an overridable value,
60return the key and data type.
61
62Configurations
63==============
64
65The following configurations (from ``records.config``) are overridable:
66
67==================================================================  ====================================================================
68TSOverridableConfigKey Value                                        Configuration Value
69==================================================================  ====================================================================
70:c:macro:`TS_CONFIG_BODY_FACTORY_TEMPLATE_BASE`                     :ts:cv:`proxy.config.body_factory.template_base`
71:c:macro:`TS_CONFIG_HTTP_ALLOW_HALF_OPEN`                           :ts:cv:`proxy.config.http.allow_half_open`
72:c:macro:`TS_CONFIG_HTTP_ALLOW_MULTI_RANGE`                         :ts:cv:`proxy.config.http.allow_multi_range`
73:c:macro:`TS_CONFIG_HTTP_ANONYMIZE_INSERT_CLIENT_IP`                :ts:cv:`proxy.config.http.insert_client_ip`
74:c:macro:`TS_CONFIG_HTTP_ANONYMIZE_REMOVE_CLIENT_IP`                :ts:cv:`proxy.config.http.anonymize_remove_client_ip`
75:c:macro:`TS_CONFIG_HTTP_ANONYMIZE_REMOVE_COOKIE`                   :ts:cv:`proxy.config.http.anonymize_remove_cookie`
76:c:macro:`TS_CONFIG_HTTP_ANONYMIZE_REMOVE_FROM`                     :ts:cv:`proxy.config.http.anonymize_remove_from`
77:c:macro:`TS_CONFIG_HTTP_ANONYMIZE_REMOVE_REFERER`                  :ts:cv:`proxy.config.http.anonymize_remove_referer`
78:c:macro:`TS_CONFIG_HTTP_ANONYMIZE_REMOVE_USER_AGENT`               :ts:cv:`proxy.config.http.anonymize_remove_user_agent`
79:c:macro:`TS_CONFIG_HTTP_ATTACH_SERVER_SESSION_TO_CLIENT`           :ts:cv:`proxy.config.http.attach_server_session_to_client`
80:c:macro:`TS_CONFIG_HTTP_AUTH_SERVER_SESSION_PRIVATE`               :ts:cv:`proxy.config.http.auth_server_session_private`
81:c:macro:`TS_CONFIG_HTTP_BACKGROUND_FILL_ACTIVE_TIMEOUT`            :ts:cv:`proxy.config.http.background_fill_active_timeout`
82:c:macro:`TS_CONFIG_HTTP_BACKGROUND_FILL_COMPLETED_THRESHOLD`       :ts:cv:`proxy.config.http.background_fill_completed_threshold`
83:c:macro:`TS_CONFIG_HTTP_CACHE_CACHE_RESPONSES_TO_COOKIES`          :ts:cv:`proxy.config.http.cache.cache_responses_to_cookies`
84:c:macro:`TS_CONFIG_HTTP_CACHE_CACHE_URLS_THAT_LOOK_DYNAMIC`        :ts:cv:`proxy.config.http.cache.cache_urls_that_look_dynamic`
85:c:macro:`TS_CONFIG_HTTP_CACHE_GENERATION`                          :ts:cv:`proxy.config.http.cache.generation`
86:c:macro:`TS_CONFIG_HTTP_CACHE_GUARANTEED_MAX_LIFETIME`             :ts:cv:`proxy.config.http.cache.guaranteed_max_lifetime`
87:c:macro:`TS_CONFIG_HTTP_CACHE_GUARANTEED_MIN_LIFETIME`             :ts:cv:`proxy.config.http.cache.guaranteed_min_lifetime`
88:c:macro:`TS_CONFIG_HTTP_CACHE_HEURISTIC_LM_FACTOR`                 :ts:cv:`proxy.config.http.cache.heuristic_lm_factor`
89:c:macro:`TS_CONFIG_HTTP_CACHE_HEURISTIC_MAX_LIFETIME`              :ts:cv:`proxy.config.http.cache.heuristic_max_lifetime`
90:c:macro:`TS_CONFIG_HTTP_CACHE_HEURISTIC_MIN_LIFETIME`              :ts:cv:`proxy.config.http.cache.heuristic_min_lifetime`
91:c:macro:`TS_CONFIG_HTTP_CACHE_HTTP`                                :ts:cv:`proxy.config.http.cache.http`
92:c:macro:`TS_CONFIG_HTTP_CACHE_IGNORE_ACCEPT_CHARSET_MISMATCH`      :ts:cv:`proxy.config.http.cache.ignore_accept_charset_mismatch`
93:c:macro:`TS_CONFIG_HTTP_CACHE_IGNORE_ACCEPT_ENCODING_MISMATCH`     :ts:cv:`proxy.config.http.cache.ignore_accept_encoding_mismatch`
94:c:macro:`TS_CONFIG_HTTP_CACHE_IGNORE_ACCEPT_LANGUAGE_MISMATCH`     :ts:cv:`proxy.config.http.cache.ignore_accept_language_mismatch`
95:c:macro:`TS_CONFIG_HTTP_CACHE_IGNORE_ACCEPT_MISMATCH`              :ts:cv:`proxy.config.http.cache.ignore_accept_mismatch`
96:c:macro:`TS_CONFIG_HTTP_CACHE_IGNORE_AUTHENTICATION`               :ts:cv:`proxy.config.http.cache.ignore_authentication`
97:c:macro:`TS_CONFIG_HTTP_CACHE_IGNORE_CLIENT_CC_MAX_AGE`            :ts:cv:`proxy.config.http.cache.ignore_client_cc_max_age`
98:c:macro:`TS_CONFIG_HTTP_CACHE_IGNORE_CLIENT_NO_CACHE`              :ts:cv:`proxy.config.http.cache.ignore_client_no_cache`
99:c:macro:`TS_CONFIG_HTTP_CACHE_IGNORE_SERVER_NO_CACHE`              :ts:cv:`proxy.config.http.cache.ignore_server_no_cache`
100:c:macro:`TS_CONFIG_HTTP_CACHE_IMS_ON_CLIENT_NO_CACHE`              :ts:cv:`proxy.config.http.cache.ims_on_client_no_cache`
101:c:macro:`TS_CONFIG_HTTP_CACHE_MAX_OPEN_READ_RETRIES`               :ts:cv:`proxy.config.http.cache.max_open_read_retries`
102:c:macro:`TS_CONFIG_HTTP_CACHE_MAX_OPEN_WRITE_RETRIES`              :ts:cv:`proxy.config.http.cache.max_open_write_retries`
103:c:macro:`TS_CONFIG_HTTP_CACHE_MAX_STALE_AGE`                       :ts:cv:`proxy.config.http.cache.max_stale_age`
104:c:macro:`TS_CONFIG_HTTP_CACHE_OPEN_READ_RETRY_TIME`                :ts:cv:`proxy.config.http.cache.open_read_retry_time`
105:c:macro:`TS_CONFIG_HTTP_CACHE_OPEN_WRITE_FAIL_ACTION`              :ts:cv:`proxy.config.http.cache.open_write_fail_action`
106:c:macro:`TS_CONFIG_HTTP_CACHE_RANGE_LOOKUP`                        :ts:cv:`proxy.config.http.cache.range.lookup`
107:c:macro:`TS_CONFIG_HTTP_CACHE_RANGE_WRITE`                         :ts:cv:`proxy.config.http.cache.range.write`
108:c:macro:`TS_CONFIG_HTTP_CACHE_REQUIRED_HEADERS`                    :ts:cv:`proxy.config.http.cache.required_headers`
109:c:macro:`TS_CONFIG_HTTP_CACHE_WHEN_TO_REVALIDATE`                  :ts:cv:`proxy.config.http.cache.when_to_revalidate`
110:c:macro:`TS_CONFIG_HTTP_CHUNKING_ENABLED`                          :ts:cv:`proxy.config.http.chunking_enabled`
111:c:macro:`TS_CONFIG_HTTP_CHUNKING_SIZE`                             :ts:cv:`proxy.config.http.chunking.size`
112:c:macro:`TS_CONFIG_HTTP_CONNECT_ATTEMPTS_MAX_RETRIES_DEAD_SERVER`  :ts:cv:`proxy.config.http.connect_attempts_max_retries_dead_server`
113:c:macro:`TS_CONFIG_HTTP_CONNECT_ATTEMPTS_MAX_RETRIES`              :ts:cv:`proxy.config.http.connect_attempts_max_retries`
114:c:macro:`TS_CONFIG_HTTP_CONNECT_ATTEMPTS_RR_RETRIES`               :ts:cv:`proxy.config.http.connect_attempts_rr_retries`
115:c:macro:`TS_CONFIG_HTTP_CONNECT_ATTEMPTS_TIMEOUT`                  :ts:cv:`proxy.config.http.connect_attempts_timeout`
116:c:macro:`TS_CONFIG_HTTP_DEFAULT_BUFFER_SIZE`                       :ts:cv:`proxy.config.http.default_buffer_size`
117:c:macro:`TS_CONFIG_HTTP_DEFAULT_BUFFER_WATER_MARK`                 :ts:cv:`proxy.config.http.default_buffer_water_mark`
118:c:macro:`TS_CONFIG_HTTP_DOC_IN_CACHE_SKIP_DNS`                     :ts:cv:`proxy.config.http.doc_in_cache_skip_dns`
119:c:macro:`TS_CONFIG_HTTP_DOWN_SERVER_CACHE_TIME`                    :ts:cv:`proxy.config.http.down_server.cache_time`
120:c:macro:`TS_CONFIG_HTTP_FLOW_CONTROL_ENABLED`                      :ts:cv:`proxy.config.http.flow_control.enabled`
121:c:macro:`TS_CONFIG_HTTP_FLOW_CONTROL_HIGH_WATER_MARK`              :ts:cv:`proxy.config.http.flow_control.high_water`
122:c:macro:`TS_CONFIG_HTTP_FLOW_CONTROL_LOW_WATER_MARK`               :ts:cv:`proxy.config.http.flow_control.low_water`
123:c:macro:`TS_CONFIG_HTTP_FORWARD_CONNECT_METHOD`                    :ts:cv:`proxy.config.http.forward_connect_method`
124:c:macro:`TS_CONFIG_HTTP_FORWARD_PROXY_AUTH_TO_PARENT`              :ts:cv:`proxy.config.http.forward.proxy_auth_to_parent`
125:c:macro:`TS_CONFIG_HTTP_GLOBAL_USER_AGENT_HEADER`                  :ts:cv:`proxy.config.http.global_user_agent_header`
126:c:macro:`TS_CONFIG_HTTP_INSERT_AGE_IN_RESPONSE`                    :ts:cv:`proxy.config.http.insert_age_in_response`
127:c:macro:`TS_CONFIG_HTTP_INSERT_FORWARDED`                          :ts:cv:`proxy.config.http.insert_forwarded`
128:c:macro:`TS_CONFIG_HTTP_INSERT_REQUEST_VIA_STR`                    :ts:cv:`proxy.config.http.insert_request_via_str`
129:c:macro:`TS_CONFIG_HTTP_INSERT_RESPONSE_VIA_STR`                   :ts:cv:`proxy.config.http.insert_response_via_str`
130:c:macro:`TS_CONFIG_HTTP_INSERT_SQUID_X_FORWARDED_FOR`              :ts:cv:`proxy.config.http.insert_squid_x_forwarded_for`
131:c:macro:`TS_CONFIG_HTTP_KEEP_ALIVE_ENABLED_IN`                     :ts:cv:`proxy.config.http.keep_alive_enabled_in`
132:c:macro:`TS_CONFIG_HTTP_KEEP_ALIVE_ENABLED_OUT`                    :ts:cv:`proxy.config.http.keep_alive_enabled_out`
133:c:macro:`TS_CONFIG_HTTP_KEEP_ALIVE_NO_ACTIVITY_TIMEOUT_IN`         :ts:cv:`proxy.config.http.keep_alive_no_activity_timeout_in`
134:c:macro:`TS_CONFIG_HTTP_KEEP_ALIVE_NO_ACTIVITY_TIMEOUT_OUT`        :ts:cv:`proxy.config.http.keep_alive_no_activity_timeout_out`
135:c:macro:`TS_CONFIG_HTTP_KEEP_ALIVE_POST_OUT`                       :ts:cv:`proxy.config.http.keep_alive_post_out`
136:c:macro:`TS_CONFIG_HTTP_NEGATIVE_CACHING_ENABLED`                  :ts:cv:`proxy.config.http.negative_caching_enabled`
137:c:macro:`TS_CONFIG_HTTP_NEGATIVE_CACHING_LIFETIME`                 :ts:cv:`proxy.config.http.negative_caching_lifetime`
138:c:macro:`TS_CONFIG_HTTP_NEGATIVE_REVALIDATING_ENABLED`             :ts:cv:`proxy.config.http.negative_revalidating_enabled`
139:c:macro:`TS_CONFIG_HTTP_NEGATIVE_REVALIDATING_LIFETIME`            :ts:cv:`proxy.config.http.negative_revalidating_lifetime`
140:c:macro:`TS_CONFIG_HTTP_NORMALIZE_AE`                              :ts:cv:`proxy.config.http.normalize_ae`
141:c:macro:`TS_CONFIG_HTTP_NUMBER_OF_REDIRECTIONS`                    :ts:cv:`proxy.config.http.number_of_redirections`
142:c:macro:`TS_CONFIG_HTTP_PARENT_CONNECT_ATTEMPT_TIMEOUT`            :ts:cv:`proxy.config.http.parent_proxy.connect_attempts_timeout`
143:c:macro:`TS_CONFIG_HTTP_PARENT_PROXY_FAIL_THRESHOLD`               :ts:cv:`proxy.config.http.parent_proxy.fail_threshold`
144:c:macro:`TS_CONFIG_HTTP_PARENT_PROXY_RETRY_TIME`                   :ts:cv:`proxy.config.http.parent_proxy.retry_time`
145:c:macro:`TS_CONFIG_HTTP_PARENT_PROXY_TOTAL_CONNECT_ATTEMPTS`       :ts:cv:`proxy.config.http.parent_proxy.total_connect_attempts`
146:c:macro:`TS_CONFIG_HTTP_PER_PARENT_CONNECT_ATTEMPTS`               :ts:cv:`proxy.config.http.parent_proxy.per_parent_connect_attempts`
147:c:macro:`TS_CONFIG_HTTP_PER_SERVER_CONNECTION_MATCH`               :ts:cv:`proxy.config.http.per_server.connection.match`
148:c:macro:`TS_CONFIG_HTTP_PER_SERVER_CONNECTION_MAX`                 :ts:cv:`proxy.config.http.per_server.connection.max`
149:c:macro:`TS_CONFIG_HTTP_POST_CHECK_CONTENT_LENGTH_ENABLED`         :ts:cv:`proxy.config.http.post.check.content_length.enabled`
150:c:macro:`TS_CONFIG_HTTP_POST_CONNECT_ATTEMPTS_TIMEOUT`             :ts:cv:`proxy.config.http.post_connect_attempts_timeout`
151:c:macro:`TS_CONFIG_HTTP_REDIRECT_USE_ORIG_CACHE_KEY`               :ts:cv:`proxy.config.http.redirect_use_orig_cache_key`
152:c:macro:`TS_CONFIG_HTTP_REQUEST_BUFFER_ENABLED`                    :ts:cv:`proxy.config.http.request_buffer_enabled`
153:c:macro:`TS_CONFIG_HTTP_REQUEST_HEADER_MAX_SIZE`                   :ts:cv:`proxy.config.http.request_header_max_size`
154:c:macro:`TS_CONFIG_HTTP_RESPONSE_HEADER_MAX_SIZE`                  :ts:cv:`proxy.config.http.response_header_max_size`
155:c:macro:`TS_CONFIG_HTTP_RESPONSE_SERVER_ENABLED`                   :ts:cv:`proxy.config.http.response_server_enabled`
156:c:macro:`TS_CONFIG_HTTP_RESPONSE_SERVER_STR`                       :ts:cv:`proxy.config.http.response_server_str`
157:c:macro:`TS_CONFIG_HTTP_SEND_HTTP11_REQUESTS`                      :ts:cv:`proxy.config.http.send_http11_requests`
158:c:macro:`TS_CONFIG_HTTP_SERVER_SESSION_SHARING_MATCH`              :ts:cv:`proxy.config.http.server_session_sharing.match`
159:c:macro:`TS_CONFIG_HTTP_SLOW_LOG_THRESHOLD`                        :ts:cv:`proxy.config.http.slow.log.threshold`
160:c:macro:`TS_CONFIG_HTTP_TRANSACTION_ACTIVE_TIMEOUT_IN`             :ts:cv:`proxy.config.http.transaction_active_timeout_in`
161:c:macro:`TS_CONFIG_HTTP_TRANSACTION_ACTIVE_TIMEOUT_OUT`            :ts:cv:`proxy.config.http.transaction_active_timeout_out`
162:c:macro:`TS_CONFIG_HTTP_TRANSACTION_NO_ACTIVITY_TIMEOUT_IN`        :ts:cv:`proxy.config.http.transaction_no_activity_timeout_in`
163:c:macro:`TS_CONFIG_HTTP_TRANSACTION_NO_ACTIVITY_TIMEOUT_OUT`       :ts:cv:`proxy.config.http.transaction_no_activity_timeout_out`
164:c:macro:`TS_CONFIG_HTTP_UNCACHEABLE_REQUESTS_BYPASS_PARENT`        :ts:cv:`proxy.config.http.uncacheable_requests_bypass_parent`
165:c:macro:`TS_CONFIG_NET_SOCK_OPTION_FLAG_OUT`                       :ts:cv:`proxy.config.net.sock_option_flag_out`
166:c:macro:`TS_CONFIG_NET_SOCK_PACKET_MARK_OUT`                       :ts:cv:`proxy.config.net.sock_packet_mark_out`
167:c:macro:`TS_CONFIG_NET_SOCK_PACKET_TOS_OUT`                        :ts:cv:`proxy.config.net.sock_packet_tos_out`
168:c:macro:`TS_CONFIG_NET_SOCK_RECV_BUFFER_SIZE_OUT`                  :ts:cv:`proxy.config.net.sock_recv_buffer_size_out`
169:c:macro:`TS_CONFIG_NET_SOCK_SEND_BUFFER_SIZE_OUT`                  :ts:cv:`proxy.config.net.sock_send_buffer_size_out`
170:c:macro:`TS_CONFIG_PARENT_FAILURES_UPDATE_HOSTDB`                  :ts:cv:`proxy.config.http.parent_proxy.mark_down_hostdb`
171:c:macro:`TS_CONFIG_SRV_ENABLED`                                    :ts:cv:`proxy.config.srv_enabled`
172:c:macro:`TS_CONFIG_SSL_CLIENT_CERT_FILENAME`                       :ts:cv:`proxy.config.ssl.client.cert.filename`
173:c:macro:`TS_CONFIG_SSL_CERT_FILEPATH`                              :ts:cv:`proxy.config.ssl.client.cert.path`
174:c:macro:`TS_CONFIG_SSL_CLIENT_VERIFY_SERVER_PROPERTIES`            :ts:cv:`proxy.config.ssl.client.verify.server.properties`
175:c:macro:`TS_CONFIG_SSL_CLIENT_VERIFY_SERVER_POLICY`                :ts:cv:`proxy.config.ssl.client.verify.server.policy`
176:c:macro:`TS_CONFIG_SSL_CLIENT_SNI_POLICY`                          :ts:cv:`proxy.config.ssl.client.sni_policy`
177:c:macro:`TS_CONFIG_SSL_HSTS_INCLUDE_SUBDOMAINS`                    :ts:cv:`proxy.config.ssl.hsts_include_subdomains`
178:c:macro:`TS_CONFIG_SSL_HSTS_MAX_AGE`                               :ts:cv:`proxy.config.ssl.hsts_max_age`
179:c:macro:`TS_CONFIG_URL_REMAP_PRISTINE_HOST_HDR`                    :ts:cv:`proxy.config.url_remap.pristine_host_hdr`
180:c:macro:`TS_CONFIG_WEBSOCKET_ACTIVE_TIMEOUT`                       :ts:cv:`proxy.config.websocket.active_timeout`
181:c:macro:`TS_CONFIG_WEBSOCKET_NO_ACTIVITY_TIMEOUT`                  :ts:cv:`proxy.config.websocket.no_activity_timeout`
182:c:macro:`TS_CONFIG_SSL_CLIENT_CERT_FILENAME`                       :ts:cv:`proxy.config.ssl.client.cert.filename`
183:c:macro:`TS_CONFIG_SSL_CLIENT_PRIVATE_KEY_FILENAME`                :ts:cv:`proxy.config.ssl.client.private_key.filename`
184:c:macro:`TS_CONFIG_SSL_CLIENT_CA_CERT_FILENAME`                    :ts:cv:`proxy.config.ssl.client.CA.cert.filename`
185:c:macro:`TS_CONFIG_HTTP_HOST_RESOLUTION_PREFERENCE`                :ts:cv:`proxy.config.hostdb.ip_resolve`
186==================================================================  ====================================================================
187
188Examples
189========
190
191Enable :ref:`transaction buffer control <transaction-buffering-control>` with a
192high water mark of :literal:`262144` and a low water mark of :literal:`65536`. ::
193
194   int callback(TSCont contp, TSEvent event, void* data)
195   {
196      TSHttpTxn txnp = static_cast<TSHttpTxn>(data);
197      TSHttpTxnConfigIntSet(txnp, TS_CONFIG_HTTP_FLOW_CONTROL_ENABLED, 1);
198      TSHttpTxnConfigIntSet(txnp, TS_CONFIG_HTTP_FLOW_CONTROL_HIGH_WATER_MARK, 262144);
199      TSHttpTxnConfigIntSet(txnp, TS_CONFIG_HTTP_FLOW_CONTROL_LOWER_WATER_MARK, 65536);
200      return 0;
201   }
202
203See Also
204========
205
206:manpage:`TSAPI(3ts)`
207