Differences

This shows you the differences between two versions of the page.

--- cookbooks:4.0.x:core:cfg [2013/06/18 05:44] – created poing
+++ cookbooks:4.0.x:core:cfg [2013/06/26 07:39] (current) – [Configuration Directives] poing
@@ Line 1: / Line 1: @@
-<fc #FF0000>**This is a work in progress**</fc>
+====== The Configuration File ======
-The Configuration File
+===== Configuration Elements =====
-Configuration Directives
+For the sake and sanity of the user of this software, we should cover the basic elements of the configuration before getting to the meat and potatoes.  There are three basic configuration elements to be concerned about.
-There are five (5) types of configuration directives used with Kamailio.
+  * Configuration Directives
+  * Comments
+  * Instruction Separator
-- C-Style Control Directives
-- Apache-Like Name/Value Pairs (delimited by a space, value within quotes)
-- Normal Name/Value Pairs (delimited by an equals sign)
-- Modify Parameter Procedure
-- Route Functions
-Comments
+-----
+-----
-Configuration file comments are PHP style, without the double-slash line comment.  Only hash (#) will work for line comments.
+==== Configuration Directives ====
-This is confusing, since the hash-bang (#!) is used at the beginning of the C-Style Control Directives.
+There are five (5) types of configuration directives used with Kamailio.\\
+^  <fc #800000>**Each type of configuration directive uses its own syntax!**</fc>  |
-/* block comment
+  - C-Style Control Directives
-   block comment */
+  - Apache-Like Name/Value Pairs
-// this is NOT a line comment
+  - Normal Name/Value Pairs
-# this is a line comment
+  - Modify Parameter Procedure
-#!c_style_directive
+  - Route Functions
-Instruction Separator
+-----
-The semicolon works with all forms of configuration directives as an instruction separator.  Allowing for comments or additional configuration directives on the same line.
+==== Comments ====
-configuration_directive_a; configuration_directive_b
+^  <fc #800000>**The first thing you should understand is the comment syntax used in the configuration file.**</fc>  |
-configuration_directive; # comment about the configuration directive
+Comments in the configuration file are a mixture of C-Style (**not C++**) and scripting language syntaxes.\\
+It closely resembles the PHP style, **//except//** you **can not use** double-slash ( ⁄ ⁄ ) for line comments.  Only the hash (#) may be used for line comments.\\ \\
+It can be confusing seeing the C-Style Control Directives ([[cfg#c-style_control_directives|explained later]]) that begin with a hash-bang (#!) mixed with line comments beginning with a hash (#).
-C-Style Control Directives
+^ Examples:  |
+|Block Comment:<code c>
+/* This is a ...
+   block comment */</code>  |
+|<fc #800000>**Not a Comment:**</fc><code> // this is NOT a line comment </code>|
+|Line Comment:<code c># this is a line comment </code>|
+|**<fc #800000>Valid Configuration Directive:</fc>**<code>#!c_style_directive</code>|
+-----
+==== Instruction Separator ====
+<fc #438D80>Just getting this out of the way before covering the Configuration Directives.</fc>
+The semicolon (;) is **//not required//** and **//may//** be used as an instruction separator for all configuration directives **//except//** Route Functions((Route Functions use scripting language syntax and **must** be terminated with a semicolon at the end of each statement.)).\\
+The general use is to allow for comments or additional configuration directives be placed on the same line.
+^ Examples:  |
+|<code>
+configuration_directive_a
+configuration_directive_b;
+configuration_directive_c; configuration_directive_d
+configuration_directive_e; # comment about the configuration directive
+</code>|
+-----
+-----
+===== Configuration Directives =====
+^ Type ^ Format ^ Comment ^
+| C-Style Control Directives | #!directive [ NAME [ VALUE ] ] | Begins with hash-bang (#!) |
+| Apache-Like Name/Value Pairs | name "value" | Delimited by a space & Value within quotes |
+| Normal Name/Value Pairs | name=value | Delimited by an equals sign |
+| Modify Parameter Procedure | modparam("MODULE", "PARAMETER", "VALUE") | |
+| Route Functions | route {...} | Scripting Language |
+==== C-Style Control Directives ====
  Available directives:
-    #!define NAME - define a keyword
+  * #!define NAME - define a keyword
-    #!define NAME VALUE - define a keyword with value
+  * #!define NAME VALUE - define a keyword with value
-    #!ifdef NAME - check if a keyword is defined
+  * #!ifdef NAME - check if a keyword is defined
-    #!ifndef - check if a keyword is not defined
+  * #!ifndef - check if a keyword is not defined
-    #!else - swtich to false branch of ifdef/ifndef region
+  * #!else - swtich to false branch of ifdef/ifndef region
-    #!endif - end ifdef/ifndef region
+  * #!endif - end ifdef/ifndef region
-    #!trydef - add a define if not already defined
+  * #!trydef - add a define if not already defined
-    #!redefine - force redefinition even if already defined
+  * #!redefine - force redefinition even if already defined
-    #!subst
+  * #!subst
-    #!substdef
+  * #!substdef
+^ Example:  |
+|<code c>
+#!define MODULE_NAME
+#!ifdef MODULE_NAME
+ ".. set directives .."
+#!else
+ ".. set alternate directives .."
+#!endif
+</code>|
+-----
+==== Apache Name/Value Pairs ====
+^ Syntax  |
+| <code c>name "value"</code>  |
+<fc #FF0000>//The value MUST be enclosed in quotes.//</fc>
+^ Examples  |
+|<code>
+loadmodule "module_name.so"
+loadmodule "another_module.so"
+include_file "file_to_include.cfg"
+import_file "/path/to/file_to_import.cfg"
+</code>|
+-------
+==== Normal Name/Value Pairs ====
+These name/value pairs are normally delimited by an equal sign.
+^ Syntax: |
+|<code c>name=value</code>|
+<fc #FF0000>There are a couple situations where the value needs to be enclosed in quotes.</fc>\\
+Check the [[../core#core_parameters|core parameters]] for the required syntax.
+^ Examples:  |
+|<code>
+memdbg=5
+memlog=5
+log_facility=LOG_LOCAL0
+fork=yes
+children=4
+#disable_tcp=yes
+auto_aliases=no
+alias="sip.mydomain.com"
+</code>|
+------
+==== Modify Parameter Procedure ====
+The modify parameter is similar to other types programming procedure.\\
+You call the procedure and it modifies the defined modules parameter.
+^ Syntax:  |
+| <code c>modparam ( string "$module" , string "$parameter" , mixed "$value" )</code> |
+<fc #800000>Strings should be enclosed in quotes.</fc>
+See the [[http://www.kamailio.org/docs/modules/4.0.x/|module documentation]] for support parameter settings.
+^ Examples:  |
+|<code>
+modparam("first_module", "module_parameter_text", "new_value");  # Set Text Value
+modparam("second_module", "module_parameter_number", 10000);      # Set Numeric Value
+modparam("second_module", "module_parameter_on", 1);              # Enable Parameter
+modparam("third_module", "module_parameter_on", 0);             # Disable Parameter
+</code>|
+-----
+==== Route Functions ====
+I will not go into too much detail here, the scripting methods, functions, and procdedures should be covered elsewhere in this wiki.\\
+^ Example:  |
+|<code c>request_route {
+        route(REQINIT); # Request Initial
+        route(NATDETECT); # NAT Detection
+        # CANCEL ??
+        if (is_method("CANCEL")) {
+         exit;
+        }
+        # OTHER SCRIPT CODE HERE
+}</code>|