diff options
| author | Dmitriy Eshenko <dmitriy.eshenko@accel-ppp.org> | 2023-10-10 15:00:20 +0300 |
|---|---|---|
| committer | Dmitriy Eshenko <dmitriy.eshenko@accel-ppp.org> | 2023-10-10 15:00:20 +0300 |
| commit | b9f47ef6dd127ebffaa25c5a12f5b38ff7bfcf1f (patch) | |
| tree | 3402eaea2ba9e2be551a10a8685a4acdb3cfde53 | |
| download | accel-ppp.github.io-b9f47ef6dd127ebffaa25c5a12f5b38ff7bfcf1f.tar.gz accel-ppp.github.io-b9f47ef6dd127ebffaa25c5a12f5b38ff7bfcf1f.zip | |
Init Accel-ppp docs
49 files changed, 3095 insertions, 0 deletions
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml new file mode 100644 index 0000000..a3cec12 --- /dev/null +++ b/.github/workflows/documentation.yml @@ -0,0 +1,28 @@ +name: documentation + +on: [push, pull_request, workflow_dispatch] + +permissions: + contents: write + +jobs: + docs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: actions/setup-python@v3 + - name: Install dependencies + run: | + pip install sphinx sphinx_rtd_theme myst_parser + - name: Sphinx build + run: | + sphinx-build doc _build + - name: Deploy to GitHub Pages + uses: peaceiris/actions-gh-pages@v3 + if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }} + with: + publish_branch: gh-pages + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: _build/ + force_orphan: true + diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..e35d885 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +_build diff --git a/doc/.gitkeep b/doc/.gitkeep new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/doc/.gitkeep diff --git a/doc/_static/.gitkeep b/doc/_static/.gitkeep new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/doc/_static/.gitkeep diff --git a/doc/_static/images/favicon.ico b/doc/_static/images/favicon.ico Binary files differnew file mode 100644 index 0000000..7700990 --- /dev/null +++ b/doc/_static/images/favicon.ico diff --git a/doc/_static/images/logo.png b/doc/_static/images/logo.png Binary files differnew file mode 100644 index 0000000..644e42d --- /dev/null +++ b/doc/_static/images/logo.png diff --git a/doc/_templates/.gitkeep b/doc/_templates/.gitkeep new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/doc/_templates/.gitkeep diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 0000000..bfd0e00 --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,30 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'Accel-ppp' +copyright = '2023, Accel-ppp Dev' +author = 'Accel-ppp Dev' +release = '1.12' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = ['sphinx_rtd_theme'] + +templates_path = ['_templates'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = "sphinx_rtd_theme" +html_static_path = ['_static'] +html_favicon = '_static/images/favicon.ico' +html_logo = '_static/images/logo.png' diff --git a/doc/configuration/chap_secrets.rst b/doc/configuration/chap_secrets.rst new file mode 100644 index 0000000..cd1ef8a --- /dev/null +++ b/doc/configuration/chap_secrets.rst @@ -0,0 +1,59 @@ +[chap-secrets] +============== + +*Chap-secret* is the module of authentication which works with user authentication data and other data (username, password, ip address, speed etc.) stored as local file. Currently *accel-ppp* may works only with one of the authentication method, chap-secrets or RADIUS. RADIUS has more priority if set in ``[modules]`` section. Remove or *#comment* ``radius`` from section ``[modules]`` if you want use ``chap-secrets``. Example: + +.. code-block:: sh + + [modules] + chap-secrets + #radius + +Configuration +------------- + +**chap-secrets=/path/to/file** + By default is ``chap-secrets=/etc/ppp/chap-secrets`` + + Specifies alternate chap-secrets file location. + +**username-hash=hash1[,hash2]** + By default is not defined. + + Specifies hash chain to calculate username hash. hash1, hash2 are openssl known digest names (md5, sha1, etc). + For example, ``username-hash=md5,sha1`` means hash username through md5 and then binary result hash through sha1. + Username have to be specified as hexadecimal dump of digest result.Password field have to be encrypted using smbencrypt (NT Hash part). + +**encrypted=0|1** + By default is disabled: ``encrypted=0`` + + Specifies either chap-secrets is encrypted. + +.. admonition:: Note: + + Encryption is incompatible with auth_chap_md5 module. + + To enable chap-secrets encryption ablity accel-ppp must be compiled with -DCRYPTO=OPENSSL (which is default). + +**gw-ip-address=x.x.x.x[/mask]** + By default is not defined. + + Specifies address to use as local address of ppp interfaces if chap-secrets is used for IP address assignment. Mask is used for IPoE. + +Chap-secrets file example +------------------------- + +.. code-block:: sh + + #client server secret ip-address speed + user001 * password1 100.64.100.1 20480/10240 + user002 * passowrd2 * 10240/10240 + user003 * passowrd3 ip_pool1 10240 + eth0.101 * eth0.101 ipoe_pool 20480 + 100.64.0.2 * 100.64.0.2 * + +* The first column contain *username*. +* The second column is only keep for support chap secrets files standard. +* The third column contain secret or password. +* The fourth column may contain allocated ip address or pool name which configured in ``[ip-pool]`` section. +* The fifth column contain rate-limit. diff --git a/doc/configuration/cli.rst b/doc/configuration/cli.rst new file mode 100644 index 0000000..9c37d08 --- /dev/null +++ b/doc/configuration/cli.rst @@ -0,0 +1,67 @@ +.. _cli_configuration: + +[cli] +===== + +Configuration overview of the command line interface. + +**verbose=1|2** + By default ``verbose=1`` + + If ``verbose=1`` then cli module will log IP address of each connection. + + If ``verbose=2`` then cli module will also log passed commands. + +**tcp=host:port** + By default is not defined. + + Defines on which IP address and port the TCP module will listen for incoming connections. When host is empty, the TCP module listens on all local interfaces. It isn't loaded if this option isn't defined. + +**telnet=host:port** + By default is not defined. + + Defines on which IP address and port the Telnet module will listen for incoming connections. When host is empty, the Telnet module listens on all local interfaces. It isn't loaded if this option isn't defined. + +**password=passwd** + By default is not defined. + + Defines the password to be used by the TCP and Telnet modules for authenticating clients. No authentication is performed if this option isn't defined. + +**prompt=prompt** + By default ``prompt=accel-ppp`` + + Defines the prompt string used by the Telnet module. + +**history-file=filename** + By default ``history-file=/var/lib/accel-ppp/history`` + + Defines the file used by the Telnet module for loading and storing its command history. + +**sessions-columns=column_list** + By default ``sessions-columns=ifname,username,calling-sid,ip,rate-limit,type,comp,state,uptime`` + + Defines the default set of columns to be displayed by the ``show sessions`` command. Invalid column names are silently discarded. All possible params: + + * ``ifname`` - interface name + * ``username`` - username + * ``calling-sid`` - calling station identifier, for *PPPoE* and *IPoE start=dhcpv4* is client mac-address, for *PPTP*, *L2TP*, *SSTP* and *IPoE start=up* is client ip addres. + * ``called-sid`` - called station identifier, for *PPPoE* and *IPoE start=dhcpv4* is server mac-address, for *PPTP*, *L2TP*, *SSTP* and *IPoE start=up* is server ip addres. + * ``sid`` - session identifier + * ``ip`` - client ip address + * ``ip6`` - client ipv6 prefix + * ``ip6-dp`` - delegated ipv6 prefix for client + * ``rate-limit`` - rate-limit, required param ``[modules]shaper``, otherwise this column not displayed. + * ``type`` - session type, may contain next connection types: *ipoe*, *pppoe*, *pptp*, *l2tp*, *sstp* + * ``comp`` - compression/ecnryption method + * ``state`` - state of session, may contain next states: *start*, *active*, *finish* + * ``uptime`` - human readable session uptime + * ``uptime-raw`` - session uptime in seconds + * ``rx-bytes`` - human readable received bytes + * ``tx-bytes`` - human readable transmitted bytes + * ``rx-bytes-raw`` - received bytes + * ``tx-bytes-raw`` - transmitted bytes + * ``rx-pkts`` - received packets + * ``tx-pkts`` - transmitted packets + * ``netns`` - network namespace name + * ``vrf`` - Virtual Routing and Forwarding + * ``ipoe-type`` - IPoE session type (UP/DHCP) diff --git a/doc/configuration/common.rst b/doc/configuration/common.rst new file mode 100644 index 0000000..f041d15 --- /dev/null +++ b/doc/configuration/common.rst @@ -0,0 +1,49 @@ +[common] +======== + +Contains common params for all connection types + + +**single-session=replace|deny** + By default is not defined. + + Specifies whether accel-ppp should control sessions count. If this option is absent session count control is turned off. If this option is ``replace`` then accel-ppp will terminate first session when second is authorized. If this option is ``deny`` then accel-ppp will deny second session authorization. + +**sid-case=upper|lower** + By default is ``sid-case=lower`` + + Specifies in which case generate session identifier (attribute ``Acct-Session-Id``). + +**sid-source=urandom|seq** + By default ``sid-source=urandom`` + + Specifies method assign session id. + + * ``urandom`` - assign session id by random method + * ``seq`` - assign session id by sequence method + +**seq-file=path** + By default is ``seq-file=/var/lib/accel-ppp/seq`` + + Path to file for sessions sequence number. Start sequence number may be set there (default /var/lib/accel-ppp/seq). + +**max-sessions=n** + By default is disabled ``max-sessions=0`` + + Specifies maximum sessions which server may processed. After reaching ``max-sessions`` accel-ppp will ignore connection tries for new sessions. + +**max-starting=n** + By default is disabled ``max-starting=0`` + + Specifies maximum concurrent session attempts which server may processed. + +**check-ip=0|1** + y default is: ``check-ip=0`` + + Specifies whether accel-ppp should check if IP already assigned to other ppp or ipoe interface. + +**netns-run-dir=/path/to/netns** + By default: ``netns-run-dir=/var/run/netns`` + + Specifies path where accel-ppp should find netns objects + diff --git a/doc/configuration/configuration.rst b/doc/configuration/configuration.rst new file mode 100644 index 0000000..850e42f --- /dev/null +++ b/doc/configuration/configuration.rst @@ -0,0 +1,45 @@ +Configuration +============= + +Accel-pppd reads options from configuration file, it usually located at ``/etc/accel-ppp.conf`` but may be redefine daemon input arguments ``accel-pppd -c /path/to/accel-ppp.conf`` + +Configuration file consists of sections in form: + +.. code-block:: sh + + [section1] + name1=val1 + name2=val2 + name3 + + [section2] + .... + + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + :includehidden: + + modules.rst + core.rst + common.rst + radius.rst + chap_secrets.rst + ppp.rst + pppoe.rst + pptp.rst + l2tp.rst + ipoe.rst + ip-pool.rst + sstp.rst + dns.rst + ipv6-dns.rst + ipv6-pool.rst + ipv6-nd.rst + ipv6-dhcp.rst + shaper.rst + log.rst + cli.rst + pppd_compat.rst + snmp.rst diff --git a/doc/configuration/core.rst b/doc/configuration/core.rst new file mode 100644 index 0000000..265545f --- /dev/null +++ b/doc/configuration/core.rst @@ -0,0 +1,12 @@ +[core] +====== + +Section [core] consist main daemon params. + +* **log-error=path** - path to file for core module error logging. +* **thread-count=n** - number of working threads, optimal - number of processors/cores. + +.. admonition:: Note: + + Can’t change with reload, for apply changes need daemon restart with drop active sessions. + diff --git a/doc/configuration/dns.rst b/doc/configuration/dns.rst new file mode 100644 index 0000000..0ba80e2 --- /dev/null +++ b/doc/configuration/dns.rst @@ -0,0 +1,34 @@ +[dns] +===== + +Overview DNS section. + +**dns1=x.x.x.x** + By default is not defined. + + Specifies primary DNS to be sent to peer. + +**dns2=x.x.x.x** + By default is not defined. + + Specifies secondary DNS to be sent to peer. + +.. admonition:: Note: + + Params in this section also may be applied with ``accel-cmd reload`` command, but for new connections. + +Also *accel-ppp* has very interesting way to allocate DNS addresses which sent RADIUS server. Received RADIUS attributes is more prior than params in config. For *ppp* (pppoe, pptp, l2tp, sstp) connection type used attributes ``MS-Primary-DNS-Server``, ``MS-Secondary-DNS-Server``. For ipoe connection type need send attributes ``DHCP-Domain-Name-Server`` + +.. code-block:: sh + + +----+-------------------+-------------------------+----+-------------------------+ + | id | username | attribute | op | value | + +----+-------------------+-------------------------+----+-------------------------+ + | 1 | user | DHCP-Domain-Name-Server | := | 100.64.254.254 | + | 2 | user | DHCP-Domain-Name-Server | := | 192.168.254.254 | + + +----+-------------------+-------------------------+----+-------------------------+ + | id | username | attribute | op | value | + +----+-------------------+-------------------------+----+-------------------------+ + | 3 | user | MS-Primary-DNS-Server | := | 100.64.254.254 | + | 4 | user | MS-Secondary-DNS-Server | := | 192.168.254.254 | diff --git a/doc/configuration/ip-pool.rst b/doc/configuration/ip-pool.rst new file mode 100644 index 0000000..a2a22e8 --- /dev/null +++ b/doc/configuration/ip-pool.rst @@ -0,0 +1,22 @@ +[ip-pool] +========= + +Configuration of ippool module. + +**gw-ip-address=x.x.x.x** + + Specifies single IP address to be used as local address of ppp interfaces. + +**gw=range** + + Range format should be ``x.x.x.x/mask`` or ``x.x.x.x-y`` + + Specifies range of local address of ppp interfaces. + +**tunnel=range** + + Specifies range of remote address of ppp interfaces, format is same as above. + +**x.x.x.x/mask,pool_name | x.x.x.x-y,pool_name** + + Also specifies range of remote address of ppp interfaces. diff --git a/doc/configuration/ipoe.rst b/doc/configuration/ipoe.rst new file mode 100644 index 0000000..e73589d --- /dev/null +++ b/doc/configuration/ipoe.rst @@ -0,0 +1,428 @@ +.. _ipoe: + +[ipoe] +------ +Method authentication users, control sessions and delivery without any tunnel "called" as IPoE (IP over Ethernet). +Accel-ppp support L2 and L3 topologies and start sessions on DHCP Discover or unclassified packet. + +Develop auxiliary kernel module for sessions start on unclassified packet and shared interfaces. +This module creates virtual interface, an analogue of ifb and used for sessions shaper and One-to-one NAT. + +The difference between L2 and L3. L2 incoming packet will be checked for the mac address set at the session start, and outgoing packets will be sent straight to this mac address without additional ARP requests, which provides protection against IP/mac address spoofing. +In the case of L3, the outgoing packet will be routed according to the established routing rules. + +IPoE configuration overview +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Section IPoE contain many flexible customization. + +**[ipoe]** + +**verbose=0|1** + Default value is ``verbose=0`` + + Writes more detailed logs. + +**ipv6=0|1** + By default is disabled: ``ipv6=0`` + + Activate support ipv6 globally. Also may defined per-interface. Required modules ``ipv6_nd``, ``ipv6_dhcp`` and ``ipv6pool`` if ipv6 addresses will allocate accel-ppp. + +**mode=L2|L3** + By default mode is L2. + + Parameter specifies client connectivity mode. ``mode=L2`` then it means that clients are on same network where interfaces. ``mode=L3`` means that client are behind some router. Also may defined per-interface. + +**start=dhcpv4|up|auto** + By default is not defined. Important to set this. + + Parameter specifies which way session starts: + + * **dhcpv4** - start on DHCP Discover. + + * **up** - unclassified packet. + + * **auto** - means automatically start session with username=interface name. Use it with conjunction vlan_mon. + + Also may defined per-interface. + +**lua-file=/path/to/file.lua** + By default is not defined. + + Needs only if used lua functions for create username from packet header information. Often used with DHCP Option 82. Look :ref:`lua_examples` for more information. + +**username=ifname|lua:function** + By default for DHCP sessions ``username=ifname``, for sessions start by unclassified packet (``start=up``) ``username`` is client ip address. + + If ``username=ifname`` then interface name from which packet was arrived will be used as username. + + + If ``username=lua:username`` then lua function with name ``username`` will be called to construct username from dhcp packet fields. + Also may defined per-interface. + +**password=username|csid|empty|<string>** + By default ``password=username`` + Specifies how to generate password. + + If ``password=username`` then password will be same as username. + + If ``password=csid`` then password will be same as Calling-Station-Id. + + Also you can specify fixed password in ``<string>`` or leave empty. + +**session-timeout=n** + By default is disabled: ``session-timeout=0`` + + Define max sessions time in seconds. After this time session will be terminated. May redefine with radius attribute **Session-Timeout** + +**idle-timeout=n** + By default is disabled ``idle-timeout=0`` + + Specifies timeout in seconds to wait for any packets from client, after this time session will terminated if client don't send any packet. Often used with ``mode=L3``. + +**lease-time=n** + By default ``lease-time=600`` + + Specifies lease time in seconds to be sent to DHCP client. + +**max-lease-time=n** + By default ``max-lease-time=660`` + + Specifies max lease time in seconds, after this time session will be terminated if client won't renew it. + +**renew-time=n** + By default ``renew-time`` calculate as lease-time/2. + + Specifies lease renew time (option 58) in seconds to be sent to DHCP client. Might be overwritten by RADIUS attribute DHCP-Renewal-Time. + +**rebind-time=n** + By default ``rebind-time`` calculate as lease-time/2+lease-time/4+lease-time/8. + + Specifies lease rebind time (option 59) in seconds to be sent to DHCP client. Might be overwritten by RADIUS attribute DHCP-Rebinding-Time. + +**shared=0|1** + By default is active ``shared=1`` + + Specifies where interface is shared by multiple users. If used vlan-per-user need turn this to 0. Also may defined per-interface. + +**unit-cache=n** + By default is disabled: ``unit-cache=0`` + + Specifies number of interfaces to keep in cache. It means that don't destory interface after corresponding session is destoyed, instead place it to cache and use it later for new sessions repeatedly. Actial only if used shared interfaces. + +**ip-pool=pool_name** + By default is not defined. + + Specifies ip pool name which accel-ppp will use for allocate client ip address. + +.. admonition:: Note: + + For use ippool need add this module to ``[modules]`` section, and sets params on section ``[ip-pool]`` + +**ipv6-pool=pool_name** + By default is not defined. + + Specifies ipv6 pool name which accel-ppp will use for allocate client ipv6 prefix. + +**ipv6-pool-delegate=pool_name** + By default is not defined. + + Specifies ipv6 prefix delegation pool name which accel-ppp will use for allocate client ipv6 prefix delegation. + +**vlan-mon=[re:]name[,filter]** + vlan-mon needs for automatically crate vlans interfaces, more often on vlan-per-user schemas. Support regular expression (**re:**). Parameter specifies list of vlans or ranges of vlans to monitor for and may be in following form: vlan-mon=eth1,2,5,10,20-30 + +**vlan-timeout=n** + By default: ``vlan-timeout=60``. + Specifies time on second of vlan inactivity before it will be removed. + +**vlan-name=pattern** + By default ``vlan-name=%I.%N`` + + The vlan-name parameter allows you to specify the pattern for the VLAN interface name. + + The pattern may include the following macros: + + ``%I``: Represents the name of the parent interface (e.g. ethX, enoX, enpXsY, etc.). + + ``%N``: Represents the number of the VLAN (the latest tag ID). In the case of Q-in-Q, this refers to the C-VLAN. + + ``%P``: Represents the number of the VLAN for the parent interface. In the case of Q-in-Q, this refers to the S-VLAN. + + For example, if the parent interface name is eth0 and the VLAN number is 10, the VLAN interface name would be eth0.10 based on the default pattern %I.%N. + + Works with interface params and required regular expression. + +**noauth=0|1** + By default is disabled: ``noauth=0`` and used RADIUS or chap-secrets authentication. + + Allows users to connect without authentication by radius or chap-secrets. For correct work it is necessary to use with ip-pool. + +**ifcfg=0|1** + By default is active: ``ifcfg=1`` + + Parameter specifies whether accel-ppp should add router IP address and route to client to interface or it is explicitly configured. Also may defined per-interface. + +**proto=n** + By default 3 - boot. + + Specifies number of protocol to be used for inserted routes. Works only with ``ifcfg=0``, when the routes create an accel-ppp, not a kernel. Also need exist gw ip address in the system on any of the interfaces, otherwise an error will be output to the accel-ppp.log + +.. admonition:: Log output: + + debug: libnetlink: RTNETLINK answers: Invalid argument + +**check-mac-change=0|1** + By default is active: ``check-mac-change=1`` + + Terminate session when detects change of mac address of client. + +**soft-terminate=0|1** + By default is disabled: ``soft-terminate=0`` + + When terminating sessions through ``cli`` or ``Radius Disconnect-Message``, the session will not be terminated immediately, but will be marked as finished and client will continue working, but next time renew lease the session will be terminated. Session will terminate immediately when expired `max-lease-time`. For manually terminate session immediately you may use cli command ``accel-cmd terminate <session selector> hard`` + +.. code-block:: sh + + accel-cmd terminate if ipoe0 hard + +**l4-redirect-table=n** + By default is disabled: ``l4-redirect-table=0`` + + Specifies number of table. If L4-Redirect radius attribute is received and it's value is not 0 or '0' then accel-ppp will add following rule: ip rule add from <client_ip> table + +**l4-redirect-ipset=<name>** + By default is not defined. + + Specifies name of ipset list. If L4-Redirect radius attribute is received and it's value is not 0 or '0' then accel-ppp will add client's ip to that ipset name. + +**l4-redirect-on-reject=n** + By default is disabled: ``l4-redirect-on-reject=0`` + + Specified time in seconds for creating temporary sessions if radius rejects access and 'ip rule add from ip_addr table l4-redirect-table' rule will be created. + +**l4-redirect-ip-pool=pool_name** + By default is not defined. + + Allocates ip address from specified pool name if radius rejects access. Pool must be sets in section `[ip-pool]` + +**agent-remote-id=<identifier>** + By default is not defined. + + If accel-ppp used as DHCP relay, than to DHCP requests will inserted Option 82 with agent-remote-id and agent-circuit-id with interface name from which received client request. + +**local-net=x.x.x.x/mask** + By default is not defined. + + Specifies networks from which packets will be treated as unclassified. Need only for ``start=up``. You may specify multiple local-net options. For example: + +.. code-block:: sh + + local-net=100.64.0.0/24 + local-net=192.168.0.0/24 + local-net=172.16.0.0/24 + +**vendor=<vendor name>** + By default is not defined. + + Specifies vendor name for RADIUS attributes in current section. For using RADIUS DHCP attributes, set ``vendor=dhcp`` + +**attr-dhcp-client-ip=<attribute>** + By default is not defined. + + Specified radius attribute which contains ip address for assign to client. Example with existing attribute: + +.. code-block:: sh + + attr-dhcp-client-ip=DHCP-Client-IP-Address + +.. admonition:: Note: + + If set custom attribute then need add its for both (radius server and accel-ppp) dictionaries. + +**attr-dhcp-router-ip=<attribute>** + By default is not defined. + + Specified radius attribute which contains router ip address for assign to client. Example with existing attribute: + +.. code-block:: sh + + attr-dhcp-router-ip=DHCP-Gateway-IP-Address + +.. admonition:: Note: + + If set custom attribute then need add its for both (radius server and accel-ppp) dictionaries. + +**attr-dhcp-mask=<attribute>** + By default is not defined. + + Specified radius attribute which contains netmask (CIDR) for assign to client. Example with existing attribute: + +.. code-block:: sh + + attr-dhcp-mask=DHCP-Subnet-Mask + +.. admonition:: Note: + + If set custom attribute then need add its for both (radius server and accel-ppp) dictionaries. + +**attr-dhcp-lease-time=<attribute>** + By default is not defined. + + Specified radius attribute which contains lease time in seconds to be sent to DHCP client. This attribute has priority and may redefine value which sets in ``lease-time`` sets globally. + +**attr-dhcp-renew-time=<attribute>** + By default is not defined. + + Specified radius attribute which contains lease renew time (option 58) in seconds to be sent to DHCP client. This attribute has priority and may redefine value which sets in ``renew-time`` sets globally. + +**gw-ip-address=x.x.x.x/mask** + By default is not defined. + + Specifies address to be used as server ip address if radius can assign only client address. In such case if client address is matched network and mask then specified address and mask will be used. You can specify multiple such options. + For example: + +.. code-block:: sh + + gw-ip-address=100.64.0.1/24 + gw-ip-address=192.168.0.1/24 + gw-ip-address=172.16.0.0/24 + +**attr-dhcp-opt82=<attribute>** + By default is not defined. + + Specifies radius attribute which will contain option 82 from DHCP packet header in binary and send to radius server. + Example: + +.. code-block:: sh + + attr-dhcp-opt82=DHCP-Option82 + +.. admonition:: Note: + + Need add custom attribute in both radius and accel-ppp dictionaries. By default dictionary is located at ``/usr/share/accel-ppp/radius/dictionary`` if accel-ppp build as pkg DEB or RPM. Dictionary path may be redefine in section ``[radius]``. + + Example adding custom attribute: + +.. code-block:: sh + + ATTRIBUTE DHCP-Option82 245 octets + + +**attr-dhcp-opt82-remote-id=<attribute>** + By default is not defined. + + Specifies radius attribute which will contain only **Agent Remote Id** from DHCP packet header and send to radius server. Example with existing attribute in dictionary: + +.. code-block:: sh + + attr-dhcp-opt82-remote-id=DHCP-Agent-Remote-Id + +**attr-dhcp-opt82-circuit-id=<attribute>** + By default is not defined. + + Specifies radius attribute which will contain only **Agent Circuit Id** from DHCP packet header and send to radius server. Example with existing attribute in dictionary: + +.. code-block:: sh + + attr-dhcp-opt82-circuit-id=DHCP-Agent-Circuit-Id + +**offer-timeout=n** + By default ``offer-timeout=10`` + + Specified time in seconds which accel-ppp wait DHCP request from client. If client don't send DHCP request for this time, accel-ppp terminate session. + +**offer-delay=delay[,delay1:count1[,delay2:count2[,...]]]** + By default is not defined. + + One of load balancing mechanism. specifies delays in milliseconds (also in condition of connection count) to send DHCPOFFER . Last delay in list may be -1 which means don't accept new connections. List must to be sorted by count key. Example: + +.. code-block:: sh + + offer-delay=0,100:1000,200:2500,300:5000,400:9999,-1:10000 + +.. admonition:: Explain: + + Clients from 1 to 999 take DHCP offers without delay, client from 1000 to 2499 take DHCP offers with delay 100 ms, clients from 2500 to 4999 take DHCP offers with delay 200 ms, clients from 5000 to 9999 take DHCP offers with delay 300 ms, last client take DHCP offer with delay 400 ms and accel-ppp no more accept connections. + +**weight=n** + By default not defined: + + More modern load balancing mechanism based on weight. + + How it works: + On reception of DHCPDISCOVER accel-ppp sends broadcast DHCP message to port 67 with same xid and add special vendor-specific option where encodes its current session count multiplied by weight. On reception of such message accel-ppp searches session with same xid and compares weight. If received weight is less than session's weight then it terminates this session. + May be used as per-interface. + +.. admonition:: Note: + + Per-interface weight=0 has special meaning as backup (fail-over) interface, f.e. it terminates session on any received weight. + +**calling-sid=mac|ip** + By default ``calling-sid=mac`` + + Specifies value of Calling-Station-Id radius attribute. + +**proxy-arp=0|1|2** + By default is disabled: ``proxy-arp=0`` + + Parameter specifies whether accel-ppp should reply to arp requests. Also may defined per-interface. + + ``0`` - proxy-arp disabled. + + ``1`` - proxy-arp enabled. Accel send arp-reply if src ip and dst ip on different interfaces (as well as linux proxy_arp). + + ``2`` - proxy-arp enabled. Accel send arp-reply back to the same interface (as well as linux proxy_arp_pvlan). + +.. admonition:: Note: + + Works only for subnets defined in `local-net` param + +**ip-unnumbered=0|1** + By default is enabled: ``ip-unnumbered=1`` + + Specifies should accel-ppp create route for session with netmask /32. May be used as per-interface. + +**interface=[re:]name** + By default interface has many params which explain below. + + Specifies interface to listen dhcp or unclassified packets. If name is prefixed with **re:** then name is treated as **regular expression**. + + May be specify multiple interface options, for example: + +.. code-block:: sh + + interface=eth0,mode=L3,start=UP,shared=1 + interface=re:^eth1\.[0-9]+\.[0-9][0-9][0-9]$,mode=L2,shared=0,start=dhcpv4,mtu=1500,ifcfg=1 + +The ``mode=L2|L3`` parameter specifies client connectivity mode. If ``mode=L2`` then it means that clients are on same network where interface is. ``mode=L3`` means that client are behind some router. + +The ``shared=0|1`` parameter specifies where interface is shared by multiple users or it is vlan-per-user. + +The ``start=dhcpv4|up|auto`` parameter specifies which way session starts. + + * ``dhcpv4`` - start by DHCP Discover packet. + + * ``up`` - start by unclassified packet. + + * ``auto`` - means automatically start session with ``username=interface`` name. Use it with conjunction vlan_mon. + +The ``ipv6`` + +The ``mtu=n`` parameter specifies whether accel-ppp should change MTU(maximum transmission unit) on interfaces. By default not set and MTU value inherited from root interface. Often used for vlan-per-user (QinQ). + +The ``range=x.x.x.x/mask`` parameter specifies local range of ip address to give to dhcp clients. First IP in range is router IP. If you need more customization use ``ip-pool`` instead of ``range``. + +The ``ifcfg=0|1`` parameter specifies whether accel-ppp should add router IP address and route to client to interface or it is explicitly configured. By default inheris global ``ifcfg`` value. + +The ``relay=x.x.x.x`` parameter specifies DHCPv4 relay IP address to pass requests to. If specified giaddr is also needed. + +The ``giaddr=x.x.x.x`` parameter specifies relay agent IP address. + +The ``src=x.x.x.x`` parameter specifies ip address to use as source when adding route to client. + +The ``username=ifname|lua:function_name`` allow set custom LUA function to form username from packet header information. Often used this param on varius BRAS connection type. + +``ipv6=0|1`` will activate support ipv6 on interface. If not defined, inherit global params. + +``weight=n`` is load balancing mechanism based on weight. ``weight=0`` has special meaning as backup (fail-over) interface, f.e. it terminates session on any received weight. diff --git a/doc/configuration/ipv6-dhcp.rst b/doc/configuration/ipv6-dhcp.rst new file mode 100644 index 0000000..1be0f31 --- /dev/null +++ b/doc/configuration/ipv6-dhcp.rst @@ -0,0 +1,29 @@ +[ipv6-dhcp] +=========== + +Overview ipv6 DHCP section. + +**verbose=0|1** + By default is disabled. + + Specified will ipv6-dhcp module produce verbose logging. + +**pref-lifetime=n** + By default ``pref-lifetime=604800`` + + Specifies preferred liftime in seconds to be sent to DHCPv6 client. + +**valid-lifetime=n** + By default ``valid-liftime=2592000`` + + Specifies valid lifetime in seconds to be sent to DHCPv6 client. + +**route-via-gw=0|1** + By default ``route-via-gw=1`` + + Specifies if delegated prefix routes should use gateway. + +**server-id=a:b:c:d** + By default ``server-id=0:0:0:1`` + + Specifies the DHCPv6 server-id. Each value a, b, c, d is hex value in range 0000 to ffff diff --git a/doc/configuration/ipv6-dns.rst b/doc/configuration/ipv6-dns.rst new file mode 100644 index 0000000..43424a7 --- /dev/null +++ b/doc/configuration/ipv6-dns.rst @@ -0,0 +1,24 @@ +[ipv6-dns] +========== + +Overview ipv6 DNS section. + +**dns=IPv6_address** + By default is not defined. + + Specifies IPv6 DNS to be sent to peer. You may specify up to 3 dns options. + +**dnssl=name** + By default is not defined. + + Specify DNS Search List. You may specify multiple dns and dnssl options. + +.. admonition:: Note: + + Also DNS addresses may be described like + + .. code-block:: sh + + [ipv6-dns] + 2001:4860:4860::8888 + 2001:4860:4860::8844 diff --git a/doc/configuration/ipv6-nd.rst b/doc/configuration/ipv6-nd.rst new file mode 100644 index 0000000..b4d4742 --- /dev/null +++ b/doc/configuration/ipv6-nd.rst @@ -0,0 +1,75 @@ +[ipv6-nd] +========= + +Overview ipv6 neighbor discovery section. + +**verbose=0|1** + By default is disabled. + + Specified will ipv6-nd module produce verbose logging. + +**MaxRtrAdvInterval=n** + By default 600 second. + + The maximum time allowed between sending unsolicited multicast router advertisements from the interface, in seconds. + +**MinRtrAdvInterval=n** + By default calculates 0.33 * **MaxRtrAdvInterval** + + The minimum time allowed between sending unsolicited multicast router advertisements from the interface, in seconds. + +**AdvManagedFlag=1|0** + By default disabled. + + When set, hosts use the administered (stateful) protocol for address autoconfiguration in addition to any addresses autoconfigured using stateless address autoconfiguration. The use of this flag is described in RFC 4862. + +**AdvOtherConfigFlag=** + By default disabled. + + When set, hosts use the administered (stateful) protocol for autoconfiguration of other (non-address) information. The use of this flag is described in RFC 4862. + +**AdvLinkMTU=** + By default not defined. + + The MTU option is used in router advertisement messages to insure that all nodes on a link use the same MTU value in those cases where the link MTU is not well known. + + If specified, i.e. not 0, must not be smaller than 1280 and not greater than the maximum MTU allowed for this link (e.g. ethernet has a maximum MTU of 1500. See RFC 4864). + +**AdvReachableTime=** + By default not defined. + + The time, in milliseconds, that a node assumes a neighbor is reachable after having received a reachability confirmation. Used by the Neighbor Unreachability Detection algorithm + +**AdvRetransTimer=** + By default not defined. + + The time, in milliseconds, between retransmitted Neighbor Solicitation messages. Used by address resolution and the Neighbor Unreachability Detection algorithm + +**AdvCurHopLimit=** + By default 64. + + The default value that should be placed in the Hop Count field of the IP header for outgoing (unicast) IP packets. The value should be set to the current diameter of the Internet. + +**AdvDefaultLifetime=n** + By default calculating 3 * **MaxRtrAdvInterval** + + The lifetime associated with the default router in units of seconds. + +**AdvValidLifetime=** + By default not defined. + + The length of time in seconds (relative to the time the packet is sent) that the prefix is valid for the purpose of on-link determination. + +**AdvPreferredLifetime=** + By default not defined. + + The length of time in seconds (relative to the time the packet is sent) that addresses generated from the prefix via stateless address autoconfiguration remain preferred. + +**AdvOnLinkFlag=** + +**AdvAutonomousFlag=** + +**MaxInitialRtrAdvCount=** + +**MaxInitialRtrAdvInterval=** + diff --git a/doc/configuration/ipv6-pool.rst b/doc/configuration/ipv6-pool.rst new file mode 100644 index 0000000..4d5f10d --- /dev/null +++ b/doc/configuration/ipv6-pool.rst @@ -0,0 +1,41 @@ +[ipv6-pool] +=========== + +Overview ipv6 pool section. + +**vendor=vendor** + By default not defined. + + If attribute is vendor-specific then specify vendor name in this option. + +**attr-prefix=attribute** + By default ``attr-prefix=Delegated-IPv6-Prefix-Pool`` + + Specifies which Radius attribute contains delegated prefix pool name. + +**attr-address=attribute** + By default ``attr-address=Stateful-IPv6-Address-Pool`` + + Specifies which Radius attribute contains stateful address pool name. + +**ipv6prefix/mask,prefix_len[,name=pool_name][,next=next_pool_name]** + By default not defined. + + fc00:0:1::/48,64 - specifies pool of address by dividing prefix fc00:0:1::/48 to networks with 64 prefix len, e.g: + +.. code-block:: sh + + fc00:0:1:0::/64 + fc00:0:1:1::/64 + ... + fc00:0:1:ffff::/64 + +**delegate=ipv6prefix/mask,prefix_len[,name=pool_name][,next=next_pool_name]** + By default not defined. + + Specifies range of prefixes to delegate to clients through DHCPv6 prefix delegation (rfc3633). Format is same as described above. + +**gw-ip6-address=ipv6address** + By default not defined. + + Specifies gateway address (used only for /128 prefixes) diff --git a/doc/configuration/l2tp.rst b/doc/configuration/l2tp.rst new file mode 100644 index 0000000..8f5fe1d --- /dev/null +++ b/doc/configuration/l2tp.rst @@ -0,0 +1,129 @@ +[l2tp] +====== + +Overview configuration of L2TP module. + +**verbose=0|1** + By default is disabled. + + Specified will pptp module produce verbose logging. + +**bind=x.x.x.x** + By default bound on all IP address. + + If this option is given then *l2tp* server will bind to specified IP address. + +**port=n** + By default ``port=1701`` + + If this option is given then *l2tp* server will bind to specified port. + +**host-name=string** + By default ``host-name=accel-ppp`` + + This name will be sent to clients in Host-Name attribute. + +**hello-interval=n** + By default ``hello-interval=60`` + + Specifies interval in seconds to send Hello control message. Its used for keep alive connection. If peer will not respond to *Hello* connection will be terminated. + +**recv-window=n** + By default ``recv-window=16`` Available value range 1-32768. + + Set the size of the local receive window. Only received messages whose sequence number is in the range [last-Nr + 1, last-Nr + recv-window] are accepted (where last-Nr is the sequence number of the last acknowledged message). + +**timeout=n** + By default ``timeout=60`` + + Specifies timeout in seconds to wait peer completes tunnel and session negotiation. + +**rtimeout=n** + By default ``timeout=1`` + + Specifies timeout (in seconds) to wait message acknowledge, if elapsed message retransmission will be performed. Timeout is multiplied by two after each retransmission. So if rtimeout is set to 1, first retransmission will occur after one second, second retransmission two seconds later, third one four seconds later, and so on, until a reply is received or the retransmit value is reached. + +**rtimeout-cap=n** + By default ``rtimeout-cap=16`` + + Set the maximum interval between retransmissions. The exponential backoff interval used by rtimeout will never grow above rtimeout-cap. rtimeout-cap must be higher than rtimeout and, according to RFC 2661, must be no less than 8 (though accel-ppp doesn't enforce this rule). + +**retransmit=n** + By default ``retransmit=5`` + + Specifies maximum number of message retransmission, if exceeds connection will be terminated. + +**mppe=deny|allow|prefer|require** + By default is not defined. + + Default behavior - don’t ask client for mppe, but allow it if client wants. + +**secret=string** + By default is not defined. + + Specifies secret to connect to server. + +**hide-avps=0|1** + By default ``hide-avps=0`` + + If this option is given and ``hide-avps=1``, then attributes sent in L2TP packets will be hidden (for AVPs that support it). + +**dataseq=deny|allow|prefer|require** + By default ``dataseq=allow`` + + Specify data sequencing negotiation algorithm: + + * deny - don't send data packets with sequence numbers + + * allow - send data packets with sequence numbers if peer have requested so only + + * prefer - send data packets with sequence numbers and enable same for peer + + * require - send data packets with sequence numbers and enforce same for peer + +**reorder-timeout=n** + By default ``reorder-timeout=0`` + + Specifies timeout in milliseconds to wait for out-of-order packets. If *0*, don't try to reorder. + +**use-ephemeral-ports=0|1** + By default ``use-ephemeral-ports=0`` + + Specifies if an arbitrary source port is used when replying to a tunnel establishment request. When this option is deactivated, the destination port of the incoming request (SCCRQ) is used as source port for the reply (SCCRP). + +**ppp-max-mtu=n** + By default ``ppp-max-mtu=1420`` + + Set the maximum MTU value that can be negotiated for PPP over L2TP sessions. + +**ifname=ifname** + By default is not defined. + + If this option is given ppp interface will be renamed using ifname as a template, i.e ``ifname=l2tp%d`` => l2tp0. + +.. admonition:: Note: + + Also interface may renamed if RADIUS server send attribute ``NAS-Port-Id`` with custom name. Length this value not be more 16 characters. + +**avp_permissive=0|1** + +**dir300_quirk=0|1** + +**ip-pool=pool_name** + By default is not defined. + + Specifies ip pool name which accel-ppp will use for allocate client ip address. + +.. admonition:: Note: + + For use ippool need add this module to ``[modules]`` section, and sets params on section ``[ip-pool]`` + +**ipv6-pool=pool_name** + By default is not defined. + + Specifies ipv6 pool name which accel-ppp will use for allocate client ipv6 prefix. + +**ipv6-pool-delegate=pool_name** + By default is not defined. + + Specifies ipv6 prefix delegation pool name which accel-ppp will use for allocate client ipv6 prefix delegation. diff --git a/doc/configuration/log.rst b/doc/configuration/log.rst new file mode 100644 index 0000000..e6aebb0 --- /dev/null +++ b/doc/configuration/log.rst @@ -0,0 +1,96 @@ +[log] +===== + +Configuration of log and log_file modules. + +Config overview +^^^^^^^^^^^^^^^ + +**log-file=/path/to/file** + By default is not defined. Required if used ``[modules]log_file`` + + Path to file to write general log. + +**log-emerg=/path/to/file** + By default is not defined. Required if used ``[modules]log_file`` + + Path to file to write emergency messages. + +**log-fail-file=/path/to/file** + By default is not defined. + + Path to file to write authentication failed session log. + +**log-debug=/path/to/file** + By default is not defined. + + Path to file to write all debug messages, also include mikrotime and threads numbers. + +**log-tcp=x.x.x.x:port** + By default is not defined. Required if used ``[modules]log_tcp`` + + Send logs to specified host. (Need add examples) + +**syslog=ident[,facility]** + By default is ``syslog=accel-pppd,daemon`` + + Send logs to system logger. Facility may be: daemon, local0-local7 or numeric value. + +**copy=0|1** + By default is not defined. + + If this options is given, logging engine will duplicate session log in general log. (Useful when per-session/per-user logs are not used). + +**per-session-dir=dir** + By default is not defined. + + Directory for session logs. If specified each session will be logged separately to file which name is unique session identifier. + +**per-user-dir=dir** + By default is not defined. + + Directory for user logs. If specified all sessions of same user will be logged to file which name is user name. + +**per-session=0|1** + By default is not defined. + + If specified then each session of same user will be logger separately to directory specified by "per-user-dir" and subdirectory which name is user name and to file which name os unique session identifier. + +**level=n** + By default is ``level=0`` + + Specifies log level which values are: + + ``0`` turn off all logging + + ``1`` log only error messages + + ``2`` log error and warning messages + + ``3`` log error, warning and minimum information messages (use this level in conjuction with verbose option of other modules if you need verbose logging) + + ``4`` log error, warning and full information messages (use this level in conjuction with verbose option of other modules if you need verbose logging) + + ``5`` log all messages including debug messages + + +logs rotation +^^^^^^^^^^^^^ + +For rotation logs can be used system logrotate utility. Needs create file ``/etc/logrotate.d/accel-ppp`` and put next: + +.. 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 + } + +.. admonition:: Note: + + For correct work *logrotate* utility need run ``accel-pppd`` daemon with ``-p /var/run/accel-pppd.pid`` argument. + +.. Caution:: If accel-ppp run with gdb (GNU debugger) for find bugs, you need disable logs rotation, because it will makes to daemon crash. diff --git a/doc/configuration/modules.rst b/doc/configuration/modules.rst new file mode 100644 index 0000000..b2bac47 --- /dev/null +++ b/doc/configuration/modules.rst @@ -0,0 +1,36 @@ +[modules] +========= + +Section [modules] contains list of modules to load. + +.. admonition:: Note: + + There exist order which define modules priority e.g. If **ippool** module will defined before **radius**, then ip-addresses always will assigned from **[ip-pool]**, and Framed-IP-Adresse recived from radius server will be ignored. + +* **log_file** - logging target which logs messages to files. It support per-session/per-user features. +* **log_syslog** - logging target which logs messages to syslog. +* **log_tcp** - logging target which logs messages over TCP/IP. +* **log_pgsql** - logging target which logs messages to PostgreSQL. +* **pptp** - PPTP controlling connection handling module. +* **pppoe** - PPPoE discovery stage handling module. +* **ipoe** - DHCP and unclassified packet connection handling module. +* **l2tp** - L2TP controlling connection handling module. +* **sstp** - SSTP controlling connection handling module. +* **auth_pap** - PAP authentication module. +* **auth_chap_md5** - CHAP (md5) authentication module. +* **auth_mschap_v1** -Microsoft CHAP (version 1) authentication module. +* **auth_mschap_v2** - Microsoft CHAP (version 2) authentication module. +* **radius** - RADIUS interaction module. +* **chap-secrets** - module authentication from file. +* **shaper** - this module controls shaper. +* **ippool** - IPv4 address assigning module. +* **ipv6_nd** - IPv6 Neighbor Discovery module. +* **ipv6_dhcp** - IPv6 DHCP module. +* **ipv6pool** - IPv6 address assigning module. +* **sigchld** - Helper module to manage child processes, required by pppd_compat. +* **pppd_compat** - this module starts pppd compatible ip-up/ip-down scripts and ip-change to handle RADIUS CoA request. +* **connlimit** - this module limits connection rate from single source. + +.. admonition:: Note: + + Can’t change with reload, for apply changes need daemon restart with drop active sessions. diff --git a/doc/configuration/ppp.rst b/doc/configuration/ppp.rst new file mode 100644 index 0000000..04288de --- /dev/null +++ b/doc/configuration/ppp.rst @@ -0,0 +1,147 @@ +[ppp] +====== + +The Point-to-Point Protocol (PPP) provides a standard method for transporting multi-protocol datagrams over point-to-point links. PPP also defines an extensible Link Control Protocol. +Section ``[ppp]`` consist common ppp prams for PPPoE/PPtP/L2TP/SSTP. + +**verbose=0|1** + Default value is ``verbose=0`` + + Writes more detailed logs. + +**min-mtu=n** + Default value is ``min-mtu=100`` + + Minimum acceptable MTU. + If client will try to negotiate less then specified MTU then it will be NAKed or disconnected if rejects greater MTU. + +**mtu=n** + By default is not defined. + + MTU which will be negotiated if client's MRU will be not acceptable. + +**mru=n** + By default is not defined. + + Preferred MRU. + +**accomp=allow|deny** + By default is: ``accomp=deny`` + + Address/Control compression negotiation. + + * ``allow`` - prefere in send and don't deny in receive directions. + + * ``deny`` - disable in both directions. + +**pcomp=allow|deny|n** + By default is: ``pcomp=deny`` + + Protocol field compression negotiation. + + * allow - prefere in send and don't deny in receive directions. + + * deny - disable in both directions. + +**ccp=n** + By default is enabled: ``ccp=1`` + + For disable CCP (*Compression Control Protocol*) negotiation set ``ccp=0`` + +**ccp-max-configure=n** + By default is: ``ccp-max-configure=3`` + + **TODO** + +**sid-case=upper|lower** + By default is: ``sid-case=lower`` + + Specifies in which case generate session identifier. + +**mppe=require|prefer|deny** + Default behavior - don't ask client for mppe, but allow it if client wants. + + Specifies mppe negotioation preference. + + ``require`` - ask client for mppe, if it rejects drop connection. + + ``prefer`` - ask client for mppe, if it rejects don't fail. + + ``deny`` - deny mppe. + + .. admonition:: Note: + + RADIUS may override this option by MS-MPPE-Encryption-Policy attribute. + MPPE requires defined ``ccp=1`` + +**ipv4=deny|allow|prefer|require** + By default is ``ipv4=allow`` + + Specifies IPv4 (IPCP) negotioation algorithm: + + ``deny`` - don't negotiate IPv4. + + ``allow`` - negotiate IPv4 only if client requests. + + ``prefer`` - ask client for IPv4 negotiation, don't fail if he rejects. + + ``require`` - require IPv4 negotiation. + +**ipv6=deny|allow|prefer|require** + By default is ``ipv6=deny`` + + Specify IPv6 (IPCP) negotioation algorithm: + + ``deny`` - don't negotiate IPv6. + + ``allow`` - negotiate IPv6 only if client requests. + + ``prefer`` - ask client for IPv6 negotiation, don't fail if he rejects. + + ``require`` - require IPv6 negotiation. + +**ipv6-intf-id=x:x:x:x|random** + By default is fixed. + + Specify fixed or random interface identifier for IPv6. + +**ipv6-peer-intf-id=x:x:x:x|random|ipv4|calling-sid** + By default is fixed. + + Specifies peer interface identifier for IPv6. + + ``random`` - generate random interface identifier for peer. + + ``ipv4`` - calculate interface identifier from IPv4 address, for example ``192:168:0:1`` + + ``calling-sid`` - calculate interface identifier from Calling-Station-Id. + +**ipv6-accept-peer-intf-id=0|1** + By default is not defined. + + Specify whether to accept peer's interface identifier. + +**lcp-echo-interval=n** + By default is disabled: ``lcp-echo-interval=0`` + + If this option is given and greater then 0 then lcp module will send echo-request every n seconds. + +**lcp-echo-failure=n** + By default is disabled: ``lcp-echo-failure=0`` + + Specifies maximum number of echo-requests may be sent without valid echo-reply, if exceeds connection will be terminated. + +**lcp-echo-timeout=sec** + By default is disabled: ``lcp-echo-timeout=0`` + + Specifies timeout in seconds to wait for any peer activity. If this option specified it turns on adaptive *lcp echo functionality* and ``lcp-echo-failure`` is not used. Also required set ``lcp-echo-interval``. + +**unit-cache=n** + By default is disabled: ``unit-cache=0`` + + Specifies number of interfaces to keep in cache. It means that don't destroy interface after corresponding session is destroyed, instead place it to cache and use it later for new sessions repeatedly. This should reduce kernel-level interface creation/deletion rate lack. + +**unit-preallocate=0|1** + By default is ``unit-preallocate=0``, ppp unit (interface) will allocate after authorization. + + Specified will accel-ppp allocate ppp unit (interface) before authorization, so Nas-Port and Nas-Port-Id would be defined in Access-Request phase. diff --git a/doc/configuration/pppd_compat.rst b/doc/configuration/pppd_compat.rst new file mode 100644 index 0000000..d6b9658 --- /dev/null +++ b/doc/configuration/pppd_compat.rst @@ -0,0 +1,42 @@ +[pppd-compat] +============= + +Configuration of pppd_compat module. Often used for creation custom shaper or other custom tricks. +This module starts pppd compatible ip-up/ip-down scripts and ip-change to handle RADIUS CoA request. + +Config overview +^^^^^^^^^^^^^^^ +**verbose=0|1** + Default value is ``verbose=0`` + + If specified and greated then 0, pppd_module will produce verbose logging. + +**radattr-prefix=/path** + By default is not defined. + + Specifies prefix of radattr files (for example ``radattr=/var/run/radattr``, resulting files will be ``/var/run/radattr.pppX``) + +**ip-pre-up=/path/to/file** + By default is not defined. + + Path to ip-pre-up script which is executed before ppp interface comes up, useful to setup firewall rules before any traffic can pass through the interface. + +**ip-up=/path/to/file** + By default is not defined. + + Path to ip-up script which is executed when ppp interfaces is completely configured and started. + +**ip-down=/path/to/file** + By default is not defined. + + Path to ip-down script which is executed when session is about to terminate. + +**ip-change=/path/to/file** + By default is not defined. + + Path to ip-change script which is executed for RADIUS CoA handling. + +**fork-limit=n** + By default is calculated ``threads*2`` + + Specifies number of simultaneously running background processes. For disable this feature need set ``fork-limit=0`` diff --git a/doc/configuration/pppoe.rst b/doc/configuration/pppoe.rst new file mode 100644 index 0000000..f2a0ad3 --- /dev/null +++ b/doc/configuration/pppoe.rst @@ -0,0 +1,124 @@ +[pppoe] +======= + +Configuration of PPPoE module. + +**verbose=0|1** + By default is disabled. + + Specified will pppoe module produce verbose logging. + +**padi-limit=n** + By default is unlimited ``padi-limit=0`` + + Specifies overall limit of PADI packets to reply in 1 second period. Rate of per-mac PADI packets is limited to no more than 1 packet per second. May also used as per-interface param. + +**interface=[re:]ifname[,padi-limit=n]** + By default is defined. Important to set this option. + + Specifies interface name to listen/send discovery packets. May be specify multiple interface options. If *ifname* is prefixed with ``re:`` then *ifname* is considered as regular expression. Optional padi-limit parameter specifies limit of PADI packets to reply on this interface in 1 second period. + +**ac-name=ac-name** + By default is ``ac-name=accel-ppp`` + + ``Need fix: ìmportant check it`` Specifies AC-Name tag value. If absent tag will not be sent. + +**service-name=service-name1,service-nameN** + By default is not defined. + + Specifies Service-Name to respond. If absent any Service-Name is acceptable and client's Service-Name will be sent back. + Also possible set multiple service-names: ``service-name=sn1,sn2,sn3`` + +**accept-any-service=n** + By default is disabled. + + If service-name specified still will answer with service names, but accepts any service name in PADR request. Useful for scenarios, where selection of PPPoE done by client, based on service names in PADO. + +**pado-delay=delay[,delay1:count1[,delay2:count2[,...]]]** + By default is disabled. + + Specifies delays (also in condition of connection count) to send PADO (ms). Last delay in list may be -1 which means don't accept new connections. List have to be sorted by count key. + +**called-sid=ifname|mac|ifname:mac** + By default is ``called-sid=mac`` + + Specifies how to represent Called-Station-ID. + +* ``ifname`` - Called-Station-ID will contain name of interface accepted request. +* ``mac`` - Called-Station-ID will contain mac address of interface accepted request. +* ``ifname:mac`` - Called-Station-Id will contain both name and mac of interface. + +**tr101=0|1** + By default is enabled ``tr101=1`` + + Specifies whether to handle TR101 tags. + +**mppe=deny|allow|prefer|require** + By default is not defined. + + Default behavior - don’t ask client for mppe, but allow it if client wants. + +**ifname=ifname** + By default is not defined. + + If this option is given ppp interface will be renamed using ifname as a template, i.e ``ifname=pppoe%d`` => *pppoe0*. + +.. admonition:: Note: + + Also interface may renamed if RADIUS server send attribute ``NAS-Port-Id`` with custom name. Length this value not be more 16 characters. + +**ifname-in-sid=called-sid|calling-sid|both** + By default is not defined. + + Specifies that interface name should be present in Called-Station-ID or in Calling-Station-ID or in both attributes. + +**sid-uppercase=0|1** + By default is lowercase ``sid-uppercase=0``` + + Specifies in which case sen attribute ``Called-Station-ID`` and ``Calling-Station-ID``. + + Example: lowercase ``Calling-Station-Id "xx:xx:xx:xx:xx:xx"``, uppercase ``Calling-Station-Id "XX:XX:XX:XX:XX:XX"`` + +**cookie-timeout=n** + By default ``cookie-timeout=5`` + + + +**ip-pool=pool_name** + By default is not defined. + + Specifies ip pool name which accel-ppp will use for allocate client ip address. + +.. admonition:: Note: + + For use ippool need add this module to ``[modules]`` section, and sets params on section ``[ip-pool]`` + +**ipv6-pool=pool_name** + By default is not defined. + + Specifies ipv6 pool name which accel-ppp will use for allocate client ipv6 prefix. + +**ipv6-pool-delegate=pool_name** + By default is not defined. + + Specifies ipv6 prefix delegation pool name which accel-ppp will use for allocate client ipv6 prefix delegation. + +**vlan-mon=[re:]name[,filter]** + vlan-mon needs for automatically crate vlans interfaces. Support regular expression (re:). Parameter specifies list of vlans or ranges of vlans to monitor for and may be in following form: ``vlan-mon=eth1,2,5,10,20-30`` + +**vlan-timeout=n** + By default: ``vlan-timeout=60``. + + Specifies time on second of vlan inactivity before it will be removed. + +**vlan-name=pattern** + By default vlan-name=%I.%N + + Specifies pattern of vlan interface name. Pattern may contain following macros: + +* ``%I`` - name of pattern interface. + +* ``%N`` - number of vlan. + +* ``%P`` - number of vlan of parent interface. + diff --git a/doc/configuration/pptp.rst b/doc/configuration/pptp.rst new file mode 100644 index 0000000..65fed08 --- /dev/null +++ b/doc/configuration/pptp.rst @@ -0,0 +1,72 @@ +[pptp] +======= + +Configuration overview of PPTP module. + +**verbose=0|1** + By default is disabled. + + Specified will pptp module produce verbose logging. + +**bind=x.x.x.x** + By default bound on all ip address. + + If this option is given then pptp server will bind to specified IP address. + +**port=n** + By default ``port=1723`` + + If this option is given then pptp server will bind to specified port. + +**echo-interval=n** + By default is disabled ``echo-interval=0`` + + If this option is given and greater then zero then pptp module will send echo-request every n seconds. + +**echo-failure=n** + By default ``echo-failure=3`` + + Specifies maximum number of echo-requests may be sent without valid echo-reply, if exceeds connection will be terminated. + +**timeout=n** + By default ``timeout=5`` + + Timeout waiting reply from client in seconds. + +**mppe=deny|allow|prefer|require** + By default is not defined. + + Default behavior - don’t ask client for mppe, but allow it if client wants. + +**ifname=ifname** + By default is not defined. + + If this option is given ppp interface will be renamed using ifname as a template, ``ifname=pptp%d`` => pptp0. + +.. admonition:: Note: + + Also interface may renamed if RADIUS server send attribute ``NAS-Port-Id`` with custom name. Length this value not be more 16 characters. + +**ppp-max-mtu=n** + By default ``ppp-max-mtu=1436`` + + Set the maximum MTU value that can be negociated for PPP over PPTP sessions. + +**ip-pool=pool_name** + By default is not defined. + + Specifies ip pool name which accel-ppp will use for allocate client ip address. + +.. admonition:: Note: + + For use ippool need add this module to ``[modules]`` section, and sets params on section ``[ip-pool]`` + +**ipv6-pool=pool_name** + By default is not defined. + + Specifies ipv6 pool name which accel-ppp will use for allocate client ipv6 prefix. + +**ipv6-pool-delegate=pool_name** + By default is not defined. + + Specifies ipv6 prefix delegation pool name which accel-ppp will use for allocate client ipv6 prefix delegation. diff --git a/doc/configuration/radius.rst b/doc/configuration/radius.rst new file mode 100644 index 0000000..8c0277f --- /dev/null +++ b/doc/configuration/radius.rst @@ -0,0 +1,95 @@ +[radius] +======== + +**verbose=0|1** + By default is not defined. + + If this option enabled, the radius module should add detailed info to log + +**interim-verbose=0|1** + By default is not defined. + + Specified, should radius module produce verbose logging of interim radius packets. + +**dictionary=/path/to/dictionary** + By default is `< -DCMAKE_INSTALL_PREFIX >/share/accel-ppp/radius/dictionary` + + Specifies path to RADIUS dictionaries. It is possible to define multiple dictionaries + +**server=address,secret[,auth-port=1812][,acct-port=1813][,req-limit=0][,fail-timeout=0,max-fail=0,][,weight=1][,backup]** + By default is not defined. + + Specifies IP address, secret, ports of RADIUS server. + +**nas-ip-address=x.x.x.x** + By default is not defined. + + Specifies value to send to RADIUS server in *NAS-IP-Address* attribute and to be matched in DM/CoA requests. Also DM/CoA server will bind to that address. + +**nas-identifier=identifier** + By default is not defined. + + Specifies value to send to RADIUS server in NAS-Identifier attribute and to be matched in DM/CoA requests. + +**gw-ip-address=x.x.x.x** + By default is not defined. + + Specifies address to use as local address of ppp interfaces if *Framed-IP-Address* received from RADIUS server. + +**acct-interim-interval=n** + By default is not defined. + + Specifies interval in seconds to send accounting information (may be overridden by radius *Acct-Interim-Interval* attribute) + +**acct-interim-jitter=n** + By default is not defined. + + Specifies absolute maximum jitter value in seconds to be applied to accounting information interval. Calculate interim-interval+-acct-interim-jitter. + +**max-try=n** + By default is ``max-try=3`` + + Specifies number of tries to send Access-Request/Accounting-Request queries. + +**timeout=n** + By default is ``timeout=3`` + + Timeout in seconds to wait response from RADIUS server. + +**acct-timeout=n** + By default is ``acct-timeout=3`` + + Specifies timeout in seconds of accounting interim update, if request not received after this time , session will terminated. If ``acct-timeout=0`` then session keeps active. + +**sid-in-auth=0|1** + By default is not defined. + + Specifies should *accel-ppp* generate and send ``Acct-Session-Id`` on Access-Request packet. By default ``Acct-Session-Id`` sent on Accounting-Request packet. + +**acct-delay-time=0|1** + By default is `acct-delay-time=0` + + Specifies whether radius client should include Acct-Delay-Time attribute to accounting requests + +**attr-tunnel-type=name** + By default is not defined. + + Specifies custom attribute name to be used to send tunnel type (as string). + +**default-realm=realm** + By default is disabled. + + Append specified realm to username. For example ``default-realm=example.com`` accel-ppp send to RADIUS server ``username@example.com`` + +DM/CoA +^^^^^^ + +**dae-server=x.x.x.x:port,secret** + By default is not defined. + + Specifies IP address, port to bind and secret for Dynamic Authorization Extension server (DM/CoA).This *ip address* must exist on any server interface. + +**require-nas-identification=0|1** + By default is not defined. + + Allow processing (DM/CoA) packets that contain valid "NAS-Identifier" and "NAS-IP-Address" attributes. diff --git a/doc/configuration/shaper.rst b/doc/configuration/shaper.rst new file mode 100644 index 0000000..8bd1ded --- /dev/null +++ b/doc/configuration/shaper.rst @@ -0,0 +1,167 @@ +.. _shaper: + +[shaper] +======== +Accel-ppp support many ways customisation rate-limit. Also limiting clients bandwidths sometimes called as QoS (Quality of Service), but QoS has more possibilities. For enable rate-liniter, we can sets ``shaper`` in section ``[modules]``. + +Config overview +--------------- + +**attr=name** + By default: ``attr=Filter-Id``. + + Specifies which radius attribute contains rate information. RADIUS server can transmit ``Filter-Id=1000``, means 1000Kbit both up-stream and down-stream rate or ``Filter-Id=2000/3000``, means 2000Kbit down-stream rate and 3000Kbit up-stream rate. + +**attr-up=name** + By default is not defined. + + Specifies which radius attribute contains rate information for **upstream**. Often used if needs separate *upstream* and *downstream* attributes. + +**attr-down=name** + By default is not defined. + + Specifies which radius attribute contains rate information for **downstream**. Often used if needs separate *upstream* and *downstream* attributes. + +**vendor=name** + By default is not defined. + + Specifies vendor name for support attributes of other vendors like *Cisco-AVPair* or *Mikrotik*. + +Example for Cisco: + +.. code-block:: sh + + vendor=Cisco + attr=Cisco-AVPair + +Example for Mikrotik: + +.. code-block:: sh + + vendor=Mikrotik + attr=Mikrotik-Rate-Limit + +**burst-factor=n** + By default is not defined. + + Burst will be calculated as rate multiply burst-factor. Common ``burst-factor`` for upstream calculated as ``burst-factor*10``. + +**up-burst-factor=n** + By default is ``up-burst-factor=1`` + + Specifies burst factor for **upstream**. + +**down-burst-factor=n** + By default is ``down-burst-factor=0.1`` + + Specifies burst factor for **downstream**. + +**cburst=n** + By default is ``cburst=1534`` + + Specifies amount of bytes that can be burst at 'infinite' speed. Recommendation: cburst should be equal to at most one average packet + +**latency=n** + By default is ``latency=0.05`` + + Specifies latency (in milliseconds) parameter of tbf qdisc which set maximum amount of time a packet can sit in the TBF. + +**mpu=n** + By default is ``mpu=0`` + + Specifies mpu parameter in bytes of tbf qdisc and policer. Determines the minimal token usage for a packet. + +**r2q=n** + By default is ``r2q=10`` + + Specifies r2q parameter of root htb qdisc. + +**quantum=n** + By default is ``quantum=1500`` + + Specifies quantum parameter of htb classes. Amount of bytes a flow is allowed to dequeue before the scheduler moves to the next class. + +**moderate-quantum=1|0** + By default is disabled ``moderate-quantum=0`` + + If fixed quantum is not specified and this option is specified then shaper module will check for quantum value is valid (in range 1000-200000). + +**fwmark=n** + By default is disabled: ``fwmark=0`` + + Specifies the fwmark for traffic that won't be passed through shaper. + +**up-limiter=police|htb** + By default is: ``up-limiter=police`` + + Specifes upstream rate limiting method. + +**down-limiter=tbf|htb** + By default is: ``down-limiter=tbf`` + + Specifies downstream rate limiting method. + +**ifb=ifb_ifname** + By default ``ifb=ifb0`` + + Specifies name of ifb interface, used only for ``up-limiter=htb`` + +**leaf-qdisc=qdisc parameters** + By default is not defined. + + In case if htb is used as up-limiter or down-limiter specified leaf qdisc can be attached automaticaly. At present *sfq* and *fq_codel qdiscs* are implemented. *CoDel* (the name comes from "controlled delay") is Active Queue Manager. Parameters are same as for tc: + + ``sfq [limit NUMBER] [perturb SECS] [quantum BYTES]`` + + ``fq_codel [limit PACKETS] [flows NUMBER] [target TIME] [interval TIME] [quantum BYTES] [[no]ecn]`` + +**rate-multiplier=n** + By default is ``rate-multiplier=1`` + + Due to accel-ppp operates with rates in kilobit basis if you send rates in different basis then you can use this option to bring your values to kilobits. For ``vendor=Mikrotik`` often sets ``rate-multiplier=0.001`` + +**rate-limit=downstream/upstream** + By default is not defined. + + Specifies default speed if there are no radius attributes. + +**time-range=range_id,time_start-time_end** + By default is not defined. + + Specifies time ranges for automatic rate reconfiguration. You can specify multiple such options. + + Configuration example: + +.. code-block:: none + + [shaper] + time-range=1,1:00-3:00 + time-range=2,3:00-5:00 + time-range=3,5:00-7:00 + +The first number is time range identifier. To define a specific rates uses following format of radius attributes: range-id,rate, range-id,down-rate/up-rate or cisco-like. + +As an example: + +.. code-block:: none + + Filter-Id=1000 + Filter-Id=1,2000 + Filter-Id=2,3000 + Filter-Id=3,4000 + +That means: set 1000Kbit by default, set 2000Kbit in time range 1, set 3000Kbit in time range 2 and set 4000Kbit in time range 3. +You have to pass multiple Filter-Id attributes to utilize this functionality. + + +Examples +-------- + +Fiter-Id +-------- + +Cisco AVPair +^^^^^^^^^^^^^^ + +Mikrotik +^^^^^^^^ diff --git a/doc/configuration/snmp.rst b/doc/configuration/snmp.rst new file mode 100644 index 0000000..1486bed --- /dev/null +++ b/doc/configuration/snmp.rst @@ -0,0 +1,2 @@ +SNMP +==== diff --git a/doc/configuration/sstp.rst b/doc/configuration/sstp.rst new file mode 100644 index 0000000..480c9a4 --- /dev/null +++ b/doc/configuration/sstp.rst @@ -0,0 +1,72 @@ +.. _sstp: + +[sstp] +====== + +Configuration options of sstp module. + +Configuration of SSTP module. +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +**bind=x.x.x.x|ipv6address|unix:pathname|unix:@abstract** + If this option is given then sstp server will bind to specified IP address or unix pathname/abstract socket. + +**port=n** + If this option is given then sstp server will bind to specified port. Default is 443. + +**verbose=n** + If this option is given and n is greater of zero then sstp module will produce verbose logging. + +**timeout=n** + Timeout waiting reply from client in seconds. Default is 60. + +**hello-interval=n** + If this option is given and greater then zero then sstp will send echo-request every n seconds and drop connection without a reply. Default is 60. + +**accept=ssl,proxy** + Specifies incoming connection acceptance mode. + * **ssl** - enable SSL/TLS support. + * **proxy** - enable PROXY protocol 1 & 2 support. + +**ssl-dhparam=pemfile** + Specifies a file with DH parameters for DHE ciphers. + +**ssl-ecdh-curve=string** + Specifies a curves for ECDHE ciphers. Value is specified in the format understood by the OpenSSL library. + +**ssl-ciphers=string** + Specifies the enabled ciphers. The ciphers are specified in the format understood by the OpenSSL library. + +**ssl-prefer-server-ciphers=n** + If this option is given and n is greater of zero then server ciphers should be preferred over client ciphers. Default is 0. + +**ssl-pemfile=pemfile** + Specifies a file with the certificate in the PEM format for sstp server. Certificate is also used to compute initial SHA1 and SHA256 certificate hash. + +**ssl-keyfile=keyfile** + Specifies a file with the secret key in the PEM format for sstp server. If not set, secret key will be loaded from the pemfile certificate. + +**cert-hash-proto=sha1,sha256** + Specifies hashing methods that can be used to compute the Compound MAC in the Crypto Binding attribute. Default is sha1 and sha256 both. + +**cert-hash-sha1=hexstring** + Given hexadecimal value overrides SHA1 hash computed from the pemfile certificate or used directly for non-ssl mode. + +**cert-hash-sha256=hexstring** + Given hexadecimal value overrides SHA256 hash computed from the pemfile certificate or used directly for non-ssl mode. + +**host-name=string** + If this option is given, only sstp connection to specified host and with the same TLS SNI will be allowed. + +**http-error=deny|allow|http[s]://host.tld[/path]** + Specify http layer error behavior for non-sstp requests. + * **deny** - reset connection without any error response. + * **allow** - respond with http-specific status codes. + * **http[s]://host.tld[/path]** - respond with http redirect to the specified location. If /path is not specified, requested uri will be appended automatically + Default value is allow. + +**ifname=ifname** + If this option is given ppp interface will be renamed using ifname as a template, i.e `sstp%d => sstp0`. + +**ppp-max-mtu=n** + Set the maximun MTU value that can be negociated for PPP over SSTP sessions. Default value is 1452, maximum is 4087. 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 + + 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 diff --git a/doc/favicon.ico b/doc/favicon.ico Binary files differnew file mode 100644 index 0000000..42e8969 --- /dev/null +++ b/doc/favicon.ico diff --git a/doc/guides/BRAS_tuning.rst b/doc/guides/BRAS_tuning.rst new file mode 100644 index 0000000..14395eb --- /dev/null +++ b/doc/guides/BRAS_tuning.rst @@ -0,0 +1,138 @@ +BRAS tuning +=========== + +Recommendations for BRAS (Broadband Remote Access Server) performance. + + +Network tuning +-------------- + +Disable kernel mitigations to maximize performance +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Edit file ``/etc/default/grub`` + +.. code-block:: sh + + GRUB_CMDLINE_LINUX_DEFAULT="intel_idle.max_cstate=0 processor.max_cstate=1 idle=poll quiet mitigations=off" + +Additional GRUB CMD arguments: + + * ixgbe.allow_unsupported_sfp=1 - Allow to use not original Intel SFP+ modules + * pcie_aspm=off - Disable Active-State Power Management + +After saving, please update grub settings + +.. code-block:: sh + + $sudo update-grub + +Warning! Enabling the idle loop (``idle=poll``) parameter can cause 100% CPU utilization on your VM (if you're using virtual enviroments like ProxMox, VMWare, etc.) + + +Disable NIC offloads +^^^^^^^^^^^^^^^^^^^^ +Disable hardware offloads,increase Tx/Rx buffers and queue length on your NICs to prevent speed problems. +Please note, that GSO offload changed to tx-gso-partial in Linux kernels 4.15 and later. + +Debian ``/etc/network/interfaces``: + + +.. code-block:: sh + + allow-hotplug eth0 + iface eth0 inet manual + up ethtool -K eth0 tso off gso off gro off rxvlan off txvlan off rx-vlan-filter off ntuple on &> /dev/null + up ethtool -K eth0 tx-gso-partial off &> /dev/null + up ethtool -G eth0 rx 4096 tx 4096 &> /dev/null + up ip link set eth0 txqueuelen 10000 &> /dev/null + +Please determine your NIC queue and buffers limit before increase: + +.. code-block:: sh + + + ethtool -g eth0 + + +Fix Download speed problem (shaper) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Change shaper from htb to tbf + +.. code-block:: sh + + [shaper] + … + down-limiter=tbf + + +Default rate limits (shaper) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If radius-server Access-Accept answer has no compatible speed attributes - to prevent unlimited session speed you can add default rate-limits (in Kbps). + +``nano /etc/accel-ppp.conf`` + +.. code-block:: sh + + [shaper] + rate-limit=888/888 + + +Change PPPoE MTU +^^^^^^^^^^^^^^^^ + +You can adjust allowed PPPoE min/max MTU/MRU settings: +``nano /etc/accel-ppp.conf`` + +.. code-block:: sh + + [ppp] + verbose=1 + min-mtu=1280 + mtu=1492 + mru=1492 + +Hotplug optimization +^^^^^^^^^^^^^^^^^^^^ +To generate hotplug events on IPoE interfaces (Debian 10): + +``nano /lib/udev/ifupdown-hotplug`` + +.. code-block:: sh + + case "$ACTION" in + add) + # these interfaces generate hotplug events *after* they are brought up + case $INTERFACE in + ppp*|ippp*|isdn*|plip*|lo|irda*|ipsec* + +just add ``|ipoe*`` after ``|ipsec*`` + +repeat with file ``/lib/udev/net.agent`` + +SYSTEMD-UDEV optimizations +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +1. Delete ``99-default.link`` from ``/lib/systemd/network/`` directory + +.. code-block:: sh + + rm /lib/systemd/network/99-default.link + +2. Change ``/lib/udev/rules.d/99-systemd.rules`` + +.. code-block:: sh + + ACTION=="add", SUBSYSTEM=="net", KERNEL!="lo|ppp*|ipoe*", RUN+="/lib/systemd/systemd-sysctl --prefix=/net/ipv4/conf/$name --prefix=/net/ipv4/neigh/$name --prefix=/net/ipv6/conf/$name --prefix=/net/ipv6/neigh/$name" + +Add ``|ppp*|ipoe*`` to ``KERNEL!="lo"`` + +3. Change ``/lib/udev/rules.d/80-ifupdown.rules`` + +.. code-block:: sh + + SUBSYSTEM=="net", ACTION=="add|remove", KERNEL!="ppp*|ipoe*", RUN+="ifupdown-hotplug" + +Add ``KERNEL!="ppp*|ipoe*"`` diff --git a/doc/guides/control_features.rst b/doc/guides/control_features.rst new file mode 100644 index 0000000..cc0e46d --- /dev/null +++ b/doc/guides/control_features.rst @@ -0,0 +1,97 @@ +Control features +================ + +Accel-ppp support next features for control daemon and sessions: + + * ``accel-cmd`` + + * ``telnet`` + + * ``snmp`` + + * ``RADIUS COA`` + +Common available commands for ``accel-cmd`` and ``telnet``. Also possible show this help message with one of commands ``accel-cmd help`` and ``telnet 127.0.0.1 2000`` then run ``help``. + +.. code-block:: text + + show stat - shows various statistics information + terminate if <interface> [soft|hard]- terminate session by interface name + [match] username <username> [soft|hard]- terminate session by username + ip <address> [soft|hard]- terminate session by ip address + csid <id> [soft|hard]- terminate session by calling station id + sid <id> [soft|hard]- terminate session by session id + all [soft|hard]- terminate all sessions + reload - reload config file + restart [hard] - restart daemon + hard - restart immediatly + default action - terminate all connections then restart + shutdown [soft|hard|cancel]- shutdown daemon + default action - send termination signals to all clients and wait everybody disconnects + soft - wait until all clients disconnects, don't accept new connections + hard - shutdown now, don't wait anything + cancel - cancel 'shutdown soft' and return to normal operation + exit - exit cli + show sessions [columns] [order <column>] [match <column> <regexp>] - shows sessions + columns: + netns - network namespace name + ifname - interface name + username - user name + ip - IP address + ip6 - IPv6 address + ip6-dp - IPv6 delegated prefix + type - VPN type + state - state of session + uptime - uptime (human readable) + uptime-raw - uptime (in seconds) + calling-sid - calling station id + called-sid - called station id + sid - session id + comp - compression/encryption method + rx-bytes - received bytes (human readable) + tx-bytes - transmitted bytes (human readable) + rx-bytes-raw - received bytes + tx-bytes-raw - transmitted bytes + rx-pkts - received packets + tx-pkts - transmitted packets + ipoe-type - IPoE session type + rate-limit - rate limit down-stream/up-stream (Kbit) + pppoe mac-filter reload - reload mac-filter file + pppoe mac-filter add <address> - add address to mac-filter list + pppoe mac-filter del <address> - delete address from mac-filter list + pppoe mac-filter show - show current mac-filter list + pppoe interface add <name> - start pppoe server on specified interface + pppoe interface del <name> - stop pppoe server on specified interface and drop his connections + pppoe interface show - show interfaces on which pppoe server started + pppoe set verbose <n> - set verbosity of pppoe logging + pppoe set PADO-delay <delay[,delay1:count1[,delay2:count2[,...]]]> - set PADO delays (ms) + pppoe set Service-Name <name> - set Service-Name to respond + pppoe set Service-Name * - respond with client's Service-Name + pppoe set AC-Name <name> - set AC-Name tag value + pppoe show verbose - show current verbose value + pppoe show PADO-delay - show current PADO delay value + pppoe show Service-Name - show current Service-Name value + pppoe show AC-Name - show current AC-Name tag value + shaper change <interface> <value> [temp] - change shaper on specified interface, if temp is set then previous settings may be restored later by 'shaper restore' + shaper change all <value> [temp] - change shaper on all interfaces, if temp is set also new interfaces will have specified shaper value + shaper restore <interface> - restores shaper settings on specified interface made by 'shaper change' command with 'temp' flag + shaper restore all - restores shaper settings on all interfaces made by 'shaper change' command with 'temp' flag + +accel-cmd +^^^^^^^^^ + +This application is very powerful and often used if you have `cli` connection. Be default accel-ppp listen *TCP* port *2000* for input/output with accel-cmd. However `telnet` has same functions, but `accel-cmd` is more comfortable, allow send command without enter in to another environment. Detail about cli you may read at :ref:`cli_configuration` .Let's revise `accel-cmd` possible commands. + + * `accel-cmd show stat` - one of more important command, allow display *accel-ppp* daemon statistics and information about connections types and something counters such as RADIUS auth, acct summary and lost queries. Detail below: + +telnet +^^^^^^^^^ + + +radius CoA +^^^^^^^^^^ + +Example, terminate session by username: ``echo User-Name=username | radclient -x 127.0.0.1:3799 disconnect testing123``. + +snmp +^^^^ diff --git a/doc/guides/radius_features.rst b/doc/guides/radius_features.rst new file mode 100644 index 0000000..1f602d9 --- /dev/null +++ b/doc/guides/radius_features.rst @@ -0,0 +1,38 @@ +RADIUS and DM/CoA features +========================== + +Since from commit version 385c403 accel-ppp support VRF (Virtual Routing and Forwarding). + +Usually, this feature is useful to isolate clients e.g. put client interface to some context with different routing and firewall rules. +User interface can be put to VRF context via RADIUS Access-Accept packet, or change it via RADIUS CoA. + +Accel-ppp uses own RADIUS vendor dictionary https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel and RADIUS attribute ``Accel-VRF-Name`` + +All VRFs should be manually created in advance: + +.. code-block:: sh + + ip link add VRF_NAME type vrf table RT_TABLE_ID + ip link set dev VRF_NAME up + +Linux VRF documentation https://www.kernel.org/doc/Documentation/networking/vrf.txt + +If ``Accel-VRF-Name`` is used in Access-Accept message, but VRF was not created then the session will not be established. + +Set VRF via CoA +--------------- + +Put user interface to some VRF context + +.. code-block:: sh + + echo 'User-Name=bob, Accel-VRF-Name="red"' | radclient -x 127.0.0.1:3799 coa testing123 + +Delete user interface from VRF context + +.. code-block:: sh + + echo 'User-Name=bob, Accel-VRF-Name="0"' | radclient -x 127.0.0.1:3799 coa testing123 + +If ``Accel-VRF-Name`` is used in CoA message and VRF does not exist then CoA-NAK will be sent. + diff --git a/doc/guides/recommendations.rst b/doc/guides/recommendations.rst new file mode 100644 index 0000000..d94cd56 --- /dev/null +++ b/doc/guides/recommendations.rst @@ -0,0 +1,62 @@ +Recommendations +=============== + +Enable forwarding +----------------- +To enable packet forwarding need edit /etc/sysctl.conf and add or uncomment next: + +.. code-block:: sh + + net.ipv4.ip_forward=1 + net.ipv6.conf.all.forwarding=1 + +For apply this params now, use command ``sysctl -p`` or after reboot server this params will be applied automatically. + +MTU +--- + +If used vlan-per-user often required 802.1ad standard also called as QinQ or Q-in-Q, then need to set MTU on main interface and S-VLAN, because adding to headed one more field. +Interface which using QinQ usually consist of ``<interface_name>.<S-VLAN>.<C-VLAN>``. +S-VLAN (Service VLAN) is TAG which wrap C-VLAN (Customer VLAN). + +As example: + +.. code-block:: sh + + MTU + 1504 + | 1504 + | | 1500 + | | | + eth0.2001.101 + | | | + | | C-VLAN + | S-VLAN + Interface + +Set up MTU on interface eth0 and interface with S-VLAN + +.. code-block:: sh + + ip link set eth0 mtu 1504 + ip link set eth0.2001 mtu 1504 + +.. admonition:: Note: + + If used ``bonding`` need change MTU on *bonding* (bond0) and *slaves* (eth0, eth1 ...) interfaces. + +Increase ARP cache size +----------------------------- + +If accel-ppp used as DHCP BRAS important to increase ARP cache size, otherwise you can cache overflow and clients have lost connections. Edit /etc/sysctl.conf and add next: + +.. code-block:: sh + + net.ipv4.neigh.default.gc_thresh1 = 4096 + net.ipv4.neigh.default.gc_thresh2 = 8192 + net.ipv4.neigh.default.gc_thresh3 = 12288 + net.ipv6.neigh.default.gc_thresh1 = 4096 + net.ipv6.neigh.default.gc_thresh2 = 8192 + net.ipv6.neigh.default.gc_thresh3 = 12288 + +For apply this params now, use command ``sysctl -p`` or after reboot server this params will be applied automatically. diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 0000000..741b6ab --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,25 @@ +.. _index: + +Welcome to accel-ppp's documentation! +===================================== +Accel-ppp is a high performance PPTP/L2TP/SSTP/PPPoE/IPoE server for Linux. + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + :includehidden: + + installation/install.rst + configuration/configuration.rst + guides/control_features.rst + guides/recommendations.rst + guides/BRAS_tuning.rst + guides/radius_features.rst + examples/examples.rst + debugging/index.rst + debugging/faq.rst + +.. toctree:: + :maxdepth: 2 + :caption: Contributing: + :includehidden: diff --git a/doc/installation/centos.rst b/doc/installation/centos.rst new file mode 100644 index 0000000..92d11c9 --- /dev/null +++ b/doc/installation/centos.rst @@ -0,0 +1,104 @@ +.. _install_centos: + +Install on Centos +----------------- + +For compile with modules **vlan_mon** and **ipoe** on centos need install vanilla linux kernel or :ref:`elrepo_kernel_inst` . If that not needed, just set **-DBUILD_IPOE_DRIVER=FALSE** and **-DBUILD_VLAN_MON_DRIVER=FALSE** on cmake. + +**Preparation** + +Before compile and build package need satisfy some dependencies + +* **rpm-build** - open-source system that manages the build process +* **cmake** - open-source system that manages the build process +* **gcc** - GNU Compiler Collection (GCC) is a compiler system +* **git** - version-control system for tracking changes, (need for downloading source code) +* **pcre-devel** - source code of pcre lib, accel-ppp need it for use reg expression +* **openssl-devel** - source code of lib ssl, accel-ppp need it for use regular expression +* **lua-devel** - this need for create custom username (IPoE) from packet. Script write on lua language + +.. code-block:: sh + + yum -y install rpm-build make cmake gcc git pcre-devel openssl-devel lua-devel + +After install dependencies, download accel-ppp source code with git client, tree master . Master tree contain actual patches last release. + +.. code-block:: sh + + git clone https://github.com/accel-ppp/accel-ppp.git /opt/accel-ppp-code + +Create directory for build source code and go to this directory. + +.. code-block:: sh + + mkdir /opt/accel-ppp-code/build + cd /opt/accel-ppp-code/build/ + +For building code need we can set next params: + +* **-DBUILD_IPOE_DRIVER=TRUE** include IPoE module.This module need if you want use accel-ppp as shared interface. +* **-DBUILD_VLAN_MON_DRIVER=TRUE** include vlan monitoring module. If you want create vlan automatically on analyse IP headers with regular expression set on accel-ppp config file. (Available for IPoE and PPPoE) +* **-DKDIR=/usr/src/kernels/`uname -r`** sets path to Linux kernel source code. Need only for build IPOE, VLAN-MON. +* **-DCMAKE_INSTALL_PREFIX=/usr** path for install executable code. If you build DEB package, not recommended change this. +* **-DCPACK_TYPE=Centos7** this arguments for building RPM package. If used centos other version, set it. + +.. code-block:: sh + + cmake -DBUILD_IPOE_DRIVER=TRUE -DBUILD_VLAN_MON_DRIVER=TRUE -DCMAKE_INSTALL_PREFIX=/usr -DKDIR=/usr/src/kernels/`uname -r` -DLUA=TRUE -DCPACK_TYPE=Centos7 .. + +.. admonition:: Notice: + + ended symbols **..** sets path to accel-ppp source code, not delete this! Or you can replace it full path to accel-ppp-code like /opt/accel-ppp-code/ + +Compile: + +.. code-block:: sh + + make + +Create RPM package: + +.. code-block:: sh + + cpack -G RPM + +Install package: + +.. code-block:: sh + + rpm -ivh accel-ppp.rpm + +If accel-ppp was build with modules **ipoe** and **vlan_mon**, need next: + +.. code-block:: sh + + cp ./drivers/ipoe/driver/ipoe.ko /lib/modules/`uname -r`/kernel/net + cp ./drivers/vlan_mon/driver/vlan_mon.ko /lib/modules/`uname -r`/kernel/net + depmod -a + +If you have success packet install, rename config file to accel-ppp.conf + +.. code-block:: sh + + mv /etc/accel-ppp.conf.dist /etc/accel-ppp.conf + +Edit accel-ppp.conf for you schemas and run accel-ppp + +**Run as systemd unit:** + +.. code-block:: sh + + systemctl start accel-ppp + +or run manual (not recommended) + +.. code-block:: sh + + accel-pppd -d -c /etc/accel-ppp.conf -p /var/run/accel-ppp.pid + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + :includehidden: + + elrepo_kernel_inst.rst
\ No newline at end of file diff --git a/doc/installation/debian.rst b/doc/installation/debian.rst new file mode 100644 index 0000000..877b153 --- /dev/null +++ b/doc/installation/debian.rst @@ -0,0 +1,88 @@ +Install on Debian +----------------- +**Preparation** + +Before compile and build package need satisfy some dependencies + +* **cmake** - open-source system that manages the build process +* **gcc** - GNU Compiler Collection (GCC) is a compiler system +* **linux-headers-`uname -r`** - source code of current installing linux kernel, need for build ipoe and vlan_mon modules. If you don`t need these modules, you may don`t install this +* **git** - version-control system for tracking changes, (need for downloading source code) +* **libpcre3-dev** - source code of pcre lib, accel-ppp need it for use reg expression +* **libssl-dev** - source code of pcre lib, accel-ppp need it for use regular expression +* **liblua5.1-0-dev** - this need for create custom username (IPoE) from packet. Script write on lua language + +.. code-block:: sh + + apt-get install -y build-essential cmake gcc linux-headers-`uname -r` git libpcre3-dev libssl-dev liblua5.1-0-dev + +After install dependencies, download accel-ppp source code with git client, tree master . Master tree contain actual patches last release. + +.. code-block:: sh + + git clone https://github.com/accel-ppp/accel-ppp.git /opt/accel-ppp-code + +Create directory for build source code and go to this directory. + +.. code-block:: sh + + mkdir /opt/accel-ppp-code/build + cd /opt/accel-ppp-code/build/ + +For building code need we can set next params: + +* **-DBUILD_IPOE_DRIVER=TRUE** include IPoE module.This module need if you want use accel-ppp as shared interface. +* **-DBUILD_VLAN_MON_DRIVER=TRUE** include vlan monitoring module. If you want create vlan automatically on analyse IP headers with regular expression set on accel-ppp config file. (Available for IPoE and PPPoE) +* **-DKDIR=/usr/src/linux-headers-`uname -r`** sets path to Linux kernel source code. Need only for build IPOE, VLAN-MON. +* **-DCMAKE_INSTALL_PREFIX=/usr** path for install executable code. If you build DEB package, not recommended change this. +* **-DCPACK_TYPE=Debian10** this arguments for building DEB package. If used debian other version, set it. For example, if used debian 9 set **-DCPACK_TYPE=Debian9** + +.. code-block:: sh + + cmake -DBUILD_IPOE_DRIVER=TRUE -DBUILD_VLAN_MON_DRIVER=TRUE -DCMAKE_INSTALL_PREFIX=/usr -DKDIR=/usr/src/linux-headers-`uname -r` -DLUA=TRUE -DCPACK_TYPE=Debian10 .. + +.. admonition:: Notice: + + ended symbols **..** sets path to accel-ppp source code, not delete this! Or you can replace it full path to accel-ppp-code like /opt/accel-ppp-code/ + +Compile: + +.. code-block:: sh + + make + +Create DEB package: + +.. code-block:: sh + + cpack -G DEB + +Install package: + +.. code-block:: sh + + dpkg -i accel-ppp.deb + +If you have success packet install, rename config file to accel-ppp.conf + +.. code-block:: sh + + mv /etc/accel-ppp.conf.dist /etc/accel-ppp.conf + +Edit accel-ppp.conf for you schemas and run accel-ppp + +**Run as systemd unit:** + +.. code-block:: sh + + systemctl start accel-ppp + +or run manual (not recommended) + +.. code-block:: sh + + accel-pppd -d -c /etc/accel-ppp.conf -p /var/run/accel-ppp.pid + + +Update procedure +^^^^^^^^^^^^^^^^^ diff --git a/doc/installation/elrepo_kernel_inst.rst b/doc/installation/elrepo_kernel_inst.rst new file mode 100644 index 0000000..a2c3501 --- /dev/null +++ b/doc/installation/elrepo_kernel_inst.rst @@ -0,0 +1,46 @@ +.. _elrepo_kernel_inst: + +Install kernel from elrepo +========================== + +At first need enable ELRepo Repository. To set up ELRepo repository, you need to import its official GPG key and then install ELRepo RPM as follows. Also you can follow original http://elrepo.org/tiki/tiki-index.php instalation guide. + +For Centos 7 + +.. code-block:: sh + + rpm --import https://www.elrepo.org/RPM-GPG-KEY-elrepo.org + rpm -Uvh https://www.elrepo.org/elrepo-release-7.0-3.el7.elrepo.noarch.rpm + +For Centos 8 + +.. code-block:: sh + + rpm --import https://www.elrepo.org/RPM-GPG-KEY-elrepo.org + yum install https://www.elrepo.org/elrepo-release-8.0-2.el8.elrepo.noarch.rpm + +Install kernel-ml and kernel-ml-devel + +.. code-block:: sh + + yum --enablerepo=elrepo-kernel install -y kernel-ml kernel-ml-devel + +To show installed kernels run command: + +.. code-block:: sh + + awk -F\' '$1=="menuentry " {print $2}' /etc/grub2.cfg + +Set installed kernel as default for grub2 bootloader: + +.. code-block:: sh + + grub2-set-default 0 + +Reboot system and check kernel version + +.. code-block:: sh + + uname -r + +Now you can continue :ref:`install_centos` with modules **vlan_mon** and **ipoe** diff --git a/doc/installation/generic_inst.rst b/doc/installation/generic_inst.rst new file mode 100644 index 0000000..ec8b87f --- /dev/null +++ b/doc/installation/generic_inst.rst @@ -0,0 +1,75 @@ +Generic Installation +-------------------- + +Requirment +^^^^^^^^^^ + +* modern linux distribution +* kernel-2.6.25 or later +* cmake-2.6 or later +* libnl-2.0 or probably later (optional, required for builtin shaper) +* libcrypto-0.9.8 or probably later (openssl-0.9.8) +* libpcre +* net-snmp-5.x (optional, required for snmp) +* libssl-0.9.8 or probably later (openssl-0.9.8) +* liblua5.1 probably later (optional, required for create username fundamental on packet header information) + +Compilation and instalation +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Make sure you have configured kernel headers in /usr/src/linux, or specify other location via KDIR. + +Download accel-ppp source code with git client, tree master . Master tree contain actual patches last release. + +.. code-block:: sh + + git clone https://github.com/accel-ppp/accel-ppp.git accel-ppp-code + +Create directory for build source code and go to this directory. + +.. code-block:: sh + + mkdir /opt/accel-ppp-code/build + cd /opt/accel-ppp-code/build/ + + +.. code-block:: sh + + cmake [-DBUILD_DRIVER=FALSE] [-DKDIR=/usr/src/linux] [-DCMAKE_INSTALL_PREFIX=/usr/local] [-DCMAKE_BUILD_TYPE=Release] [-DLOG_PGSQL=FALSE] [-DSHAPER=FALSE] [-DRADIUS=TRUE] [-DNETSNMP=FALSE] .. + +.. admonition:: Notice: + + Please note that the double dot record in the end of the command is essential. + You'll probably get error or misconfigured sources if you miss it. + +BUILD_DRIVER, KDIR, CMAKE_INSTALL_PREFIX, CMAKE_BUILD_TYPE, LOG_PGSQL, SHAPER, RADIUS are optional, +but while pptp is not present in mainline kernel you probably need BUILD_DRIVER. + +.. code-block:: sh + + make + make install + +Run +^^^ + +.. code-block:: sh + + accel-pppd -d -p /var/run/accel-ppp.pid -c /etc/accel-ppp.conf + +.. code-block:: sh + + usage: accel-pppd [-d] [-p <file>] -c <file> + where: + -d - daemon mode + -p - write pid to <file> + -c - config file + +Control +^^^^^^^ +Accel-ppp support next features for control daemon and sessions + +* **accel-cmd** +* **telnet** +* **radius CoA** +* **snmp** diff --git a/doc/installation/install.rst b/doc/installation/install.rst new file mode 100644 index 0000000..3c1fe60 --- /dev/null +++ b/doc/installation/install.rst @@ -0,0 +1,15 @@ +.. _install: + +Installation +============ + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + :includehidden: + + generic_inst.rst + debian.rst + ubuntu.rst + centos.rst + diff --git a/doc/installation/ubuntu.rst b/doc/installation/ubuntu.rst new file mode 100644 index 0000000..eb98ca5 --- /dev/null +++ b/doc/installation/ubuntu.rst @@ -0,0 +1,84 @@ +Install on Ubuntu +----------------- +**Preparation** + +Before compile and build package need satisfy some dependencies + +* **cmake** - open-source system that manages the build process +* **gcc** - GNU Compiler Collection (GCC) is a compiler system +* **linux-headers-`uname -r`** - source code of current installing linux kernel, need for build ipoe and vlan_mon modules. If you don`t need these modules, you may don`t install this +* **git** - version-control system for tracking changes, (need for downloading source code) +* **libpcre3-dev** - source code of pcre lib, accel-ppp need it for use reg expression +* **libssl-dev** - source code of pcre lib, accel-ppp need it for use regular expression +* **liblua5.1-0-dev** - this need for create custom username (IPoE) from packet. Script write on lua language + +.. code-block:: sh + + apt-get install -y build-essential cmake gcc linux-headers-`uname -r` git libpcre3-dev libssl-dev liblua5.1-0-dev + +After install dependencies, download accel-ppp source code with git client, tree master . Master tree contain actual patches last release. + +.. code-block:: sh + + git clone https://github.com/accel-ppp/accel-ppp.git /opt/accel-ppp-code + +Create directory for build source code and go to this directory. + +.. code-block:: sh + + mkdir /opt/accel-ppp-code/build + cd /opt/accel-ppp-code/build/ + +For building code need we can set next params: + +* **-DBUILD_IPOE_DRIVER=TRUE** include IPoE module.This module need if you want use accel-ppp as shared interface. +* **-DBUILD_VLAN_MON_DRIVER=TRUE** include vlan monitoring module. If you want create vlan automatically on analyse IP headers with regular expression set on accel-ppp config file. (Available for IPoE and PPPoE) +* **-DKDIR=/usr/src/linux-headers-`uname -r`** sets path to Linux kernel source code. Need only for build IPOE, VLAN-MON. +* **-DCMAKE_INSTALL_PREFIX=/usr** path for install executable code. If you build DEB package, not recommended change this. +* **-DCPACK_TYPE=Ubuntu18** this arguments for building DEB package. If used Ubuntu other version, set it. For example, if used Ubuntu 16 set **-DCPACK_TYPE=Ubuntu16** + +.. code-block:: sh + + cmake -DBUILD_IPOE_DRIVER=TRUE -DBUILD_VLAN_MON_DRIVER=TRUE -DCMAKE_INSTALL_PREFIX=/usr -DKDIR=/usr/src/linux-headers-`uname -r` -DLUA=TRUE -DCPACK_TYPE=Ubuntu18 .. + +.. admonition:: Notice: + + ended symbols **..** sets path to accel-ppp source code, not delete this! Or you can replace it full path to accel-ppp-code like /opt/accel-ppp-code/ + +Compile: + +.. code-block:: sh + + make + +Create DEB package: + +.. code-block:: sh + + cpack -G DEB + +Install package: + +.. code-block:: sh + + dpkg -i accel-ppp.deb + +If you have success packet install, rename config file to accel-ppp.conf + +.. code-block:: sh + + mv /etc/accel-ppp.conf.dist /etc/accel-ppp.conf + +Edit accel-ppp.conf for you schemas and run accel-ppp + +**Run as systemd unit:** + +.. code-block:: sh + + systemctl start accel-ppp + +or run manual (not recommended) + +.. code-block:: sh + + accel-pppd -d -c /etc/accel-ppp.conf -p /var/run/accel-ppp.pid diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 0000000..7eb8adf --- /dev/null +++ b/doc/requirements.txt @@ -0,0 +1,2 @@ +Sphinx==4.5.0 +sphinx-rtd-theme==1.0.0 |
