summaryrefslogtreecommitdiff
path: root/doc/examples
diff options
context:
space:
mode:
Diffstat (limited to 'doc/examples')
-rw-r--r--doc/examples/examples.rst12
-rw-r--r--doc/examples/lua_examples.rst102
-rw-r--r--doc/examples/pppd_compat_examples.rst144
3 files changed, 258 insertions, 0 deletions
diff --git a/doc/examples/examples.rst b/doc/examples/examples.rst
new file mode 100644
index 0000000..b50140b
--- /dev/null
+++ b/doc/examples/examples.rst
@@ -0,0 +1,12 @@
+.. _examples:
+
+Examples
+========
+
+.. toctree::
+ :maxdepth: 2
+ :caption: Contents:
+ :includehidden:
+
+ lua_examples.rst
+ pppd_compat_examples.rst
diff --git a/doc/examples/lua_examples.rst b/doc/examples/lua_examples.rst
new file mode 100644
index 0000000..43d88a4
--- /dev/null
+++ b/doc/examples/lua_examples.rst
@@ -0,0 +1,102 @@
+.. _lua_examples:
+
+Lua examples
+============
+
+Important that accel-ppp was built with lua support ``cmake -DLUA=TRUE`` or if system has more modern lua version, need this sets, for example ``cmake -DLUA=5.3``
+
+Example accel-ppp configuration:
+
+.. code-block:: sh
+
+ [ipoe]
+ lua-file=/etc/accel-ppp.lua
+ username=lua:username_func
+
+Create /etc/accel-ppp.lua and edit. Example for D-link switches with Option 82:
+
+.. code-block:: sh
+
+ #!lua
+ function username_func(pkt)
+ v,b1,b2,b3,b4=string.unpack(pkt:agent_remote_id():sub(-4),'bbbb')
+ ip=b1..'.'..b2..'.'..b3..'.'..b4
+ v,port=string.unpack(string.sub(pkt:agent_circuit_id(),'-1'),'b')
+ local username=ip..'-'..port
+ -- print(username)
+ return username
+ end
+
+Object **pkt** has next functions:
+
+**hdr(name)**
+ Will return value which contained in DHCP packet header. ``name`` may receive next params: ``xid``, ``ciaddr``, ``giaddr``, ``chaddr``.
+
+**ifname()**
+ Will return interface name which received packet.
+
+**ipaddr()**
+ Will return client ip address exist in packet header.
+
+**hwaddr()**
+ Will return client MAC address.
+
+**vlan()**
+ Will return client VLAN.
+
+.. code-block:: sh
+
+ local vlan = pkt:vlan()
+ local svid = bit.rshift(vlan,16)
+ local cvid = bit.band(vlan,0xffff)
+
+**options()**
+ Will return table which contains number of DHCP option in received packet.
+
+**option(num)**
+ Will return value with option number ``num``.
+
+**agent_circuit_id()**
+ Will return ``agent_circuit_id`` option 82.
+
+**agent_remote_id()**
+ Will return ``agent_remote_id`` option 82.
+
+.. admonition:: Note:
+
+ All function return type ``string``, except for ``options()``
+
+Also to accel-ppp includes packet **lpack** for disassemble binary data.
+It add to object ``string`` additional function ``unpack(binary, fmt)``, where ``binary`` is string which contain binary data, and ``fmt`` is data format. To ``fmt`` may be sets next data types:
+
+**z** - zero terminated string
+
+**p** - string precended by length byte
+
+**P** - string precended by length word
+
+**f** - float
+
+**d** - double
+
+**c** - int8_t
+
+**b** - uint8_t
+
+**h** - int16_t
+
+**H** - uint16_t
+
+**i** - int32_t
+
+**I** - uint32_t
+
+**l** - int64_t
+
+**L** - uint64_t
+
+**<** - little endian
+
+**>** - big endian
+
+**=** - native endian
diff --git a/doc/examples/pppd_compat_examples.rst b/doc/examples/pppd_compat_examples.rst
new file mode 100644
index 0000000..5333805
--- /dev/null
+++ b/doc/examples/pppd_compat_examples.rst
@@ -0,0 +1,144 @@
+.. _pppd_compat_examples:
+
+pppd-compat examples
+====================
+
+Accel-ppp module ``[pppd-compat]`` is useful to execute scripts when **ip-up|ip-down|ip-change** event for customer's session occurs.
+
+Examples below show how to put cusomer's IPv4 & IPv6 to specific ipsets, depending on the value of received RADIUS-attribute named ``Filter-Id``. For example, it can be useful if one needs to grant access from **customer ipset** only to **specific ipset**.
+
+Example Accel-ppp configuration:
+
+.. code-block:: sh
+
+ [modules]
+ pppd_compat
+
+ [pppd-compat]
+ ip-up=/etc/accel-ppp_ip-up.sh
+ ip-down=/etc/accel-ppp_ip-down.sh
+ ip-change=/etc/accel-ppp_ip-up.sh
+ radattr-prefix=/run/radattr
+
+.. admonition:: Note:
+
+ **ipsets** must exist before scripts are executed.
+
+Example ipsets creation:
+
+.. code-block:: sh
+
+ #!/bin/sh
+
+ ipset create soc_res_v4 hash:net family inet
+ ipset create soc_res_v6 hash:net family inet6
+ ipset create blk_res_v4 hash:net family inet
+ ipset create blk_res_v6 hash:net family inet6
+ ipset create blk_usr_v4 hash:ip family inet
+ ipset create soc_usr_v6 hash:net family inet6
+ ipset create soc_usr_v4 hash:ip family inet
+ ipset create blk_usr_v6 hash:net family inet6
+
+Example /etc/accel-ppp_ip-up.sh script:
+
+.. code-block:: sh
+
+ #!/bin/sh
+
+ # Option "Active".
+ ACTIVE_FILTER_ID=1
+
+ # Option "Paysystems".
+ BLOCK_SET_V4='blk_usr_v4'
+ BLOCK_SET_V6='blk_usr_v6'
+ BLOCK_FILTER_ID=2
+
+ # Option "Social".
+ SOCIAL_SET_V4='soc_usr_v4'
+ SOCIAL_SET_V6='soc_usr_v6'
+ SOCIAL_FILTER_ID=3
+
+ # argv[5], contains IPv4-address,
+ # (https://github.com/xebd/accel-ppp/blob/master/accel-pppd/extra/pppd_compat.c).
+ IPV4=$5
+
+ # argv[1], contains interface name.
+ RADATTR='/run/radattr.'$1
+
+ # Add|delete client's IPv4|IPv6 addresses to a specific ipset.
+ # $IPV6_PREFIX and $IPV6_DELEGATED_PREFIX are environment variables of Accel-ppp,
+ # (https://github.com/xebd/accel-ppp/blob/master/accel-pppd/extra/pppd_compat.c).
+ if [ -f $RADATTR ]; then
+ # Get value of "Filter-Id" RADIUS-attribute.
+ FILTER_ID=$(awk '/Filter-Id/ {print $2}' $RADATTR)
+ if [ $FILTER_ID = $ACTIVE_FILTER_ID ]; then
+ ipset del $BLOCK_SET_V4 $IPV4 -exist -quiet &> /dev/null
+ ipset del $SOCIAL_SET_V4 $IPV4 -exist -quiet &> /dev/null
+ ipset del $BLOCK_SET_V6 $IPV6_PREFIX -exist -quiet &> /dev/null
+ ipset del $SOCIAL_SET_V6 $IPV6_PREFIX -exist -quiet &> /dev/null
+ ipset del $BLOCK_SET_V6 $IPV6_DELEGATED_PREFIX -exist -quiet &> /dev/null
+ ipset del $SOCIAL_SET_V6 $IPV6_DELEGATED_PREFIX -exist -quiet &> /dev/null
+ logger -t ip-change "Allowed: IPv4 $IPV4, IPv6 $IPV6_PREFIX, IPv6-DP $IPV6_DELEGATED_PREFIX"
+ elif [ $FILTER_ID = $BLOCK_FILTER_ID ]; then
+ ipset del $SOCIAL_SET_V4 $IPV4 -exist -quiet &> /dev/null
+ ipset add $BLOCK_SET_V4 $IPV4 -exist -quiet &> /dev/null
+ ipset del $SOCIAL_SET_V6 $IPV6_PREFIX -exist -quiet &> /dev/null
+ ipset add $BLOCK_SET_V6 $IPV6_PREFIX -exist -quiet &> /dev/null
+ ipset del $SOCIAL_SET_V6 $IPV6_DELEGATED_PREFIX -exist -quiet &> /dev/null
+ ipset add $BLOCK_SET_V6 $IPV6_DELEGATED_PREFIX -exist -quiet &> /dev/null
+ logger -t ip-change "Blocked: IPv4 $IPV4, IPv6 $IPV6_PREFIX, IPv6-DP $IPV6_DELEGATED_PREFIX"
+ elif [ $FILTER_ID = $SOCIAL_FILTER_ID ]; then
+ ipset del $BLOCK_SET_V4 $IPV4 -exist -quiet &> /dev/null
+ ipset add $SOCIAL_SET_V4 $IPV4 -exist -quiet &> /dev/null
+ ipset del $BLOCK_SET_V6 $IPV6_PREFIX -exist -quiet &> /dev/null
+ ipset add $SOCIAL_SET_V6 $IPV6_PREFIX -exist -quiet &> /dev/null
+ ipset del $BLOCK_SET_V6 $IPV6_DELEGATED_PREFIX -exist -quiet &> /dev/null
+ ipset add $SOCIAL_SET_V6 $IPV6_DELEGATED_PREFIX -exist -quiet &> /dev/null
+ logger -t ip-change "Social: IPv4 $IPV4, IPv6 $IPV6_PREFIX, IPv6-DP $IPV6_DELEGATED_PREFIX"
+ fi
+ else
+ logger -t ip-change "radattr file not found, $CALLED_SID $CALLING_SID"
+ fi
+
+Example /etc/accel-ppp_ip-down.sh script:
+
+.. code-block:: sh
+
+ #!/bin/sh
+
+ # Option "Blocked".
+ BLOCK_SET_V4='blk_usr_v4'
+ BLOCK_SET_V6='blk_usr_v6'
+
+ # Option "Social".
+ SOCIAL_SET_V4='soc_usr_v4'
+ SOCIAL_SET_V6='soc_usr_v6'
+
+ # argv[5], contains IPv4-address,
+ # (https://github.com/xebd/accel-ppp/blob/master/accel-pppd/extra/pppd_compat.c).
+ IPV4=$5
+
+ # Delete customer's IPv4|Pv6 addresses from all ipsets,
+ # $IPV6_PREFIX and $IPV6_DELEGATED_PREFIX are environment variables from Accel-ppp,
+ # (https://github.com/xebd/accel-ppp/blob/master/accel-pppd/extra/pppd_compat.c).
+ ipset del $BLOCK_SET_V4 $IPV4 -exist -quiet &> /dev/null
+ ipset del $SOCIAL_SET_V4 $IPV4 -exist -quiet &> /dev/null
+ ipset del $BLOCK_SET_V6 $IPV6_PREFIX -exist -quiet &> /dev/null
+ ipset del $SOCIAL_SET_V6 $IPV6_PREFIX -exist -quiet &> /dev/null
+ ipset del $BLOCK_SET_V6 $IPV6_DELEGATED_PREFIX -exist -quiet &> /dev/null
+ ipset del $SOCIAL_SET_V6 $IPV6_DELEGATED_PREFIX -exist -quiet &> /dev/null
+ logger -t ip-change "Removing from all ipsets: IPv4 $IPV4, IPv6 $IPV6_PREFIX, IPv6-DP $IPV6_DELEGATED_PREFIX"
+
+Example iptables/ipv6tables rules:
+
+.. code-block:: sh
+
+ iptables -t filter -A FORWARD -m set --match-set blk_usr_v4 src -m set ! --match-set blk_res_v4 dst -j DROP
+ iptables -t filter -A FORWARD -m set --match-set soc_usr_v4 src -m set ! --match-set soc_res_v4 dst -j DROP
+ iptables -t filter -A FORWARD -m set ! --match-set blk_res_v4 src -m set --match-set blk_usr_v4 dst -j DROP
+ iptables -t filter -A FORWARD -m set ! --match-set soc_res_v4 src -m set --match-set soc_usr_v4 dst -j DROP
+
+ ip6tables -t filter -A FORWARD -m set --match-set blk_usr_v6 src -m set ! --match-set blk_res_v6 dst -j DROP
+ ip6tables -t filter -A FORWARD -m set --match-set soc_usr_v6 src -m set ! --match-set soc_res_v6 dst -j DROP
+ ip6tables -t filter -A FORWARD -m set ! --match-set blk_res_v6 src -m set --match-set blk_usr_v6 dst -j DROP
+ ip6tables -t filter -A FORWARD -m set ! --match-set soc_res_v6 src -m set --match-set soc_usr_v6 dst -j DROP
generated by cgit v1.2.3 (git 2.39.1) at 2025-07-04 00:10:12 +0000