<p>pespin has uploaded this change for <strong>review</strong>.</p><p><a href="https://gerrit.osmocom.org/c/osmo-gsm-tester/+/17487">View Change</a></p><pre style="font-family: monospace,monospace; white-space: pre-wrap;">doc/manuals: Introduce Troubleshooting section about SIGKILL fix<br><br>Add a section describing how to clean up and recover osmo-gsm-tester<br>state after a sigkill is used.<br><br>Change-Id: I4841ab6d44a122140e6352df1fb6543418adc033<br>---<br>M doc/manuals/chapters/troubleshooting.adoc<br>1 file changed, 39 insertions(+), 0 deletions(-)<br><br></pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;">git pull ssh://gerrit.osmocom.org:29418/osmo-gsm-tester refs/changes/87/17487/1</pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;"><span>diff --git a/doc/manuals/chapters/troubleshooting.adoc b/doc/manuals/chapters/troubleshooting.adoc</span><br><span>index a3b5c8b..c7c6868 100644</span><br><span>--- a/doc/manuals/chapters/troubleshooting.adoc</span><br><span>+++ b/doc/manuals/chapters/troubleshooting.adoc</span><br><span>@@ -13,3 +13,42 @@</span><br><span> Careful: if a configuration item consists of digits and starts with a zero, you</span><br><span> need to quote it, or it may be interpreted as an octal notation integer! Please</span><br><span> avoid using the octal notation on purpose, it is not provided intentionally.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+=== {app-name} not running but resources still allocated</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The <<state_dir,reserved_resources.state>> is used to keep shared state of the</span><br><span style="color: hsl(120, 100%, 40%);">+the resources allocated by any {app-name} instance. Each {app-name} instance</span><br><span style="color: hsl(120, 100%, 40%);">+being run is responsible to de-allocate the used resources before exiting. In</span><br><span style="color: hsl(120, 100%, 40%);">+general, upon receiving a shutdown action (ie. 'CTRL+C', 'SIGINT', python</span><br><span style="color: hsl(120, 100%, 40%);">+exception, etc.), {app-name} is able to handle properly the situation and</span><br><span style="color: hsl(120, 100%, 40%);">+de-allocate the resources before the process exits. Similarly, {app-name} also</span><br><span style="color: hsl(120, 100%, 40%);">+takes care of terminating all its children processes being managed before</span><br><span style="color: hsl(120, 100%, 40%);">+exiting itself.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+However, under some circumstances, {app-name} will be unable to de-allocate the</span><br><span style="color: hsl(120, 100%, 40%);">+resources and they will remain allocated for subsequent {app-name} instances</span><br><span style="color: hsl(120, 100%, 40%);">+which try to use them. That situation is usually reached when someone terminates</span><br><span style="color: hsl(120, 100%, 40%);">+{app-name} in a hard way. Main reasons are {app-name} process receiving a</span><br><span style="color: hsl(120, 100%, 40%);">+'SIGKILL' signal ('kill -9 $pid') which cannot be caught, or due to the entire</span><br><span style="color: hsl(120, 100%, 40%);">+host being shut down in a non proper way.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+As a noticeable example, SIGKILL is known to be sent to {app-name} when it runs</span><br><span style="color: hsl(120, 100%, 40%);">+under a jenkins shell script and any of the two following things happen:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+- User presses the red cross icon in the Jenkins UI to terminate the running</span><br><span style="color: hsl(120, 100%, 40%);">+  job.</span><br><span style="color: hsl(120, 100%, 40%);">+- Connection between Jenkins master (UI) and Jenkins slave running the job is</span><br><span style="color: hsl(120, 100%, 40%);">+  lost.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Once this situation is reached, one needs to follow 2 steps:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+- Gain console access to the <<install_main_unit,Main Unit>> and manually clean</span><br><span style="color: hsl(120, 100%, 40%);">+  or completely remove the 'reserved_resources.state' in the</span><br><span style="color: hsl(120, 100%, 40%);">+  <<state_dir,state_dir>>. In general it's a good idea to make sure no</span><br><span style="color: hsl(120, 100%, 40%);">+  {app-name} instance is running at all and then remove completely all files in</span><br><span style="color: hsl(120, 100%, 40%);">+  <<state_dir,state_dir>>, since {app-name} could theoretically have been killed</span><br><span style="color: hsl(120, 100%, 40%);">+  while writing some file and it may have ended up with corrupt content.</span><br><span style="color: hsl(120, 100%, 40%);">+- Gain console access to the <<install_main_unit,Main Unit>> and each of the</span><br><span style="color: hsl(120, 100%, 40%);">+  <<install_slave_unit,Slave Units>> and kill any hanging long-termed processes</span><br><span style="color: hsl(120, 100%, 40%);">+  in there which may have been started by {app-name}. Some popular processes in</span><br><span style="color: hsl(120, 100%, 40%);">+  this list include 'tcpdump', 'osmo-\*', 'srs*', etc.</span><br><span></span><br></pre><p>To view, visit <a href="https://gerrit.osmocom.org/c/osmo-gsm-tester/+/17487">change 17487</a>. To unsubscribe, or for help writing mail filters, visit <a href="https://gerrit.osmocom.org/settings">settings</a>.</p><div itemscope itemtype="http://schema.org/EmailMessage"><div itemscope itemprop="action" itemtype="http://schema.org/ViewAction"><link itemprop="url" href="https://gerrit.osmocom.org/c/osmo-gsm-tester/+/17487"/><meta itemprop="name" content="View Change"/></div></div>

<div style="display:none"> Gerrit-Project: osmo-gsm-tester </div>
<div style="display:none"> Gerrit-Branch: master </div>
<div style="display:none"> Gerrit-Change-Id: I4841ab6d44a122140e6352df1fb6543418adc033 </div>
<div style="display:none"> Gerrit-Change-Number: 17487 </div>
<div style="display:none"> Gerrit-PatchSet: 1 </div>
<div style="display:none"> Gerrit-Owner: pespin <pespin@sysmocom.de> </div>
<div style="display:none"> Gerrit-MessageType: newchange </div>