From b9f47ef6dd127ebffaa25c5a12f5b38ff7bfcf1f Mon Sep 17 00:00:00 2001
From: Dmitriy Eshenko <dmitriy.eshenko@accel-ppp.org>
Date: Tue, 10 Oct 2023 15:00:20 +0300
Subject: Init Accel-ppp docs

---
 doc/debugging/faq.rst   | 83 +++++++++++++++++++++++++++++++++++++++++++++++++
 doc/debugging/index.rst | 54 ++++++++++++++++++++++++++++++++
 2 files changed, 137 insertions(+)
 create mode 100644 doc/debugging/faq.rst
 create mode 100644 doc/debugging/index.rst

(limited to 'doc/debugging')

diff --git a/doc/debugging/faq.rst b/doc/debugging/faq.rst
new file mode 100644
index 0000000..87bd746
--- /dev/null
+++ b/doc/debugging/faq.rst
@@ -0,0 +1,83 @@
+FAQ
+===============
+
+HTB: quantum of class is big
+----------------------------
+When an error appears in the logs:
+
+.. code-block:: sh
+
+  HTB: quantum of class 10001 is big. Consider r2q change.
+
+You need to set a parameter for the shaper:
+
+.. code-block:: sh
+
+  #accel-pp will calculate the value itself
+  moderate-quantum=1
+
+
+How to rotate logs ?
+--------------------
+
+You can use system logrotate utility for it. Put following file to /etc/logrotate.d
+
+.. code-block:: sh
+
+  /var/log/accel-ppp/*.log {
+        missingok
+        sharedscripts
+        postrotate
+                test -r /var/run/accel-pppd.pid && kill -HUP `cat /var/run/accel-pppd.pid`
+        endscript
+  }
+
+I don't see pppd processes, how to manually terminate session ?
+---------------------------------------------------------------
+
+Yes, in fact accel-ppp doesn't use pppd because it has its own ppp implementation.
+To terminate session you may use three methods:
+
+1. Use cli (telnet or tcp):
+
+.. code-block:: sh
+
+  By default telnet listens connections on 2000 port and tcp on 2001 port.
+  $ telnet 127.0.0.1 2000
+  Trying 127.0.0.1...
+  Connected to 127.0.0.1.
+  Escape character is '^]'.
+  accel-ppp version 1.5.0
+  accel-ppp# terminate if ppp0
+
+
+or
+
+.. code-block:: sh
+
+  $ echo 'terminate if ppp0' | nc -q0 127.0.0.1 2001
+
+
+There are also other criterias to select session(s), use help cli command to get more information.
+
+2. Use radius Disconnect-Message:
+
+.. code-block:: sh
+
+  $ echo 'NAS-Port=0' | radclient 127.0.0.1:3799 disconnect testing123
+  Received response ID 170, code 41, length = 20
+
+and you can control it in logs:
+
+.. code-block:: sh
+
+  [2012-01-21|16:48:55]:  info: ppp0: recv [RADIUS|Disconnect-Request id=aa <NAS-Port 0>]
+  [2012-01-21|16:48:55]:  info: ppp0: send [RADIUS|Disconnect-ACK id=aa]
+
+3. Use snmp:
+
+.. code-block:: sh
+
+  $ snmpset -m +ACCEL-PPP-MIB -v 2c -c local 127.0.0.1 ACCEL-PPP-MIB::termByIfName.0 = ppp0
+
+
diff --git a/doc/debugging/index.rst b/doc/debugging/index.rst
new file mode 100644
index 0000000..4e80896
--- /dev/null
+++ b/doc/debugging/index.rst
@@ -0,0 +1,54 @@
+.. _debugging:
+
+Debugging
+=========
+
+Sometimes for debugging need to build accel-ppp with additional flags:
+
+``-DCMAKE_BUILD_TYPE=Debug`` - Include debug information to accel-pppd binary
+
+``-DCMAKE_C_FLAGS='-g -O0'`` - Enable optimization flags
+
+``-DMEMDEBUG=TRUE`` - Set this flag if you want to debug memleak
+
+Allow create core dump files without size limiting, edit /etc/security/limits.conf and add
+
+.. code-block:: sh
+  
+  *  soft  core  unlimited
+
+Or run ``ulimit -c unlimited`` for apply immediately
+
+Edit ``/etc/sysctl.conf`` to define core dump file name and location, add
+
+.. code-block:: sh
+  
+  kernel.core_uses_pid = 1
+  kernel.core_pattern = /root/core-%e-%p
+
+And apply ``sysctl -p``
+
+If accel-ppp runs as systemd service to allow create coredumps it is necessary to add ``DefaultLimitCORE=infinity`` to ``/etc/systemd/system.conf`` and run ``systemctl daemon-reexec`` to activate new params.
+
+Recommended: to create a self-checking program with predefined mistake. Create ``test.c`` with the following content
+
+.. code-block:: sh
+  
+  int main() {
+    *(char *)0 = 0;
+    return 0;
+  }
+
+Compile this program ``gcc test.c`` and run ``./a.out``
+
+If core files appear in ``/root`` directory and in ``dmesg`` exist output ``a.out[xxxx]: segfault at ...`` then all done properly.
+
+**Run accel-ppp in GDB (GNU Debugger)**
+
+If you want to run accel-ppp in GDB, necessary disable logratation for accel-ppp log files.
+
+.. code-block:: sh
+  
+  gdb -ex=run  --args accel-pppd -c /etc/accel-ppp.conf -p /var/run/accel-ppp.pid
+  
+ 
-- 
cgit v1.2.3