1<?xml version="1.0" encoding="utf-8" ?>
2<!DOCTYPE fileref SYSTEM "fileref.dtd">
3
4<fileref>
5  <header>
6    <copyright>
7      <year>1997</year><year>2018</year>
8      <holder>Ericsson AB. All Rights Reserved.</holder>
9    </copyright>
10    <legalnotice>
11      Licensed under the Apache License, Version 2.0 (the "License");
12      you may not use this file except in compliance with the License.
13      You may obtain a copy of the License at
14
15          http://www.apache.org/licenses/LICENSE-2.0
16
17      Unless required by applicable law or agreed to in writing, software
18      distributed under the License is distributed on an "AS IS" BASIS,
19      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
20      See the License for the specific language governing permissions and
21      limitations under the License.
22
23    </legalnotice>
24
25    <title>config</title>
26    <prepared></prepared>
27    <docno></docno>
28    <date></date>
29    <rev></rev>
30  </header>
31  <file>config</file>
32  <filesummary>Configuration file.</filesummary>
33  <description>
34    <p>A <em>configuration file</em> contains values for configuration
35      parameters for the applications in the system. The <c>erl</c>
36      command-line argument <c>-config Name</c> tells the system to use
37      data in the system configuration file <c>Name.config</c>.</p>
38    <p>Configuration parameter values in the configuration file
39      override the values in the application resource files (see
40      <seefile marker="app"><c>app(4)</c></seefile>).
41      The values in the configuration file can be
42      overridden by command-line flags (see
43      <seecom marker="erts:erl"><c>erts:erl(1)</c></seecom>).</p>
44    <p>The value of a configuration parameter is retrieved by calling
45      <c>application:get_env/1,2</c>.</p>
46  </description>
47
48  <section>
49    <title>File Syntax</title>
50    <p>The configuration file is to be called <c>Name.config</c>, where
51      <c>Name</c> is any name.</p>
52    <p>File <c>.config</c> contains a single Erlang term and
53      has the following syntax:</p>
54    <code type="none">
55[{Application1, [{Par11, Val11}, ...]},
56 ...
57 {ApplicationN, [{ParN1, ValN1}, ...]}].</code>
58    <taglist>
59      <tag><c>Application = atom()</c></tag>
60      <item><p>Application name.</p></item>
61      <tag><c>Par = atom()</c></tag>
62      <item><p>Name of a configuration parameter.</p></item>
63      <tag><c>Val = term()</c></tag>
64      <item><p>Value of a configuration parameter.</p></item>
65    </taglist>
66  </section>
67
68  <section>
69    <title>sys.config</title>
70    <p>When starting Erlang in embedded mode, it is assumed that
71      exactly one system configuration file is used, named
72      <c>sys.config</c>. This file is to be located in
73      <c>$ROOT/releases/Vsn</c>, where <c>$ROOT</c> is the Erlang/OTP
74      root installation directory and <c>Vsn</c> is the release version.</p>
75    <p>Release handling relies on this assumption. When installing a
76      new release version, the new <c>sys.config</c> is read and used
77      to update the application configurations.</p>
78    <p>This means that specifying another <c>.config</c> file, or more
79      <c>.config</c> files, leads to inconsistent update of application
80      configurations. There is, however, a syntax for
81      <c>sys.config</c> that allows pointing out other
82      <c>.config</c> files:</p>
83    <code type="none">
84[{Application, [{Par, Val}]} | File].</code>
85    <taglist>
86      <tag><c>File = string()</c></tag>
87      <item>Name of another <c>.config</c> file.
88        Extension <c>.config</c> can be omitted. It is
89        recommended to use absolute paths. If a relative path is used,
90        <c>File</c> is searched, first, relative from <c>sys.config</c> directory, then relative
91        to the current working directory of the emulator, for backward compatibility.
92        This allow to use a <c>sys.config</c> pointing out other <c>.config</c> files in a release
93        or in a node started manually using <c>-config ...</c> with same result whatever
94        the current working directory.
95        </item>
96    </taglist>
97    <p>When traversing the contents of <c>sys.config</c> and a filename
98      is encountered, its contents are read and merged with the result
99      so far. When an application configuration tuple
100      <c>{Application, Env}</c> is found, it is merged with the result
101      so far. Merging means that new parameters are added and existing
102      parameter values overwritten.</p>
103    <p><em>Example:</em></p>
104    <code type="none">
105sys.config:
106
107[{myapp,[{par1,val1},{par2,val2}]},
108 "/home/user/myconfig"].
109
110myconfig.config:
111
112[{myapp,[{par2,val3},{par3,val4}]}].</code>
113    <p>This yields the following environment for <c>myapp</c>:</p>
114    <code type="none">
115[{par1,val1},{par2,val3},{par3,val4}]</code>
116    <p>The behavior if a file specified in <c>sys.config</c> does not
117      exist, or is erroneous, is backwards compatible.
118      Starting the runtime system will fail. Installing a new release
119      version will not fail, but an error message is returned and
120      the erroneous file is ignored.</p>
121  </section>
122
123  <section>
124    <title>See Also</title>
125    <p><seefile marker="app"><c>app(4)</c></seefile>,
126      <seecom marker="erts:erl"><c>erts:erl(1)</c></seecom>,
127      <seeguide marker="system/design_principles:des_princ">OTP Design Principles</seeguide></p>
128  </section>
129</fileref>
130
131