Erlang Run-Time System Application (ERTS)
User's Guide
Version 6.1

Chapters

• Communication in Erlang
  • Top of chapter
  • Passing of Signals
  • Synchronous Communication
  • Implementation
• Time and time correction in Erlang
  • Top of chapter
  • What does time correction mean in my system?
  • Where does Erlang use corrected time?
  • What is erlang:now/0 really?
  • Should I use erlang:now/0 or os:timestamp/0
  • Turning off time correction
• Match specifications in Erlang
  • Top of chapter
  • Grammar
  • Function descriptions
  • Variables and literals
  • Execution of the match
  • Differences between match specifications in ETS and tracing
  • Examples
• How to interpret the Erlang crash dumps
  • Top of chapter
  • General information
  • Memory information
  • Internal table information
  • Allocated areas
  • Allocator
  • Process information
  • Port information
  • ETS tables
  • Timers
  • Distribution information
  • Loaded module information
  • Fun information
  • Process Data
  • Atoms
  • Disclaimer
• How to implement an alternative carrier for the Erlang distribution
  • Top of chapter
  • Introduction
  • The driver
  • Putting it all together
• The Abstract Format
  • Top of chapter
  • Module declarations and forms
  • Atomic literals
  • Patterns
  • Expressions
  • Clauses
  • Guards
  • The abstract format after preprocessing
• tty - A command line interface
  • Top of chapter
  • Normal Mode
  • Shell Break Mode
• How to implement a driver
  • Top of chapter
  • Introduction
  • Sample driver
  • Compiling and linking the sample driver
  • Calling a driver as a port in Erlang
  • Sample asynchronous driver
  • An asynchronous driver using driver_async
• Inet configuration
  • Top of chapter
  • Introduction
  • Configuration Data
  • User Configuration Example
• External Term Format
  • Top of chapter
  • Introduction
  • Distribution header
  • ATOM_CACHE_REF
  • SMALL_INTEGER_EXT
  • INTEGER_EXT
  • FLOAT_EXT
  • ATOM_EXT
  • REFERENCE_EXT
  • PORT_EXT
  • PID_EXT
  • SMALL_TUPLE_EXT
  • LARGE_TUPLE_EXT
  • MAP_EXT
  • NIL_EXT
  • STRING_EXT
  • LIST_EXT
  • BINARY_EXT
  • SMALL_BIG_EXT
  • LARGE_BIG_EXT
  • NEW_REFERENCE_EXT
  • SMALL_ATOM_EXT
  • FUN_EXT
  • NEW_FUN_EXT
  • EXPORT_EXT
  • BIT_BINARY_EXT
  • NEW_FLOAT_EXT
  • ATOM_UTF8_EXT
  • SMALL_ATOM_UTF8_EXT
• Distribution Protocol
  • Top of chapter
  • EPMD Protocol
  • Distribution Handshake
  • Protocol between connected nodes
  • New Ctrlmessages for distrvsn = 1 (OTP R4)
  • New Ctrlmessages for distrvsn = 2
  • New Ctrlmessages for distrvsn = 3 (OTP R5C)
  • New Ctrlmessages for distrvsn = 4 (OTP R6)

9 Inet configuration

9.1  Introduction

This chapter tells you how the Erlang runtime system is configured for IP communication. It also explains how you may configure it for your own particular needs by means of a configuration file. The information here is mainly intended for users with special configuration needs or problems. There should normally be no need for specific settings for Erlang to function properly on a correctly IP configured platform.

When Erlang starts up it will read the kernel variable inetrc which, if defined, should specify the location and name of a user configuration file. Example:

% erl -kernel inetrc '"./cfg_files/erl_inetrc"'

Note that the usage of a .inetrc file, which was supported in earlier Erlang versions, is now obsolete.

A second way to specify the configuration file is to set the environment variable ERL_INETRC to the full name of the file. Example (bash):

% export ERL_INETRC=./cfg_files/erl_inetrc

Note that the kernel variable inetrc overrides this environment variable.

If no user configuration file is specified and Erlang is started in non-distributed or short name distributed mode, Erlang will use default configuration settings and a native lookup method that should work correctly under most circumstances. Erlang will not read any information from system inet configuration files (like /etc/host.conf, /etc/nsswitch.conf, etc) in these modes, except for /etc/resolv.conf and /etc/hosts that is read and monitored for changes on Unix platforms for the internal DNS client inet_res.

If Erlang is started in long name distributed mode, it needs to get the domain name from somewhere and will read system inet configuration files for this information. Any hosts and resolver information found then is also recorded, but not used as long as Erlang is configured for native lookups. (The information becomes useful if the lookup method is changed to 'file' or 'dns', see below).

Native lookup (system calls) is always the default resolver method. This is true for all platforms except VxWorks and OSE Delta where 'file' or 'dns' is used (in that order of priority).

On Windows platforms, Erlang will search the system registry rather than look for configuration files when started in long name distributed mode.

9.2  Configuration Data

Erlang records the following data in a local database if found in system inet configuration files (or system registry):

• Host names and addresses
• Domain name
• Nameservers
• Search domains
• Lookup method

This data may also be specified explicitly in the user configuration file. The configuration file should contain lines of configuration parameters (each terminated with a full stop). Some parameters add data to the configuration (e.g. host and nameserver), others overwrite any previous settings (e.g. domain and lookup). The user configuration file is always examined last in the configuration process, making it possible for the user to override any default values or previously made settings. Call inet:get_rc() to view the state of the inet configuration database.

These are the valid configuration parameters:

{file, Format, File}.

Format = atom()

File = string()

