====== Backhaul configuration ====== ===== Overall network presentation ===== To connect a gateway to a network there are several possible interfaces: * Ethernet * WAN / PPP * WiFi (**Wirnet iFemtoCell only**) {{:images:keros_network_layers_1.0.jpg?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. Cellular 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: * Web interface. * SMS. * RESTAPI. * Editable configuration files. * WiFi Acces-Point (**Wirnet iFemtoCell only**). 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 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 behavior 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. DefaultAutoConnectTechnologies = ethernet, wifi, cellular PreferredTechnologies = ethernet, wifi, cellular 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. NetworkInterfaceBlacklist = ethernet The field value ''wifi'' is a default value for ConnMan. It is simply ignored if no WiFi device is available on the gateway. === 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: # connmanctl services *AO Wired ethernet_7076ff0100b5_cable *AR Orange F cellular_208017001155386_context1 # connmanctl connect cellular_208017001155386_context1 Connected cellular_208017001155386_context1 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 those cases, the check would be negative whereas the LNS is reachable. For those 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: EnableOnlineCheck = true OnlineCheckUseConnmanHeaders = true OnlineCheckServerIpV4Url = http://ipv4.connman.net/online/status.html OnlineCheckServerIpV6Url = http://ipv6.connman.net/online/status.html 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. # curl -vs http://www.google.com/ The check is OK if ''< HTTP/1.x 200 OK'' is displayed * 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 < ... 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. \\ Monitoring of the connection must be done to solve such cases: see [[wiki:network_mana:backhaul#network_monitoring]] === Fallback DNS servers === Fallback DNS server are used if no DNS server is given by DHCP server of a particular service. They can be configure using following parameter: FallbackNameservers = 9.9.9.9,8.8.8.8,1.1.1.1 ==== 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, ConnMan applies automatically the configuration. Executing /etc/init.d/connman restart is not mandatory 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 IPv4 = dhcp to IPv4 = 192.168.1.5/24/192.168.1.1 Where ''192.168.1.5'' will be the new IP address of the Wirnet gateway, ''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: Nameservers = 192.0.2.1,192.0.2.2 ConnMan automatically detects the changes and applies them when the configuration file is closed. === LOCAL Ethernet (Wirnet iBTS only) === 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. ==== WiFi configuration ==== ConnMan’s WiFi (wlan) Ethernet configuration is done via the editable configuration file ''/etc/network/connman/wlan.config''. To manually configure a WiFi network, the fields ''Name'' and ''Passphrase'' must be changed. [global] Name = WLAN Description = WLAN Interface configuration [service_WLAN] Type = wifi IPv4 = dhcp Name = SSID Name Passphrase = 1234passphrase Connman supports multiple WiFi 'services' descriptions. Just add a new 'service' with another name than "service_WLAN". \\ It also supports various type of configuration (static, tls, peap, ...). For further details on ConnMan service configuration, please refer to ConnMan's [[http://git.kernel.org/cgit/network/connman/connman.git/plain/doc/config-format.txt|online documentation]]. === Via WPS feature === The WPS button of the Wirnet iFemtoCell can be used to simply connect the gateway to a WiFi network. * Press the WPS button of your WiFi access point. * Press the WPS button of the Wirnet iFemtoCell. * The association is done between the gateway and the WiFi access point. The WPS button is indicate by a WiFi symbol. \\ {{:images:wps_button.png?150|}} ==== Cellular configuration ==== The Wirnet iFemtoCell cellular modem is an external USB cellular dongle, here a list of several dongles tested in the [[wiki:ifemtocell:cellular_backhaul_ifemto|Cellular backhaul]] page.\\ The other Wirnet gateways cellular modem is an internal modem. \\ These modems provide integrated userland APIs. Cellular configuration is achieved by configuring oFono. Each time a new sim card is used oFono configuration need to be reloaded with Ofono reset command. === 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: * A default APN for all SIM cards can be stored in this file. In this case, the MCC/MNC are not needed. * Multiple APN for multiple SIM card can be stored (using MCC/MNC of the SIM). * A default PIN code for all SIM cards can be stored. * Multiple PIN code for multiple SIM card can be stored (using SIM card ICCID). * 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. A file named ''/etc/network/ofono/default_provisioning'' contains several operators configuration (MCC, MNC, APN) for several countries. \\ If the SIM used is already configured in this file, there is no need of configuring the APN the ''/etc/network/ofono/provisioning''. The PIN code, if set, still needs to be configured in ''/etc/network/ofono/provisioning''. On Wirnet iZeptoCell-Cellular, the APN that must be used is ''bicsapn''. It is pre-configured on this gateway and this configuration should not be changed # Syntax: # ## Default "operator" configuration: #[operator] #internet.AccessPointName= # Mandatory #internet.Username= #internet.Password= #internet.AuthenticationMethod= # chap (default), pap, none #internet.Protocol= # ip (default), ipv6, dual # ## Specific "operator" configuration: #[operator:,] #internet.AccessPointName= # Mandatory #internet.Username= #internet.Password= #internet.AuthenticationMethod= # chap (default), pap, none #internet.Protocol= # ip (default), ipv6, dual # ## Default "sim" configuration: #[sim] #pin= # SIM pin #phone= # PH-SIM pin #firstphone= # PH-FSIM pin #network= # PH-NET pin #netsub= # PH-NETSUB pin #service= # PH-SP pin #corp= # PH-CORP pin # ## Specific "sim" configuration: #[sim:] #pin= # SIM pin #phone= # PH-SIM pin #firstphone= # PH-FSIM pin #network= # PH-NET pin #netsub= # PH-NETSUB pin #service= # PH-SP pin #corp= # PH-CORP pin A list of Mobile Network Code / Mobile Country Code can be found on [[http://mcc-mnc.com/|mcc-mnc.com]]. * If a Roaming SIM card is inserted in the gateway, the **APN** codes to configure should be those ones of the SIM and not those of the local operator. * If needed, please see **SubscriberIdentity** line in gsmdiag.py result to know the **MCC/MNC** of the SIM card (5 first digits). * The **MCC/MNC** to configure is the one of the SIM provider also, not the one of the local operator. 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 file is changed, a service ''reset'' has to be performed. /etc/init.d/ofono reset **Each time the SIM card is changed, a service ''reset'' has to be performed.** === Modem tools === == GSM diagnosis tool == GSM diagnosis tool is a script using oFono interfaces to detect most common problems on cellular modems. It can also be used to have a quick view of cellular modems status on board. It produces information on modem status directly on the console and also a text file ''/tmp/gsmdiag.txt''. Call of script: ''# gsmdiag.py'' Diagnosis output examples: ++++ Modem ready to connect| # gsmdiag.py 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 Diagnostic written in /tmp/gsmdiag.txt ++++ ++++ SIM not detected| # gsmdiag.py Number of modems: 1 [Modem:/quectelqmi_2] Syspath:/sys/devices/soc0/soc/2100000.aips-bus/2184200.usb/ci_hdrc.1/usb2/2-1/2-1.1 HardwarePosition:internal Powered:1 Online:1 Manufacturer:QUALCOMM INCORPORATED Model:QUECTEL Mobile Broadband Module Revision:EG25GGBR07A08M2G [SimProps] Present:0 Error: no SIM in modem (double checked with AT commands) Diagnostic written in /tmp/gsmdiag.txt ++++ ++++ SIM detected but not operational| # gsmdiag.py Number of modems: 1 [Modem:/quectelqmi_1] Syspath:/sys/devices/soc0/soc/2100000.aips-bus/2184200.usb/ci_hdrc.1/usb1/1-1/1-1.1 HardwarePosition:internal Powered:1 Online:1 Manufacturer:QUALCOMM INCORPORATED Model:QUECTEL Mobile Broadband Module Revision:EG25GGBR07A07M2G [SimProps] Present:0 Error: SIM detected (ICCID: 8959102062181454741F) but not usable by Ofono Diagnostic written in /tmp/gsmdiag.txt ++++ ++++ Wrong pin code case| # gsmdiag.py 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, ...) Diagnostic written in /tmp/gsmdiag.txt ++++ == getmodeminfo.py tool == This script displays: * Humanly readable hardware position of a cellular modem: * slot and position in slot * or "extusb" if modem is a dongle (since v3.3) * oFono path of a cellular modem * ConnMan service corresponding to a cellular modem * Network interface corresponding to a cellular 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). # getmodeminfo.py Usage: /usr/bin/getmodeminfo.py [OPTION] Options are: -h get modem info from modem hardware position -h modemslot,modemposition: for modem inside cellular 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 When successful, the output will look like this: #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 == 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. On Wirnet IBTS gateway, serial port to access cellular module //AT// command interface is ''/dev/slot/${SLOTNO}/ttyAT${MODEMNO}'' (speed: 115200), where: * ''$SLOTNO'' is the slot number (''1'' if the cellular module is plugged just next to the CPU module). * ''$MODEMNO'' is the modem number (''1'' for single WAN modules, ''1'' or ''2'' for dual WAN modules). Discovery report file ''/tmp/sys_startup_status.json'' lists all modules and their position / slot number On other gateways with an internal modem, serial port to access cellular module //AT// command interface is ''/dev/ttyAT'' (speed: 115200). It is not possible to send AT commands to external USB dongles used on Wirnet iFemtoCell. * Get IMEI (iStation and iFemtoCell Evolution):echo $'AT+CGSN\r' | microcom /dev/ttyAT # result: root@klk-wiis-xxxxxx:~ # echo $'AT+CGSN\r' | microcom /dev/ttyAT AT+CGSN 86769xxxxxxxxx8 OK == QMI (Wirnet iBTS only) == A command line tool called //qmicli// is available to provide a large set of services such as: * Get IMEI: qmicli -d /dev/cdc-wdm1 --dms-get-ids * Get information on attached session: qmicli -d /dev/cdc-wdm1 --nas-get-serving-system * List //qmicli// services: qmicli --help-all This is only usable on Sierra Wireless modems. ==== Cellular modem firmware upgrade (Wirnet iBTS only) ==== Depending on the region, the gateways are shipped with different types of cellular 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 firmware. Refer to Sierra Wireless or to the operators to get further information about this firmware 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 firmware. Check your modem version before using one of this ipk. These packages are available in the [[wiki:resources:resources|resources]] page. To determine the cellular module type on a gateway, use the following command: $ grep Model /tmp/sys_startup_status.json "Model": "MC7304", To determine which cellular module firmware is currently installed, use the following command: $ 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", 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:keros_custo:sw_updates|software updates]] page. The update takes about 5 minutes. A successful upgrade should display this kind of trace: 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' 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: $ discoveryScript.py -o /tmp/sys_startup_status.json ===== Interface management over web interface ===== See the dedicated page: [[wiki:systeme_mana:webui:#network_configuration|Web interface]]. ===== Interface management through SMS ===== See the dedicated page: [[wiki:systeme_mana:sms#configuration_commands|SMS]]. ===== Interface management through REST API ===== See the dedicated page: [[wiki:systeme_mana:restapi|REST API]]. ===== Network monitoring ===== See the dedicated page: [[wiki:network_mana:networkmonitoring|Network monitoring]]. ===== Network Manager ===== ==== Networking configuration ===== The ''/etc/default/networking'' file allow user to choose the network manager: # We use ConnMan by default; uncomment to activate ifupdown #NETWORK_MANAGER=ifupdown 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 '' and up using ''ifup ''. This is an example for static IP addressing for ''eth0'': # /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 Bring up the interface: ifup eth0 ===== Router Mode ===== ==== Purpose ==== The aim of the router mode is to bring data connection to a sub-network thanks to a connection from a single gateway. Here is an example of how it could be used :\\ {{:images:router_mode.jpg?850|}} ==== Router configuring ==== To activate the router mode on a gateway, some commands need to be made in the gateway console. Here are the commands : # Activate router mode echo "ROUTER=yes" > /etc/default/localnet.conf # Edition of /etc/network/connman/main.conf to disable handling of eth0: NetworkInterfaceBlacklist = vmnet,vboxnet,virbr,ifb,eth1,wlan-adm,usb,eth0 # Add eth0 to localnet handling by adding this line in /etc/udev/rules.d/localnet.rules SUBSYSTEM=="net", KERNEL=="eth0", RUN+="/etc/udev/scripts/localnet.sh" # Make sure this config is saved in case of firmware upgrade echo "/etc/udev/rules.d/localnet.rules" > /etc/sysupgrade.d/localnet.conf These commands need to be made on the gateway which will host the connection only. Nothing has to be done on other gateway(s).\\ A reboot of the gateway is needed to apply this configuration. You can do so with the command ''reboot'' The host gateway can now provide data connection locally to another gateway or to multiple gateways thanks to an ethernet switch. \\ Local connections to the switch can be: * Ethernet and/or * WLAN