config(5)

💖 config — the Configuration File glow-up 💖

okay bestie, this is config(5), a manual page from the Files section, and no cap it's literally the page that tells you how your Erlang system's configuration files work. it's giving ✨ foundational ✨. grab a strawberry drink, we're doing this. 🍓

---

🌸 NAME 🌸

config — the Configuration file. that's it, that's the name, iconic. 👑

---

✨ DESCRIPTION ✨

so. a configuration file holds values for configuration parameters for the applications in your system. that's the whole vibe.

the erl command-line argument -config Name tells the system: bestie, use the data in the system configuration file Name.config. 💅

and the erl command-line argument -configfd works the same way as the -config option, except instead of a file it specifies a file descriptor to read the configuration data from. yes, a file descriptor. we love a glow-up. 🔥

the configuration data from config files and from file descriptors gets read in the same order as they're given on the command line. for example:

erl -config a -configfd 3 -config b -configfd 4

would make the system read configuration data in this order: a.config, file descriptor 3, b.config, and file descriptor 4. so specific. so ordered. 🎀

and if a configuration parameter is specified more than once across the given files and file descriptors? the last one overrides the previous ones. last one wins, periodt. 👑

also important, listen up: configuration parameter values in a configuration file or file descriptor override the values in the application resource files (see app(5)). but — and this is the plot twist — the values in the configuration file are always overridden by command-line flags (see erts:erl(1)). hierarchy, bestie. respect it. 💀

to actually get the value of a configuration parameter, you call application:get_env/1,2. that's your retrieval moment. 🫶

---

📝 FILE SYNTAX 📝

the configuration file is supposed to be called Name.config, where Name is literally any name you want. main character naming energy. ✨

a .config file contains a single Erlang term, and here's the syntax, verbatim, no edits:

[{Application1, [{Par11, Val11}, ...]},
 ...
 {ApplicationN, [{ParN1, ValN1}, ...]}].

and now the types, because we're thorough:

• Application = atom(): — Application name.
• Par = atom(): — Name of a configuration parameter.
• Val = term(): — Value of a configuration parameter.

atoms and terms, living in harmony. 🌈

---

🌟 SYS.CONFIG 🌟

okay so when you start Erlang in embedded mode, the system assumes that exactly one system configuration file is used, and it's named sys.config. exactly one. not two. not zero. one. 💅

this file is located in $ROOT/releases/Vsn, where $ROOT is the Erlang/OTP root installation directory and Vsn is the release version. yes, both of those variables, exactly like that. 🎀

Release handling relies on this assumption. like, relies. when you install a new release version, the new sys.config is read and used to update the applications' configurations. that's the whole system bestie. 🔥

⚠️ so this means that specifying another .config file, or more .config files, leads to an inconsistent update of application configurations. inconsistent. not cute. not the vibe. 😭

but!! there is a way to point out other config files from a sys.config. and how you do that is described in the very next section, because we keep it organized. 💜

---

🦋 INCLUDING FILES FROM SYS.CONFIG AND -CONFIGFD CONFIGURATIONS 🦋

so there IS a way to include other configuration files from a sys.config file, and also from a configuration that comes from a file descriptor that's been pointed out with the -configfd command-line argument. bestie, we love options. 🫶

the syntax for including files can be described by the Erlang type language like this:

[{Application, [{Par, Val}]} | IncludeFile].

and the type:

• IncludeFile = string(): — Name of a .config file. the extension .config can be omitted. it's recommended to use absolute paths. if a relative path is used in a sys.config, IncludeFile is searched, first, relative to the sys.config directory, then relative to the current working directory of the emulator. if a relative path is used in a -configfd configuration, IncludeFile is searched, first, relative to the dictionary containing the boot script (see also the -boot command-line argument) for the emulator, then relative to the current working directory of the emulator. and why do we care? because this makes it possible to use sys.config for pointing out other .config files in a release, or in a node started manually using -config or -configfd, with the same result whatever the current working directory is. consistency, slay. ✨

now, when traversing the contents of a sys.config or a -configfd configuration and a filename is encountered, its contents are read and merged with the result so far. and when an application configuration tuple {Application, Env} is found, it's merged with the result so far too. and what does merging mean, you ask? new parameters are added and existing parameter values are overwritten. that's the merge. that's it. 💅

🎀 Example 🎀

sys.config:

["/home/user/myconfig1"
 {myapp,[{par1,val1},{par2,val2}]},
 "/home/user/myconfig2"].

myconfig1.config:

[{myapp,[{par0,val0},{par1,val0},{par2,val0}]}].

myconfig2.config:

[{myapp,[{par2,val3},{par3,val4}]}].

this yields the following environment for myapp:

[{par0,val0},{par1,val1},{par2,val3},{par3,val4}]

look at that merge. look at par2 getting absolutely overtaken by val3. ate. 🔥

⚠️ the run-time system will abort before staring up if an include file specified in sys.config or a -configfd configuration does not exist, or is erroneous. so like, don't do that. however, installing a new release version will not fail if there's an error while loading an include file — instead an error message is returned and the erroneous file is ignored. soft launch of failure, i guess. 💀

---

👀 SEE ALSO 👀

• app(5)
• erts:erl(1)
• OTP Design Principles

go read those too, bestie, i'm not kidding. 📚

---

and that's the whole page, fr fr. this little masterpiece came to you from Ericsson AB, and it's part of kernel 8.5.4.2. mwah. 💖✨🎀🦋🌸💅🫶👑🌈⭐💜