wiki:backhaul
Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
wiki:backhaul [2018/09/26 12:03] ghi [Interface management through RESTAPI] |
— (current) | ||
|---|---|---|---|
| Line 1: | Line 1: | ||
| - | ====== Backhaul configuration ====== | ||
| - | ===== Overall network presentation ===== | ||
| - | |||
| - | To connect an Wirnet iBTS gateway to a network there are two possible interfaces: | ||
| - | * Ethernet | ||
| - | * GSM | ||
| - | |||
| - | {{:images:ibts_network_layers_2.1.png?900|}} | ||
| - | |||
| - | The interfaces are handled by ConnMan, which is a daemon for managing Internet connections within embedded devices. ConnMan provides a way to auto connect interfaces, to prioritize interfaces (route management), and to configure fallback interfaces. ConnMan is not used to monitor the network. | ||
| - | |||
| - | GSM protocol is handled by oFono. The use of oFono is almost entirely handled by ConnMan. | ||
| - | Ethernet is directly handled by ConnMan. | ||
| - | For further details about ConnMan, please refer to [[https://01.org/connman/documentation|Connman documentation]]. | ||
| - | |||
| - | Interfaces' configuration could be done through: | ||
| - | |||
| - | * Wirnet iBTS web interface. | ||
| - | * SMS. | ||
| - | * RESTAPI. | ||
| - | * editable configuration files. | ||
| - | |||
| - | Kerlink provides two scripts to monitor the network (only one can be used at the same time): | ||
| - | * ''networkmonitoring.py'': This script is self-sufficient. It is used to monitor/repair the default route (it regularly pings an IP). | ||
| - | * ''fixnetwork.py'': This script is designed to be called by a customer application. It is used to repair multiple interfaces at the same time. | ||
| - | |||
| - | ===== Interface management over web interface ===== | ||
| - | |||
| - | See the dedicated page: [[wiki:webui:#network_configuration|Web interface]]. | ||
| - | |||
| - | ===== Interface management through SMS ===== | ||
| - | |||
| - | See the dedicated page: [[wiki:sms#configuration_commands|SMS]]. | ||
| - | |||
| - | ===== Interface management through RESTAPI ===== | ||
| - | |||
| - | See the dedicated page: [[wiki:restapi|RESTAPI]]. | ||
| - | |||
| - | ===== Interface management through configuration files ===== | ||
| - | |||
| - | ==== Network auto-connection and fallback ==== | ||
| - | |||
| - | ConnMan’s auto-connection and fallback are configured via the editable configuration file ''/etc/network/connman/main.conf''. ConnMan automatically detects configuration changes and applies them when the configuration file is closed. | ||
| - | |||
| - | === Auto-connection and preferred technologies === | ||
| - | |||
| - | Connman handles which interfaces should be mounted/used in which order, at boot time, but also when an interface appears/disappears. | ||
| - | |||
| - | The behaviour of connman regarding interface mounting can be changed with the following options. Please refer to [[https://01.org/connman/documentation|connman's documentation]] to properly understand how these parameters are used. By default ConnMan will auto-connect to Ethernet and cellular and prioritizes Ethernet over cellular. | ||
| - | |||
| - | <code> | ||
| - | DefaultAutoConnectTechnologies = ethernet, wifi, cellular | ||
| - | PreferredTechnologies = ethernet, wifi, cellular | ||
| - | </code> | ||
| - | |||
| - | Removing a technology from these parameters does not mean that this technology will not be used. It means that this technology will be used last. | ||
| - | To force a technology to be unused, the following parameter can be used. | ||
| - | |||
| - | <code> | ||
| - | NetworkInterfaceBlacklist = ethernet | ||
| - | </code> | ||
| - | |||
| - | The field ''wifi'' is a default value for ConnMan but it is not used on the Wirnet iBTS since WiFi is not available. | ||
| - | |||
| - | === Online check configuration === | ||
| - | |||
| - | The routing table is managed by ConnMan. To define what should be the default route, in addition to the preferred technologies and the auto connected technologies mechanism, ConnMan tries to connect to an HTTP server when the interface is mounted. If successful, service is declared as Online, if not, it is declared Ready. | ||
| - | |||
| - | This is what **O** or **R** means in connmanctl services. | ||
| - | Example:<code bash> | ||
| - | root@klk-lpbs_040070:~ # connmanctl services | ||
| - | *AO Wired ethernet_7076ff0100b5_cable | ||
| - | *AR Orange F cellular_208017001155386_context1 | ||
| - | root@klk-lpbs_040070:~ # connmanctl connect cellular_208017001155386_context1 | ||
| - | Connected cellular_208017001155386_context1 | ||
| - | </code> | ||
| - | |||
| - | By default, ConnMan tries to reach the server “ipv4.connman.net”. Since the gateway is used to send/receive LoRa packets to an LNS, checking the default server is not optimal. For example, the LNS could be in a local network, or “ipv4.connman.net” could be down. In that cases, the check would be negative whereas the LNS is reachable. For this reasons, it is strongly advised to configure connman to check the LNS instead of “ipv4.connman.net”. | ||
| - | |||
| - | The online check mechanism can be configured with the following parameters: | ||
| - | |||
| - | <code bash> | ||
| - | EnableOnlineCheck = true | ||
| - | OnlineCheckUseConnmanHeaders = true | ||
| - | OnlineCheckServerIpV4Url = http://ipv4.connman.net/online/status.html | ||
| - | OnlineCheckServerIpV6Url = http://ipv6.connman.net/online/status.html | ||
| - | </code> | ||
| - | |||
| - | When checking if a service is online, the ''OnlineCheckUseConnmanHeaders'' parameter forces connman to check for specific headers in HTTP response. | ||
| - | If this setting is false, a 200 status is enough to say that service is ONLINE. When using your own server, set ''OnlineCheckUseConnmanHeaders'' to false, otherwise Connman specific headers will be tested. | ||
| - | |||
| - | When using the ''OnlineCheckUseConnmanHeaders'' parameter, before configuring the URL in connman, it is strongly advised to check the response of this URL. | ||
| - | |||
| - | You can use the following command for the check. Replace the URL by your own. | ||
| - | <code bash> | ||
| - | # curl -vs http://www.google.com/ | ||
| - | </code> | ||
| - | |||
| - | The check is OK if ''< HTTP/1.x 200 OK'' is displayed | ||
| - | |||
| - | <code bash> | ||
| - | * Trying 172.217.16.68... | ||
| - | * Connected to www.google.com (172.217.16.68) port 80 (#0) | ||
| - | > GET / HTTP/1.1 | ||
| - | > Host: www.google.com | ||
| - | > User-Agent: curl/7.47.1 | ||
| - | > Accept: */* | ||
| - | > | ||
| - | < HTTP/1.1 200 OK | ||
| - | < Date: Tue, 10 Apr 2018 13:24:22 GMT | ||
| - | < Expires: -1 | ||
| - | < Cache-Control: private, max-age=0 | ||
| - | < Content-Type: text/html; charset=ISO-8859-1 | ||
| - | < P3P: CP="This is not a P3P policy! See g.co/p3phelp for more info." | ||
| - | < X-XSS-Protection: 1; mode=block | ||
| - | < X-Frame-Options: SAMEORIGIN | ||
| - | < Server: gws | ||
| - | < Set-Cookie: 1P_JAR=2018-04-10-13; expires=Thu, 10-May-2018 13:24:22 GMT; path=/; domain=.google.com | ||
| - | < Set-Cookie: NID=127=bLF6FcSHkY73RVk5FpKGpy4vOr8MO2F6GA__Z-N-jSYPT0bmu7blzhSAwT84rUFaN8QVAof8iDLSFTCnWSN0zExyMYx7d2apB5lRsg0uKfartso28B-SmC9cVBOL_Hgp; expires=Wed, 10-Oct-2018 13:24:22 GMT; path=/; domain=.google.com; HttpOnly | ||
| - | < Accept-Ranges: none | ||
| - | < Vary: Accept-Encoding | ||
| - | < Transfer-Encoding: chunked | ||
| - | < | ||
| - | <!doctype html> | ||
| - | ... | ||
| - | </code> | ||
| - | |||
| - | <note important> | ||
| - | ConnMan does not try to ping an IP address to determine whether the interface is working. It only checks if the interface is available. Thus, in case Ethernet is preferred, and an Ethernet cable is connected between the gateway and a switch, and this switch is not connected to any network, the fallback interface will not be used. \\ | ||
| - | A monitoring of the connection must be done to solve such cases: see [[wiki:backhaul#network_monitoring]] | ||
| - | </note> | ||
| - | |||
| - | ==== Ethernet configuration ==== | ||
| - | |||
| - | === LAN Ethernet === | ||
| - | |||
| - | ConnMan’s LAN Ethernet configuration is done via an editable configuration file ''/etc/network/connman/lan.config''. This file is not created by default on the gateway. A configuration file ''/etc/network/connman/lan.config.example'' is provided. \\ | ||
| - | Once file ''/etc/network/connman/lan.config'' is created, relaunch connman to apply the configuration ''/etc/init.d/connman restart''. | ||
| - | |||
| - | By default DHCP is used, there is no default IP address. To use static IP addressing, the field ''IPv4'' can be changed, for example, from | ||
| - | |||
| - | <code ini>IPv4 = dhcp</code> | ||
| - | |||
| - | to | ||
| - | |||
| - | <code ini>IPv4 = 192.168.1.0/24/192.168.1.1</code> | ||
| - | |||
| - | Where ''192.168.1.0'' will be the new IP address of the Wirnet iBTS, ''24'' will be the subnet length (in bits), and ''192.168.1.1'' will be the default gateway. | ||
| - | |||
| - | If DNS resolution is needed, the ''Nameservers'' field can be added. Multiple addresses can be used. For example: | ||
| - | |||
| - | <code ini>Nameservers = 192.0.2.1,192.0.2.2</code> | ||
| - | |||
| - | ConnMan automatically detects the changes and applies them when the configuration file is closed. | ||
| - | |||
| - | === LOCAL Ethernet === | ||
| - | |||
| - | To check and analyze the status of the Wirnet iBTS, a computer can be connected to the //LOCAL// RJ45 connector of the CPU module. | ||
| - | |||
| - | Local Ethernet is managed independently by the //ifplugd// daemon. | ||
| - | |||
| - | Once an ethernet cable plug is detected: | ||
| - | - 3 DHCP discover frames are sent to check if a DHCP server is present on the network | ||
| - | - If it fails, a static IP address is set as configured in ''/etc/network/ifplugd/local.conf''. The default IP address is ''192.168.1.1'' | ||
| - | |||
| - | A DHCP server can also be started if configured. | ||
| - | |||
| - | ==== Cellular configuration ==== | ||
| - | |||
| - | The cellular modem is from SierraWireless. This modem provides integrated userland APIs called //qmi//. Cellular configuration is achieved by configuring oFono. Each time a new sim card is used oFono configuration need to be reloaded. | ||
| - | |||
| - | === oFono === | ||
| - | |||
| - | The oFono daemon is used to configure the modem at startup or to reconfigure the modem. | ||
| - | |||
| - | oFono also provides a D-Bus API to get and set the properties of the modem. It's mainly used to provision ConnMan and to abstract future modem modifications. | ||
| - | |||
| - | To get alarms or any information from modem through oFono API, please refer to [[http://git.kernel.org/cgit/network/ofono/ofono.git/tree/doc|oFono Documentation]]. | ||
| - | |||
| - | == Configuring oFono == | ||
| - | |||
| - | oFono configuration is done via the editable configuration file ''/etc/network/ofono/provisioning''. | ||
| - | |||
| - | It is used to define APN, PIN code and cellular context: | ||
| - | * Multiple PIN code for multiple SIM card can be stored in this file (using SIM card ICCID). | ||
| - | * A default PIN code for all SIM cards can be stored. | ||
| - | * Usually SIM cards only need ''SIM PIN'' code to be unlocked but sometimes other types of PIN code can be used, as described in the example below. | ||
| - | |||
| - | <file ini provisioning> | ||
| - | # Syntax: | ||
| - | #[operator:MCC,MNC] | ||
| - | #internet.AccessPointName=APN => only mandatory field | ||
| - | #internet.Username=myUsername | ||
| - | #internet.Password=myPassword | ||
| - | #internet.AuthenticationMethod=[chap, pap] => default is chap | ||
| - | #internet.Protocol=[ip, ipv6, dual] => default is ip | ||
| - | # | ||
| - | #[sim:ICCID] | ||
| - | #pin=XXXX => SIM PIN of SIM identified by ICCID | ||
| - | #phone=XXXX => PH-SIM PIN of SIM identified by ICCID | ||
| - | #firstphone=XXXX => PH-FSIM PIN of SIM identified by ICCID | ||
| - | #network=XXXX => PH-NET PIN of SIM identified by ICCID | ||
| - | #netsub=XXXX => PH-NETSUB PIN of SIM identified by ICCID | ||
| - | #service=XXX => PH-SP PIN of SIM identified by ICCID | ||
| - | #corp=XXXX => PH-CORP PIN of SIM identified by ICCID | ||
| - | # | ||
| - | #[sim] | ||
| - | #pin=XXXX => default SIM PIN | ||
| - | #phone=XXXX => default PH-SIM PIN | ||
| - | #firstphone=XXXX => default PH-FSIM PIN | ||
| - | #network=XXXX => default PH-NET PIN | ||
| - | #netsub=XXXX => default PH-NETSUB PIN | ||
| - | #service=XXX => default PH-SP PIN | ||
| - | #corp=XXXX => default PH-CORP PIN | ||
| - | |||
| - | # Orange | ||
| - | [operator:208,01] | ||
| - | internet.AccessPointName=orange.m2m.spec | ||
| - | |||
| - | # SFR | ||
| - | [operator:208,10] | ||
| - | internet.AccessPointName=websfr | ||
| - | </file> | ||
| - | |||
| - | A list of Mobile Network Code / Mobile Country Code can be found on [[http://mcc-mnc.com/|mcc-mnc.com]]. | ||
| - | |||
| - | <note important> | ||
| - | * If a Roaming SIM card is inserted in the gateway, the **MCC/MNC** codes to configure should be those ones of the SIM and not those of the local operator. | ||
| - | * The **APN** to configure is the one of the SIM provider also, not the one of the local operator. | ||
| - | </note> | ||
| - | |||
| - | oFono stores information about SIM cards into the ''/etc/network/ofono/YOUR_IMSI*'' folder. The provisioning file is only used if this folder does not exist. | ||
| - | |||
| - | To update oFono with the last configuration, each time the provisioning file, or the SIM card is changed, a service ''reset'' has to be performed. | ||
| - | |||
| - | <code bash> | ||
| - | /etc/init.d/ofono reset | ||
| - | </code> | ||
| - | |||
| - | === GSM tools === | ||
| - | |||
| - | == GSM diagnosis tool == | ||
| - | |||
| - | <note important> | ||
| - | The //GSM diagnosis// tool is delivered //as-is// (not fully validated). | ||
| - | </note> | ||
| - | |||
| - | GSM diagnosis tool is a script using oFono interfaces to detect most common problems on GSM modems. It can also be used to have a quick view of GSM modems status on board. | ||
| - | |||
| - | It produces a text file ''/tmp/gsmdiag.txt'' with information on modem status inside. | ||
| - | |||
| - | Call of script: | ||
| - | |||
| - | <code bash> | ||
| - | root@klk-lpbs-040070:~ # gsmdiag.py | ||
| - | Diagnostic written in /tmp/gsmdiag.txt | ||
| - | </code> | ||
| - | |||
| - | Diagnosis file (wrong pin code case): | ||
| - | |||
| - | <file> | ||
| - | Number of modems: 1 | ||
| - | [Modem:/sierra_1] | ||
| - | Powered:1 | ||
| - | Online:0 | ||
| - | Manufacturer:Sierra Wireless, Incorporated | ||
| - | Model:MC7304 | ||
| - | Revision:SWI9X15C_05.05.39.02 r22713 carmd-fwbuild1 2014/06/19 16:48:58 | ||
| - | [SimProps] | ||
| - | Present:1 | ||
| - | CardIdentifier:89330120403002181830 | ||
| - | SubscriberIdentity: property does not exist | ||
| - | LockedPins:dbus.Array([dbus.String(u'pin')], signature=dbus.Signature('s'), variant_level=1) | ||
| - | PinRequired:pin | ||
| - | Error: SIM code required (PIN, PUK, ...) | ||
| - | </file> | ||
| - | |||
| - | Diagnosis file (modem ready to connect): | ||
| - | |||
| - | <file> | ||
| - | Number of modems: 1 | ||
| - | [Modem:/sierra_0] | ||
| - | Powered:1 | ||
| - | Online:1 | ||
| - | Manufacturer:Sierra Wireless, Incorporated | ||
| - | Model:MC7304 | ||
| - | Revision:SWI9X15C_05.05.39.02 r22713 carmd-fwbuild1 2014/06/19 16:48:58 | ||
| - | [SimProps] | ||
| - | Present:1 | ||
| - | CardIdentifier:89330120403002181830 | ||
| - | SubscriberIdentity:208016202395143 | ||
| - | LockedPins:dbus.Array([dbus.String(u'pin')], signature=dbus.Signature('s'), variant_level=1) | ||
| - | PinRequired:none | ||
| - | [NetworkRegistrationProps] | ||
| - | Status:registered | ||
| - | MobileCountryCode:208 | ||
| - | MobileNetworkCode:01 | ||
| - | Name:Orange F | ||
| - | Strength:40 | ||
| - | [ConnectionContexts] | ||
| - | [/sierra_0/context1] | ||
| - | Name:Internet | ||
| - | Active:0 | ||
| - | Type:internet | ||
| - | Protocol:ip | ||
| - | AccessPointName:orange.m2m.spec | ||
| - | Username: | ||
| - | Password: | ||
| - | AuthenticationMethod:chap | ||
| - | </file> | ||
| - | |||
| - | == getmodeminfo.py tool == | ||
| - | |||
| - | This script displays: | ||
| - | * Humanly readable hardware position of a GSM modem: | ||
| - | * slot and position in slot | ||
| - | * or "extusb" if modem is a dongle (since 3.3) | ||
| - | * oFono path of a GSM modem | ||
| - | * ConnMan service corresponding to a GSM modem | ||
| - | * Network interface corresponding to a GSM modem | ||
| - | * Modem syspath | ||
| - | A modem can be identified by any of these parameters. | ||
| - | |||
| - | Only meaningful parameters are displayed (if a modem is not attached to a data network, it does not have a corresponding Connman service). | ||
| - | |||
| - | <code> | ||
| - | root@klk-lpbs-0504B4:~ # getmodeminfo.py | ||
| - | Usage: /usr/bin/getmodeminfo.py [OPTION] | ||
| - | Options are: | ||
| - | -h get modem info from modem hardware position | ||
| - | -h modemslot,modemposition: for modem inside WAN modules | ||
| - | -h extusb: for modem plugged on external USB | ||
| - | -h syspath: for any modem (example: /sys/devices/soc0/soc/2100000.aips-bus/2184200.usb/ci_hdrc.1/usb2/2-1/2-1.3) | ||
| - | -o ofononame: get modem info from modem ofono name (example: /sierra_0) | ||
| - | -c connmanservice: get modem info from corresponding connman service | ||
| - | -n interfacename: get modem info from corresponding network interface name | ||
| - | </code> | ||
| - | |||
| - | When successful, the output will look like this: | ||
| - | <code> | ||
| - | root@klk-lpbs-0504B4:~ #getmodeminfo.py -n ppp0 | ||
| - | modem position: extusb | ||
| - | ofono modem name: /huawei_0 | ||
| - | connman service: cellular_208103292732049_context1 | ||
| - | network interface name: ppp0 | ||
| - | modem syspath: /sys/devices/soc0/soc/2100000.aips-bus/2184000.usb/ci_hdrc.0/usb1/1-1 | ||
| - | </code> | ||
| - | |||
| - | == AT commands == | ||
| - | |||
| - | //AT// commands are instructions used to control a modem. They allow users to communicate directly with the modem. //AT// is the abbreviation of ATtention. It is used for different operations such as debugging, dialing and changing connection parameters. | ||
| - | |||
| - | Serial port to access GSM module //AT// command interface is ''/dev/slot/${SLOTNO}/ttyAT'' (speed: 115200), where ''$SLOTNO'' is the slot number (''1'' if the GSM module is plugged just next to the CPU module). | ||
| - | |||
| - | <note> | ||
| - | Discovery report file ''/tmp/sys_startup_status.json'' lists all modules and their position / slot number | ||
| - | </note> | ||
| - | |||
| - | == QMI == | ||
| - | |||
| - | A command line tool called //qmicli// is available to provide a large set of services such as: | ||
| - | |||
| - | * Get IMEI:<code bash> | ||
| - | qmicli -d /dev/cdc-wdm0 --dms-get-ids | ||
| - | </code> | ||
| - | |||
| - | * Get information on attached session:<code bash> | ||
| - | qmicli -d /dev/cdc-wdm0 --nas-get-serving-system | ||
| - | </code> | ||
| - | * List //qmicli// services:<code bash> | ||
| - | qmicli --help-all | ||
| - | </code> | ||
| - | |||
| - | ==== GSM firmware upgrade ==== | ||
| - | |||
| - | Depending on the region, the gateways are shipped with different types of GSM modules (Sierra wireless MC7354, MC7304 and MC7430). | ||
| - | |||
| - | By default, these modules contain a generic firmware. Even though this generic firmware is sufficient to properly work with most operators, Sierra Wireless supplies a list of operators approved firmwares. | ||
| - | |||
| - | Refer to Sierra Wireless or to the operators to get further information about these firmwares and to know in which case they are required. | ||
| - | |||
| - | To simplify the firmware upgrades on Wirnet iBTS, Kerlink provides //.ipk// packages that automatically install the firmwares. Check your modem version before using one of these ipk. | ||
| - | |||
| - | These packages are available in the [[wiki:resources|resources]] page. | ||
| - | |||
| - | To determine the GSM module type on a gateway, use the following command: | ||
| - | <code bash> | ||
| - | $ grep Model /tmp/sys_startup_status.json | ||
| - | "Model": "MC7304", | ||
| - | </code> | ||
| - | |||
| - | To determine which GSM module firmware is currently installed, use the following command: | ||
| - | <code bash> | ||
| - | $ grep radio_sw_version /tmp/sys_startup_status.json | ||
| - | "radio_sw_version": "9999999_9902574_SWI9X15C_05.05.58.00_00_GENNA-UMTS_005.025_002", | ||
| - | </code> | ||
| - | |||
| - | To trigger the update, first check the module version of the gateway and make sure it is compatible with the firmware you want to install. Then follow the instruction of the [[wiki:sw_updates|software updates]] page. The update takes about 5 minutes. | ||
| - | |||
| - | A successful upgrade should display this kind of trace: | ||
| - | <code> | ||
| - | original firmware revision was: | ||
| - | SWI9X15C_05.05.58.00 r27038 carmd-fwbuild1 2015/03/04 21:30:23 | ||
| - | image 'modem': unique id '005.026_000', build id '05.05.58.00_GENEU-4G' | ||
| - | image 'pri': unique id '005.026_000', build id '05.05.58.00_GENEU-4G' | ||
| - | |||
| - | new firmware revision is: | ||
| - | SWI9X15C_05.05.58.00 r27038 carmd-fwbuild1 2015/03/04 21:30:23 | ||
| - | image 'modem': unique id '005.022_000', build id '05.05.58.00_ROGERS' | ||
| - | image 'pri': unique id '005.022_000', build id '05.05.58.00_ROGERS' | ||
| - | </code> | ||
| - | |||
| - | The firmware upgrade happens after the gateway reboot. Therefore, the ''/tmp/sys_startup_status.json'' file is not populated with the right values. If you want to check the version of the firmware without rebooting the gateway first, you need to execute the following command: | ||
| - | |||
| - | <code bash> | ||
| - | $ discoveryScript.py -o /tmp/sys_startup_status.json | ||
| - | </code> | ||
| - | |||
| - | |||
| - | ===== Network monitoring ===== | ||
| - | |||
| - | Kerlink provides two scripts to monitor the network (only one can be used at the same time): | ||
| - | * networkmonitoring.py: This script is self-sufficient. It is used to monitor/repair the default route (it regularly pings an IP). | ||
| - | * fixnetwork.py: This script is designed to be called by a customer application. It is used to repair multiple interfaces at the same time. | ||
| - | |||
| - | ====fixnetwork.py==== | ||
| - | |||
| - | This script has been designed to be called by client applications that monitor different network links.\\ | ||
| - | Client applications should send monitored links status to the script each time the status is refreshed. The script will then take actions to fix defective links.\\ | ||
| - | |||
| - | Since this script is used to monitor multiple links at the same time, in most cases, it is up to the client application to choose which link should be used (instead of relying on the default route). | ||
| - | |||
| - | This script uses a configuration file (''/etc/network/fixnetwork.conf'') describing what actions and when this actions should be taken. | ||
| - | |||
| - | This script uses LOG_LOCAL2 Syslog facility to output logs. By default, the traces are written in ''/var/log/networkmonitoring.log'' | ||
| - | |||
| - | |||
| - | === Script Usage === | ||
| - | <code> | ||
| - | root@klk-lpbs-0504B4:/user/test # fixnetwork.py -h | ||
| - | Usage: /usr/bin/fixnetwork.py [OPTION] device1HwPos,connectionState,durationSinceLastOk .... deviceXHwPos,connectionState,durationSinceLastOk | ||
| - | With: | ||
| - | deviceXHwPos can be: | ||
| - | gsmmodemXSlot-modemXPosition for a GSM modem inside a WAN module with: | ||
| - | modemXSlot: module slot number (1 to n) | ||
| - | modemXPosition: 1 for mono WAN modules, 1 or 2 for Dual WAN modules | ||
| - | extusb: device must be the only modem plugged on external USB | ||
| - | cable0: device is POE/LAN ethernet on iBTS | ||
| - | cable1: device is Local ethernet on iBTS, or ethernet on iFemtoCell | ||
| - | wifi: device is wifi device (on iFemtoCell only) | ||
| - | connectionState: OK (last applicative ping using this device was OK) or KO (applicative ping KO or not done because no corresponding interface exists) | ||
| - | durationSinceLastOk: error duration in seconds (since last successful applicative ping or first applicative ping) | ||
| - | Options are: | ||
| - | -h: display help | ||
| - | -f confFile: give configuration file. Default is /etc/network/fixnetwork.conf | ||
| - | | ||
| - | Given information on network links to monitor, this script will take actions to try to bring monitored links up. | ||
| - | Actions can be: connection restart, device hardware reset, board reboot, ... | ||
| - | Example: | ||
| - | /usr/bin/fixnetwork.py gsm1-1,OK,0 gsm1-2,KO,50 cable0,KO,3400 | ||
| - | means: | ||
| - | - connection on modem 1 on slot 1 is OK | ||
| - | - connection on modem 2 on slot 1 is KO since 50s | ||
| - | - connection on POE/LAN device is KO since 3400s | ||
| - | </code> | ||
| - | |||
| - | ===reporting network links status=== | ||
| - | |||
| - | * Each time the script is called, all monitored network link status must be given to the script. Otherwise, unwanted behaviours could occur. For example, if only GSM status is reported (KO), whereas Ethernet is properly working, ConnMan could be restarted, which would stop Ethernet from working for a short period of time. | ||
| - | * Script execution can be long (if an action is taken). When no action is taken (normal case), script execution is less than one second long, when actions are taken, it can take up to 20 seconds per monitored link. | ||
| - | * The script will take a maximum of one action per failing monitored link per script call. | ||
| - | * The parameters are case sensitive, use ''OK'' not ''ok'' | ||
| - | |||
| - | ===configuration file=== | ||
| - | |||
| - | Configuration file example with default values. | ||
| - | |||
| - | <code bash> | ||
| - | [general] | ||
| - | # Log level: | ||
| - | # - 0: No messages | ||
| - | # - 1: Messages every time an action is taken | ||
| - | # - 2: Messages every time a monitored connection status changes | ||
| - | # - 3: Messages every time script is called | ||
| - | # - 4 or more: Script debugging, many messages | ||
| - | # default is 1 | ||
| - | log_level=1 | ||
| - | |||
| - | [onelinkactions] | ||
| - | # These actions are done when a link is down during a given amount of time. | ||
| - | # If parameter is 0, corresponding action will never be taken. | ||
| - | # Number of seconds before reconnecting service (using connman command). Default is 30. | ||
| - | error_duration_before_service_reconnect=30 | ||
| - | # Number of seconds before device hw reset (if possible for this device) | ||
| - | error_duration_before_device_hw_reset=90 | ||
| - | # Number of seconds before reconnecting service (using connman command). Default is 150. | ||
| - | error_duration_before_service_reconnect_2=150 | ||
| - | # Number of seconds before actions are retried. | ||
| - | # If not 0, this parameter should be more than all other action parameters | ||
| - | error_duration_before_action_retry=300 | ||
| - | |||
| - | [alllinksactions] | ||
| - | # These actions are done when all links are down during a given amount of time. | ||
| - | # Number of seconds before restarting Ofono and Connman servers. Default is 50. | ||
| - | error_duration_before_servers_restart=50 | ||
| - | # Number of seconds before restarting Ofono and Connman servers and devices hardware. Default is 200 | ||
| - | error_duration_before_network_hardware_reboot=200 | ||
| - | # Number of seconds before restarting board. Default is 0. | ||
| - | # If not 0, this parameter should be more than all other action parameters | ||
| - | error_duration_before_board_reboot=0 | ||
| - | # Number of seconds before actions are retried. | ||
| - | # If not 0, this parameter should be more than all other action parameters | ||
| - | error_duration_before_action_retry=400 | ||
| - | </code> | ||
| - | |||
| - | In sections ''[onelinkactions]'' and ''[alllinksactions]'', error duration of any action must be 0 (action will never be executed) or greater than previous action error duration. \\ | ||
| - | |||
| - | ''error_duration_before_action_retry'' is not a real action. It is used to re-execute all actions (for one link or for all links) after a certain error duration. | ||
| - | |||
| - | |||
| - | ===Actions execution=== | ||
| - | |||
| - | All actions described in the configuration have an "error duration" parameter. If this parameter is 0, corresponding action will never occur. | ||
| - | Otherwise, durations must be interpreted this way: | ||
| - | * First action: the action will be taken when the monitored link is reported down for a time greater than this parameter. | ||
| - | * Other actions: other actions are only taken if the time elapsed since the previous action is greater or equal than the action error duration minus the previous error duration (eg: (error_duration_2 = 90) - (error_duration_1 = 30) = 60s). The aim is to give the time to the script to finish its actions before doing something else. For example, asking the modem to reset could be useless, if the associated ConnMan service is under reconnection. | ||
| - | * Each time the monitored link status is back to OK, then reported once again as KO, the scripts restarts to the first action. | ||
| - | |||
| - | Hereunder is the configuration file that will be used to illustrate a execution cycle: | ||
| - | <code> | ||
| - | error_duration_action_1=30 | ||
| - | error_duration_action_2=90 | ||
| - | error_duration_action_3=150 | ||
| - | error_duration_action_4=300 | ||
| - | </code> | ||
| - | |||
| - | Example of execution cycle: | ||
| - | <code> | ||
| - | t0: GSM link stops working | ||
| - | |||
| - | t0+25: first call to fixnetwork | ||
| - | fixnetwork.py cable0,OK,0 gsm1-1,KO,25 | ||
| - | => no action executed | ||
| - | |||
| - | t0+60: | ||
| - | fixnetwork.py cable0,OK,0 gsm1-1,KO,60 | ||
| - | => action 1 executed (40s since first error report) | ||
| - | |||
| - | t0+95: | ||
| - | fixnetwork.py cable0,OK,0 gsm1-1,KO,95 | ||
| - | => no action executed (only 35s since first action execution) | ||
| - | |||
| - | t0+130: | ||
| - | fixnetwork.py cable0,OK,0 gsm1-1,KO,130 | ||
| - | => action 2 executed (65s since first action execution) | ||
| - | |||
| - | ... | ||
| - | |||
| - | t1: GSM link starts working | ||
| - | fixnetwork.py cable0,OK,0 gsm1-1,OK,0 | ||
| - | => link is up | ||
| - | |||
| - | t2: GSM link stops working | ||
| - | fixnetwork.py cable0,OK,0 gsm1-1,KO,40 | ||
| - | => action 1 executed (link is said to be down since 40s) | ||
| - | </code> | ||
| - | |||
| - | Second example of execution cycle: | ||
| - | <code> | ||
| - | t0: GSM link stops working | ||
| - | |||
| - | t0+35: | ||
| - | fixnetwork.py cable0,OK,0 gsm1-1,KO,35 | ||
| - | => onelinkaction action 1 executed on GSM (35s since first error report) | ||
| - | |||
| - | t0+40: Ethernet link also stops working | ||
| - | |||
| - | t0+100: | ||
| - | fixnetwork.py cable0,OK,60 gsm1-1,KO,100 | ||
| - | => alllinksactions action 1 executed (60s since eth0 down and 100s since GSM down) | ||
| - | |||
| - | t0+120: eth0 starts working again | ||
| - | |||
| - | t0+135: | ||
| - | fixnetwork.py cable0,OK,15 gsm1-1,KO,135 | ||
| - | => onelinkaction action 1 executed on GSM (35s since alllinksactions action 1 execution) | ||
| - | </code> | ||
| - | |||
| - | ==== networkmonitoring.py ==== | ||
| - | === Presentation === | ||
| - | This script monitors the network and takes actions to fix it if the connection fails.\\ | ||
| - | Only the default route is monitored by the script. It relies on ConnMan to define the default route and to mount the network links.\\ | ||
| - | Since ''networkmonitoring.py'' monitors the default route, the client application should use the default route. | ||
| - | |||
| - | Regularly the script will check if it can access a server. The check can be done by: | ||
| - | * ICMP pings to a given server (IP address or DNS name). | ||
| - | * TCP connection to a given server (IP address or DNS name) and port. | ||
| - | |||
| - | Once a check fails, monitoring is done every 10 seconds. Actions are taken after a certain amount of consecutive failed attempt to receive an answer from the monitored server. | ||
| - | |||
| - | Taken actions when check fails are: | ||
| - | * Restarting ConnMan service corresponding to network default route (if any). | ||
| - | * Restarting ConnMan, oFono daemons | ||
| - | * Hardware reboot of all WAN modules and ethernet phy. | ||
| - | * Reboot board. | ||
| - | |||
| - | === Configuration === | ||
| - | The behavior of the script is defined in the ''/etc/network/networkmonitoring.conf'' file. | ||
| - | This script uses LOG_LOCAL2 Syslog facility to output logs. By default, the traces are written in ''/var/log/networkmonitoring.log''. | ||
| - | |||
| - | Here is a commented example of configuration file: | ||
| - | <code> | ||
| - | [general] | ||
| - | # Monitor network. 0 means no monitoring. This is the default value. | ||
| - | monitor_network=0 | ||
| - | # Number of seconds to wait before first check. Default: 60 | ||
| - | first_check_delay=60 | ||
| - | # Interval in seconds between two monitoring when network is OK. Default: 1200 | ||
| - | check_interval=1200 | ||
| - | # Log level: | ||
| - | # - 0: No messages | ||
| - | # - 1: Messages every time an action is taken | ||
| - | # - 2: Messages every time monitoring fails | ||
| - | # - 3: Messages every time monitoring is done | ||
| - | # - 4 or more: Script debugging, many messages | ||
| - | # default is 0 | ||
| - | log_level=0 | ||
| - | # monitor_external_usb (since firmware v3.3): | ||
| - | # - 0: external usb is not monitored (no reset of external USB port), default | ||
| - | # - 1: external usb is monitored (external USB port is reset whith all WAN modules when needed) | ||
| - | monitor_external_usb=0 | ||
| - | |||
| - | [ping] | ||
| - | # Server used to check if network is up or not. It can be an Ip adress or a name. Default: 8.8.8.8 | ||
| - | server=8.8.8.8 | ||
| - | #server="google.com" | ||
| - | # Protocol used to check if server is reachable. Possible values are : | ||
| - | # - ping: will send ICMP ping to given server. Port is useless | ||
| - | # - tcp: will try to connect to given server on given port | ||
| - | #Default is ping | ||
| - | protocol=ping | ||
| - | # Port on which ping is done. Default is 80. | ||
| - | port=80 | ||
| - | # Timeout in seconds before saying we failed to connect to monitored server. | ||
| - | # Default is 5 | ||
| - | timeout=5 | ||
| - | |||
| - | [actions] | ||
| - | # Once network failure is detected, ping is done each 10s. | ||
| - | # Actions is taken after a number of consecutive failure. | ||
| - | # If parameter is 0, corresponding action will never be taken. | ||
| - | # Number of failed ping before reconnecting service (using connman command). Default is 3. | ||
| - | ping_error_before_service_reconnect=3 | ||
| - | # Number of failed ping before restarting Ofono and Connman servers. Default is 5. | ||
| - | ping_error_before_servers_restart=5 | ||
| - | # Number of failed ping before restarting Ofono and Connman servers and eth and modems hardware. Default is 10 | ||
| - | ping_error_before_network_hardware_reboot=10 | ||
| - | # Number of failed ping before restarting board. Default is 20 | ||
| - | # If not 0, this parameter should be more than all other action parameters | ||
| - | ping_error_before_board_reboot=20 | ||
| - | </code> | ||
| - | |||
| - | In most cases, it is advised to use the same server address than the one in ''/etc/network/connman/main.conf''.\\ | ||
| - | In most cases, it is advised to use the LNS address for the monitoring.\\ | ||
| - | It is strongly advised to check if the ping to the server is working before doing the modification in the configuration file. | ||
| - | |||
| - | If ''ping_error_before_board_reboot''= 0, then there will be no board reboot. Once all actions will be finished, the script will stop. | ||
| - | It means that without reboot, no more actions will be taken. When disabling the reboot of ''networkmonitoring.py'', it is expected that the reboot comes from the user's application. | ||
| - | |||
| - | === actions execution === | ||
| - | |||
| - | Since the behaviour of ConnMan and ''networkmonitoring.py'' is a bit complicated, an example of classical network failure is described in this section. | ||
| - | |||
| - | Hereunder is the configuration of ConnMan and ''networkmonitoring.py'' used in this example (without comment) | ||
| - | |||
| - | <code /etc/network/connman/main.conf> | ||
| - | [General] | ||
| - | DefaultAutoConnectTechnologies = ethernet, cellular | ||
| - | PreferredTechnologies = ethernet, cellular | ||
| - | EnableOnlineCheck = true | ||
| - | OnlineCheckUseConnmanHeaders = false | ||
| - | OnlineCheckServerIpV4Url = http://myServer123456.com | ||
| - | </code> | ||
| - | |||
| - | <code /etc/network/networkmonitoring.conf> | ||
| - | [general] | ||
| - | monitor_network=1 | ||
| - | first_check_delay=30 | ||
| - | check_interval=1200 | ||
| - | log_level=1 | ||
| - | monitor_external_usb=0 | ||
| - | [ping] | ||
| - | server=myServer123456.com | ||
| - | protocol=ping | ||
| - | port=80 | ||
| - | timeout=5 | ||
| - | [actions] | ||
| - | ping_error_before_service_reconnect=3 | ||
| - | ping_error_before_servers_restart=5 | ||
| - | ping_error_before_network_hardware_reboot=10 | ||
| - | ping_error_before_board_reboot=20 | ||
| - | </code> | ||
| - | |||
| - | **example:** | ||
| - | |||
| - | * Initial state: | ||
| - | * the gateway has an ethernet connection (eth0) and cellular modem (ppp0 not shown by ifconfig) ready to be used. | ||
| - | * The default route is ethernet and this route can access the server | ||
| - | |||
| - | * The connection to the server is lost (network problem on eth0) | ||
| - | * The script detects the problem | ||
| - | * The default service is restarted | ||
| - | * ConnMan detects another service (ppp0) with an access to the server | ||
| - | * This service becomes the default one | ||
| - | |||
| - | * The network problem on eth0 disappears | ||
| - | * The default route stays on ppp0 (Since ''networkmonitoring.py'' monitors the default route and the default route is properly working, no action is taken) | ||
| - | |||
| - | * The connection to the server is lost (network problem on ppp0) | ||
| - | * The script detects the problem | ||
| - | * The default service is restarted | ||
| - | * ConnMan detects another service (eth0) with an access to the server | ||
| - | * This service becomes the default one | ||
| - | |||
| - | ===== Network Manager ===== | ||
| - | |||
| - | ==== Networking configuration ===== | ||
| - | |||
| - | The ''/etc/default/networking'' file allow user to choose the network manager: | ||
| - | |||
| - | <code bash /etc/default/networking> | ||
| - | # We use connman by default; uncomment to activate ifupdown | ||
| - | #NETWORK_MANAGER=ifupdown | ||
| - | </code> | ||
| - | |||
| - | By default, the line is commented, meaning that ConnMan is used to manage the network. If this line is uncommented and ConnMan turned off (reboot or ''/etc/init.d/connman stop''), the interfaces management is configured by ifupdown. | ||
| - | |||
| - | ==== Interfaces configuration ==== | ||
| - | |||
| - | This means that the interfaces have to be configured through ''/etc/network/interfaces'', are brought down using ''ifdown <interface>'' and up using ''ifup <interface>''. | ||
| - | |||
| - | This is an example for static IP addressing for ''eth0'': | ||
| - | |||
| - | <code bash /etc/network/interfaces> | ||
| - | # /etc/network/interfaces -- configuration file for ifup(8), ifdown(8) | ||
| - | |||
| - | # --- other interfaces omitted for brevity | ||
| - | |||
| - | # Wired or wireless interfaces | ||
| - | auto eth0 | ||
| - | iface eth0 inet static | ||
| - | address 192.168.0.95 | ||
| - | netmask 255.255.255.0 | ||
| - | gateway 192.168.0.254 | ||
| - | network 192.168.0.0 | ||
| - | </code> | ||
| - | |||
| - | Bring up the interface: | ||
| - | |||
| - | <code bash> | ||
| - | ifup eth0 | ||
| - | </code> | ||
wiki/backhaul.1537956181.txt.gz · Last modified: 2019/01/17 10:01 (external edit)