Specify a system file that Erlang should read configuration data from. Format tells the parser how the file should be interpreted: resolv (Unix resolv.conf), host_conf_freebsd (FreeBSD host.conf), host_conf_bsdos (BSDOS host.conf), host_conf_linux (Linux host.conf), nsswitch_conf (Unix nsswitch.conf) or hosts (Unix hosts). File should specify the name of the file with full path.

{resolv_conf, File}.

File = string()

Specify a system file that Erlang should read resolver configuration from for the internal DNS client inet_res, and monitor for changes, even if it does not exist. The path must be absolute.

This may override the configuration parameters nameserver and search depending on the contents of the specified file. They may also change any time in the future reflecting the file contents.

If the file is specified as an empty string "", no file is read nor monitored in the future. This emulates the old behaviour of not configuring the DNS client when the node is started in short name distributed mode.

If this parameter is not specified it defaults to /etc/resolv.conf unless the environment variable ERL_INET_ETC_DIR is set which defines the directory for this file to some maybe other than /etc.

{hosts_file, File}.

File = string()

Specify a system file that Erlang should read resolver configuration from for the internal hosts file resolver and monitor for changes, even if it does not exist. The path must be absolute.

These host entries are searched after all added with {file, hosts, File} above or {host, IP, Aliases} below when the lookup option file is used.

If the file is specified as an empty string "", no file is read nor monitored in the future. This emulates the old behaviour of not configuring the DNS client when the node is started in short name distributed mode.

If this parameter is not specified it defaults to /etc/hosts unless the environment variable ERL_INET_ETC_DIR is set which defines the directory for this file to some maybe other than /etc.

{registry, Type}.

Type = atom()

Specify a system registry that Erlang should read configuration data from. Currently, win32 is the only valid option.

{host, IP, Aliases}.

IP = tuple()

Aliases = [string()]

Add host entry to the hosts table.

{domain, Domain}.

Domain = string()

Set domain name.

{nameserver, IP [,Port]}.

IP = tuple()

Port = integer()

Add address (and port, if other than default) of primary nameserver to use for inet_res.

{alt_nameserver, IP [,Port]}.

IP = tuple()

Port = integer()

Add address (and port, if other than default) of secondary nameserver for inet_res.

{search, Domains}.

Domains = [string()]

Add search domains for inet_res.

{lookup, Methods}.

Methods = [atom()]

Specify lookup methods and in which order to try them. The valid methods are: native (use system calls), file (use host data retrieved from system configuration files and/or the user configuration file) or dns (use the Erlang DNS client inet_res for nameserver queries).

The lookup method string tries to parse the hostname as a IPv4 or IPv6 string and return the resulting IP address. It is automatically tried first when native is not in the Methods list. To skip it in this case the pseudo lookup method nostring can be inserted anywhere in the Methods list.

{cache_size, Size}.

Size = integer()

Set size of resolver cache. Default is 100 DNS records.

{cache_refresh, Time}.

Time = integer()

Set how often (in millisec) the resolver cache for inet_res. is refreshed (i.e. expired DNS records are deleted). Default is 1 h.

{timeout, Time}.

Time = integer()

Set the time to wait until retry (in millisec) for DNS queries made by inet_res. Default is 2 sec.

{retry, N}.

N = integer()

Set the number of DNS queries inet_res will try before giving up. Default is 3.

{inet6, Bool}.

Bool = true | false

Tells the DNS client inet_res to look up IPv6 addresses. Default is false.

{usevc, Bool}.

Bool = true | false

Tells the DNS client inet_res to use TCP (Virtual Circuit) instead of UDP. Default is false.

{edns, Version}.

Version = false | 0

Sets the EDNS version that inet_res will use. The only allowed is zero. Default is false which means to not use EDNS.

{udp_payload_size, Size}.

N = integer()

Sets the allowed UDP payload size inet_res will advertise in EDNS queries. Also sets the limit when the DNS query will be deemed too large for UDP forcing a TCP query instead, which is not entirely correct since the advertised UDP payload size of the individual nameserver is what should be used, but this simple strategy will do until a more intelligent (probing, caching) algorithm need be implemented. The default is 1280 which stems from the standard Ethernet MTU size.

{udp, Module}.

Module = atom()

Tell Erlang to use other primitive UDP module than inet_udp.

{tcp, Module}.

Module = atom()

Tell Erlang to use other primitive TCP module than inet_tcp.

clear_hosts.

Clear the hosts table.

clear_ns.

Clear the list of recorded nameservers (primary and secondary).

clear_search.

Clear the list of search domains.

9.3  User Configuration Example

Here follows a user configuration example.

Assume a user does not want Erlang to use the native lookup method, but wants Erlang to read all information necessary from start and use that for resolving names and addresses. In case lookup fails, Erlang should request the data from a nameserver (using the Erlang DNS client, set to use EDNS allowing larger responses). The resolver configuration will be updated when its configuration file changes, furthermore, DNS records should never be cached. The user configuration file (in this example named erl_inetrc, stored in directory ./cfg_files) could then look like this (Unix):

      %% -- ERLANG INET CONFIGURATION FILE --
      %% read the hosts file
      {file, hosts, "/etc/hosts"}.
      %% add a particular host
      {host, {134,138,177,105}, ["finwe"]}.
      %% do not monitor the hosts file
      {hosts_file, ""}.
      %% read and monitor nameserver config from here
      {resolv_conf, "/usr/local/etc/resolv.conf"}.
      %% enable EDNS
      {edns,0}.
      %% disable caching
      {cache_size, 0}.
      %% specify lookup method
      {lookup, [file, dns]}.

And Erlang could, for example, be started like this:

% erl -sname my_node -kernel inetrc '"./cfg_files/erl_inetrc"'