diff options
Diffstat (limited to 'lib/kernel/doc/src/heart.xml')
| -rw-r--r-- | lib/kernel/doc/src/heart.xml | 174 |
1 files changed, 82 insertions, 92 deletions
diff --git a/lib/kernel/doc/src/heart.xml b/lib/kernel/doc/src/heart.xml index 9da4773f2d..5b5b71e521 100644 --- a/lib/kernel/doc/src/heart.xml +++ b/lib/kernel/doc/src/heart.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2013</year> + <year>1996</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -29,93 +29,84 @@ <rev>A</rev> </header> <module>heart</module> - <modulesummary>Heartbeat Monitoring of an Erlang Runtime System</modulesummary> + <modulesummary>Heartbeat monitoring of an Erlang runtime system.</modulesummary> <description> <p>This modules contains the interface to the <c>heart</c> process. <c>heart</c> sends periodic heartbeats to an external port program, which is also named <c>heart</c>. The purpose of - the heart port program is to check that the Erlang runtime system + the <c>heart</c> port program is to check that the Erlang runtime system it is supervising is still running. If the port program has not received any heartbeats within <c>HEART_BEAT_TIMEOUT</c> seconds - (default is 60 seconds), the system can be rebooted. Also, if - the system is equipped with a hardware watchdog timer and is - running Solaris, the watchdog can be used to supervise the entire - system.</p> - <p>An Erlang runtime system to be monitored by a heart program, - should be started with the command line flag <c>-heart</c> (see - also <seealso marker="erts:erl">erl(1)</seealso>). The <c>heart</c> - process is then started automatically:</p> + (defaults to 60 seconds), the system can be rebooted.</p> + <p>An Erlang runtime system to be monitored by a heart program + is to be started with command-line flag <c>-heart</c> (see + also <seealso marker="erts:erl"><c>erl(1)</c></seealso>). + The <c>heart</c> process is then started automatically:</p> <pre> % <input>erl -heart ...</input></pre> - <p>If the system should be rebooted because of missing heart-beats, - or a terminated Erlang runtime system, the environment variable - <c>HEART_COMMAND</c> has to be set before the system is started. - If this variable is not set, a warning text will be printed but - the system will not reboot. However, if the hardware watchdog is - used, it will trigger a reboot <c>HEART_BEAT_BOOT_DELAY</c> - seconds later nevertheless (default is 60).</p> - <p>To reboot on the WINDOWS platform <c>HEART_COMMAND</c> can be + <p>If the system is to be rebooted because of missing heartbeats, + or a terminated Erlang runtime system, environment variable + <c>HEART_COMMAND</c> must be set before the system is started. + If this variable is not set, a warning text is printed but + the system does not reboot.</p> + <p>To reboot on Windows, <c>HEART_COMMAND</c> can be set to <c>heart -shutdown</c> (included in the Erlang delivery) - or of course to any other suitable program which can activate a - reboot.</p> - <p>The hardware watchdog will not be started under Solaris if - the environment variable <c>HW_WD_DISABLE</c> is set.</p> - <p>The <c>HEART_BEAT_TIMEOUT</c> and <c>HEART_BEAT_BOOT_DELAY</c> - environment variables can be used to configure the heart timeouts, - they can be set in the operating system shell before Erlang is - started or be specified at the command line:</p> + or to any other suitable program that can activate a reboot.</p> + <p>The environment variable <c>HEART_BEAT_TIMEOUT</c> + can be used to configure the heart + time-outs; it can be set in the operating system shell before Erlang + is started or be specified at the command line:</p> <pre> % <input>erl -heart -env HEART_BEAT_TIMEOUT 30 ...</input></pre> <p>The value (in seconds) must be in the range 10 < X <= 65535.</p> - <p>It should be noted that if the system clock is adjusted with - more than <c>HEART_BEAT_TIMEOUT</c> seconds, <c>heart</c> will - timeout and try to reboot the system. This can happen, for - example, if the system clock is adjusted automatically by use of - NTP (Network Time Protocol).</p> - - <p> If a crash occurs, an <c><![CDATA[erl_crash.dump]]></c> will <em>not</em> be written - unless the environment variable <c><![CDATA[ERL_CRASH_DUMP_SECONDS]]></c> is set. - </p> - + <p>Notice that if the system clock is adjusted with + more than <c>HEART_BEAT_TIMEOUT</c> seconds, <c>heart</c> + times out and tries to reboot the system. This can occur, for + example, if the system clock is adjusted automatically by use of the + Network Time Protocol (NTP).</p> + <p>If a crash occurs, an <c><![CDATA[erl_crash.dump]]></c> is <em>not</em> + written unless environment variable + <c><![CDATA[ERL_CRASH_DUMP_SECONDS]]></c> is set:</p> <pre> % <input>erl -heart -env ERL_CRASH_DUMP_SECONDS 10 ...</input></pre> - - <p> If a regular core dump is wanted, let heart know by setting the kill signal to abort - using the environment variable <c><![CDATA[HEART_KILL_SIGNAL=SIGABRT]]></c>. - If unset, or not set to <c><![CDATA[SIGABRT]]></c>, the default behaviour will be a kill - signal using <c><![CDATA[SIGKILL]]></c>. - </p> - + <p>If a regular core dump is wanted, let <c>heart</c> know by setting + the kill signal to abort using environment variable + <c><![CDATA[HEART_KILL_SIGNAL=SIGABRT]]></c>. If unset, or not set to + <c><![CDATA[SIGABRT]]></c>, the default behavior is a kill signal using + <c><![CDATA[SIGKILL]]></c>:</p> <pre> % <input>erl -heart -env HEART_KILL_SIGNAL SIGABRT ...</input></pre> - - <p> - Furthermore, <c><![CDATA[ERL_CRASH_DUMP_SECONDS]]></c> has the following behaviour on - <c>heart</c>: + <p> If heart should <em>not</em> kill the Erlang runtime system, this can be indicated + using the environment variable <c><![CDATA[HEART_NO_KILL=TRUE]]></c>. + This can be useful if the command executed by heart takes care of this, + for example as part of a specific cleanup sequence. + If unset, or not set to <c><![CDATA[TRUE]]></c>, the default behaviour + will be to kill as described above. </p> - <taglist> - <tag><c><![CDATA[ERL_CRASH_DUMP_SECONDS=0]]></c></tag> - <item><p> - Suppresses the writing a crash dump file entirely, - thus rebooting the runtime system immediately. - This is the same as not setting the environment variable. - </p> - </item> - <tag><c><![CDATA[ERL_CRASH_DUMP_SECONDS=-1]]></c></tag> - <item><p> Setting the environment variable to a negative value will not reboot - the runtime system until the crash dump file has been completly written. - </p> - </item> - <tag><c><![CDATA[ERL_CRASH_DUMP_SECONDS=S]]></c></tag> - <item><p> - Heart will wait for <c>S</c> seconds to let the crash dump file be written. - After <c>S</c> seconds <c>heart</c> will reboot the runtime system regardless of - the crash dump file has been written or not. - </p> - </item> - </taglist> - <p>In the following descriptions, all function fails with reason + <pre> +% <input>erl -heart -env HEART_NO_KILL 1 ...</input></pre> + + <p>Furthermore, <c><![CDATA[ERL_CRASH_DUMP_SECONDS]]></c> has the + following behavior on <c>heart</c>:</p> + <taglist> + <tag><c><![CDATA[ERL_CRASH_DUMP_SECONDS=0]]></c></tag> + <item><p>Suppresses the writing of a crash dump file entirely, + thus rebooting the runtime system immediately. + This is the same as not setting the environment variable.</p> + </item> + <tag><c><![CDATA[ERL_CRASH_DUMP_SECONDS=-1]]></c></tag> + <item><p>Setting the environment variable to a negative value does not + reboot the runtime system until the crash dump file is completly + written.</p> + </item> + <tag><c><![CDATA[ERL_CRASH_DUMP_SECONDS=S]]></c></tag> + <item><p><c>heart</c> waits for <c>S</c> seconds to let the crash dump + file be written. After <c>S</c> seconds, <c>heart</c> reboots the + runtime system, whether the crash dump file is written or not.</p> + </item> + </taglist> + <p>In the following descriptions, all functions fail with reason <c>badarg</c> if <c>heart</c> is not started.</p> </description> @@ -128,37 +119,36 @@ <funcs> <func> <name name="set_cmd" arity="1"/> - <fsummary>Set a temporary reboot command</fsummary> + <fsummary>Set a temporary reboot command.</fsummary> <desc> - <p>Sets a temporary reboot command. This command is used if + <p>Sets a temporary reboot command. This command is used if a <c>HEART_COMMAND</c> other than the one specified with - the environment variable should be used in order to reboot - the system. The new Erlang runtime system will (if it - misbehaves) use the environment variable - <c>HEART_COMMAND</c> to reboot.</p> - - <p>Limitations: The <c><anno>Cmd</anno></c> command string - will be sent to the heart program as a ISO-latin-1 or UTF-8 - encoded binary depending on the file name encoding mode of the - emulator (see - <seealso marker="kernel:file#native_name_encoding/0"><c>file:native_name_encoding/0</c></seealso>). - The size of the encoded binary must be less than 2047 bytes.</p> + the environment variable is to be used to reboot + the system. The new Erlang runtime system uses (if it misbehaves) + environment variable <c>HEART_COMMAND</c> to reboot.</p> + <p>Limitations: Command string <c><anno>Cmd</anno></c> is sent to the + <c>heart</c> program as an ISO Latin-1 or UTF-8 encoded binary, + depending on the filename encoding mode of the emulator (see + <seealso marker="kernel:file#native_name_encoding/0"><c>file:native_name_encoding/0</c></seealso>). + The size of the encoded binary must be less than 2047 bytes.</p> </desc> </func> + <func> <name name="clear_cmd" arity="0"/> - <fsummary>Clear the temporary boot command</fsummary> + <fsummary>Clear the temporary boot command.</fsummary> <desc> <p>Clears the temporary boot command. If the system terminates, the normal <c>HEART_COMMAND</c> is used to reboot.</p> </desc> </func> + <func> <name name="get_cmd" arity="0"/> - <fsummary>Get the temporary reboot command</fsummary> + <fsummary>Get the temporary reboot command.</fsummary> <desc> - <p>Get the temporary reboot command. If the command is cleared, - the empty string will be returned.</p> + <p>Gets the temporary reboot command. If the command is cleared, + the empty string is returned.</p> </desc> </func> @@ -166,12 +156,12 @@ <name name="set_callback" arity="2"/> <fsummary>Set a validation callback</fsummary> <desc> - <p> This validation callback will be executed before any heartbeat sent - to the port program. For the validation to succeed it needs to return - with the value <c>ok</c>. + <p> This validation callback will be executed before any + heartbeat is sent to the port program. For the validation to + succeed it needs to return with the value <c>ok</c>. </p> - <p> An exception within the callback will be treated as a validation failure. </p> - <p> The callback will be removed if the system reboots. </p> + <p>An exception within the callback will be treated as a validation failure.</p> + <p>The callback will be removed if the system reboots.</p> </desc> </func> <func> |