Information on Alternative Network Connection Types
==============================================================================
Contents:
0. Setting up WLAN/USB adapters
1. General information about PPP connections using PPPd
2. GPRS/EDGE connections using USB connected mobile phones with CDC-ACM driver
3. High Speed 3G/UMTS/CDMA USB modems
4. Analog modems and other RS232 devices (using additional PL2303 based USB to Serial converter)
5. PPPoE (PPP over Ethernet) using built-in LAN adapter
6. Additional notes on PPP connections
0. Setting up Wi-Fi/USB adapters
==============================================================================
0.0 This image supports the WLAN/USB devices based on the following Ralink chipsets: RT2870 and RT3070. The actual devices built with those chips are numerous and can be found inside many well known adapters produced by D-Link, Linksys, Netgear, Belkin and others. Here is a non-exhaustive list of the verified devices:
D-Link DWA-125 (A1/A2)
D-Link DWA-140 (B1/B2)
D-Link DWA-160 B1
Linksys WUSB-100N v2
SMC EZ Connection N
TP-Link TL-WN727N (v1.3/v2.0)
Edimax EW-7711U*N
0.1 The connection setup is performed by editing two configuration files (or just one in case you want to use DHCP): /var/etc/Wireless/RT*STA/RT*STA.dat and /var/interfaces_wlan. The following procedure should be performed only once, during initial setup. All the commands described below should be executed via Telnet. Connect your WLAN adapter to the USB port and run the command:
iwconfig
You should see several network interfaces, including the following (the keyword is wlan0):
wlan0 RT2870 Wireless ESSID:""
Mode:Auto Frequency=2.412 GHz
Link Quality=10/100 Signal level:0 dBm Noise level:-143 dBm
Rx invalid nwid:0 Rx invalid crypt:0 Rx invalid frag:0
Tx excessive retries:0 Invalid misc:0 Missed beacon:0
The above output means that there has been a new wireless device created called wlan0 and that your WLAN adapter based on the RT2870 chipset has been recognised. Keep the chipset name in mind (it follows "wlan0" label in the output) as it will be required for the next step. If the the chipset name is not shown (happens for some devices from time to time) you can execute the following command: lsmod. That should display all of the currently loaded kernel modules and you should be able to get the the chipset name from that output (rt2870 or rt3070).
0.2 Locate the directory inside /var/etc/Wireless which matches the chipset name you've just obtained. Inside that directory there will be a similarly named file with a .dat extension. For instance, in this example the file will be called /var/etc/Wireless/RT2870STA/RT2870STA.dat. That file is an ordinary text file that should can edited using a standard Unix compatible plain text editor. You must put your wireless network settings into this file. The absolute minimum for WPA or WPA2 encrypted connection is:
SSID=Your-Acces-Point-SSID
AuthMode=OPEN | SHARED | WEPAUTO | WPAPSK | WPA2PSK | WPANONE (pick one, see below for detailed description)
EncrypType=NONE | WEP | TKIP | AES (self-explanatory, pick one)
WPAPSK=Pre-Shared-Key (if required)
AuthMode can be one of the following:
OPEN no encryption
SHARED shared key (basically, WEP encryption)
WEPAUTO automatic change between OPEN and SHARED
WPAPSK WPA mode with pre-shared key
WPA2PSK WPA2PSK mode with pre-shared key
WPANONE WPA with pre-shared key in AdHoc mode
0.3 You can skip this step if you want to use DHCP settings for your wireless interface, otherwise you need to edit the file /var/interfaces_wlan. You should specify the IP configuration for the wlan0 interface in this file as follows (change the values that suit your network):
iface wlan0 inet static
address 192.168.1.25
netmask 255.255.255.0
gateway 192.168.1.1
If you want to use DHCP again, just put the following into this file:
iface wlan0 inet dhcp
0.4 Try bringing up the interface using the following command:
ifup -i /var/interfaces_wlan wlan0
If everything works fine (check the configuration with ipaddr, ifconfig, iwconfig, etc.), then you do not need to do anything else and the next time you reboot your receiver the wireless connection will be established automatically.
1. General information about PPP connections using PPPd
==============================================================================
1.0 All the connection methods described in the rest of this document make use of the PPP protocol and PPPd service which has been made available on Cuberevo for the first time ever by the PGI team. The difference between these connection types is only in the commands that will be sent to your modem device and in some PPPd settings.
1.1 In addition to the PPPd service, the PGI image contains full support for iptables, i.e. Linux firewall, which (if configured the right way) allows to protect the receiver from external attacks that can become a reality once the receiver is directly connected to the Internet. iptables also allow things like Internet connection sharing using NAT and masquerading, although you should keep in mind the hardware and software limitations as well as the fact that you will have to configure iptables yourself for such purposes.
1.2 It should be made clear that this document is NOT a complete guide to PPPd and iptables. The ultimate configuration will most likely be different for each user. All the information "missing" in this document can be easily found on the Internet. This document serves just one purpose: to explain where all of the configuration parts are located and the general approach to configuring various PPP connection types. The details can then be tailored by users to suit their needs.
1.3 The minimum requirement for all types of PPP connection (except PPPoE) is to establish a SERIAL LINK between the receiver and your "modem device" (no matter whether it is an old-school dial-up modem or the latest HSDPA/3G device). Since the built-in RS232 port is used for debugging (and is not available at all on 91HD) the only feasible way is to use the receiver's USB port. To turn the USB port into a serial communication device a special driver is required (depending on the connected device type), so ultimately, the PPP connection requires a USB connected device which has driver support for Cuberevo. The procedure to find out whether your modem device is supported by Cuberevo is described below in the relevant section. The PPPoE connection does not require any special drivers as it uses the built in LAN interface and all the necessary drivers are already a part of the PGI image.
1.4 If your USB port is already being used (for instance, by a storage device) and you want to connect a second device to it, you can try using good quality USB 2.0 hub, ideally a powered hub with its own power source.
1.5 After you have successfully set up your PPP connection as described below you can set the PPP parameter in pgi.conf and the connection will be established automatically every time the receiver is restarted. It is possible to control the PPP connection using the scripts menu plugin (available via the WWW button on the remote by default, except 91HD where this menu can be called via the OSD plug-in menu -> script plugin). Finally, you can enable "on-demand connection" (using already supplied templates in the /var/etc/ppp/peers directory) where connection will be established only when there is a need for it (and will be terminated automatically after period of inactivity).
2. GPRS/EDGE connections using USB connected mobile phones with CDC-ACM driver
==============================================================================
2.0 The cdc-acm.ko Linux kernel driver is supplied with the image to enable support for certain mobile phones with a USB interface and CDC-ACM standard support. There is no exhaustive list of the supported phone models, but there is a very good chance for many older Nokia phones that use the CA-53 (and similar) data cable. All steps described below should be performed only once during the initial setup. All the commands should be executed via Telnet.
2.1 Connect your phone using a compatible USB data cable and type the following command: dmesg
If the last lines of the output contain the output similar to the following:
cdc_acm: no version magic, tainting kernel.
drivers/usb/class/cdc-acm.c: Ignoring extra header, type -3, length 4
cdc_acm 2-1:1.1: ttyACM0: USB ACM device
usbcore: registered new driver cdc_acm
drivers/usb/class/cdc-acm.c: v0.25:USB Abstract Control Model driver for USB modems and ISDN adapters
then the phone has been detected with the cdc-acm driver and the chances of getting a connection are very good. In any case, you have to see the message about "ttyACM...: USB ACM device".
2.2 Check if the ttyACM device has been created using the following command: ls -ls /dev/ttyACM*
crw-rw---- 1 root root 166, 0 Mar 18 10:34 /dev/ttyACM0
If the output is similar to the above (there can be more than one device with the ttyACM name), then everything is going well. Otherwise there is a problem with the device compatibility.
2.3 Now that we have a serial device for communication with the phone the PPPd service can make use it. PPPd related configuration is contained in several files. A special chat-script is one of them. It contains the modem "AT-commands" sent to the modem to establish the required connection. The actual chat-script can be located anywhere on the system but it is good practice to keep it in the directory /var/etc/ppp/chats, already allocated for this purpose. There are already several "out of the box" templates in this directory. One of them is called gprs.chat and can be used as a template for GPRS connections. Most likely it will have to be modified to fit your Internet provider settings (as a bare minimum you need to change the Access Point name set by default to "internet").
2.4 Sometimes you will have to change more commands in the chat file, depending on your phone model and ISP settings. It is advisable to search for your particular settings on the Internet as they are most likely already have been described by somebody else. It is also possible to use the "picocom" utility supplied with PGI images to check your modem configuration and to test various AT commands. Picocom allows sending AT commands directly to your modem via the serial device and displaying modem replies. In fact it is possible to fully control your modem using this utility. Start your modem session as follows: "picocom -c /dev/ttyACM0" (with local echo) or "picocom /dev/ttyACM0" (without local echo). To exit picocom session press CTRL+A immediately followed by CTRL+Q. Once the session is established you can try various AT commands to display or set your modem parameters. For instance, AT&V should display all possible commands and settings, while ATI should show manufacturer information/IMEI, etc. More commands can be seen here:
http://en.wikipedia.org/wiki/Hayes_command_set#GSM , however, most manufacturers have their own custom AT commands which allow configuring additional parameters (see 3.1 below, for example).
2.5 Once the chat script is ready the actual PPPd configuration file, also known as the "peer" file, needs to be created. This file MUST reside in the /var/etc/ppp/peers directory. During PPPd start the file name is used as the parameter and most of the PPPd settings will be read from there. The settings include the chat script name (from 2.3 above), the serial interface speed, and importantly, the serial device name (from 2.2 above). If you have several /dev/ttyACM* devices, you have to try them in turn to see which one is really the one you want. There already exists a template called /var/etc/ppp/peers/gprs that contains some typical settings for GPRS connection. Some ISPs may require a user name and password to be supplied. You have to use the additional settings in the peers file as well as to modify the chap-secrets or pap-secrets file located in /var/etc/ppp/, although the standard practice is not to use any logins for GPRS connections. Additional information on the peer file options can be found on the Internet. Also it is worth checking Linux man-pages for PPPd.
2.6 Now you can test the connection by launching PPPd with the following command:
pppd call
&
where is the name of the file from /var/etc/ppp/peers directory (step 2.5).
If all the settings are correct, then there should be some activity on your phone related to creating a GPRS connection. The Telnet session should then have some output similar to the following:
[PGI ~]$ pppd call gprs &
Script /sbin/chat -v -f /var/etc/ppp/chats/gprs.chat finished (pid 1287), status = 0x0
Serial connection established.
using channel 2
Using interface ppp0
Connect: ppp0 <--> /dev/ttyACM0
Warning - secret file /etc/ppp/pap-secrets has world and/or group access
sent [LCP ConfReq id=0x1 ]
rcvd [LCP ConfRej id=0x1 ]
sent [LCP ConfReq id=0x2 ]
rcvd [LCP ConfAck id=0x2 ]
rcvd [LCP ConfReq id=0x0 ]
No auth is possible
sent [LCP ConfRej id=0x0 ]
rcvd [LCP ConfReq id=0x1 ]
sent [LCP ConfAck id=0x1 ]
sent [IPCP ConfReq id=0x1 ]
rcvd [IPCP ConfReq id=0x0 ]
sent [IPCP ConfAck id=0x0 ]
rcvd [IPCP ConfNak id=0x1 ]
sent [IPCP ConfReq id=0x2 ]
rcvd [IPCP ConfAck id=0x2 ]
Script /etc/ppp/ip-pre-up started (pid 1291)
Script /etc/ppp/ip-pre-up finished (pid 1291), status = 0x0
local IP address x.x.x.x
remote IP address y.y.y.y
primary DNS address z.z.z.z
secondary DNS address z.z.z.z
You can verify your new IP configuration by using standard commands such as "ip address", etc.:
ip address
ppp0: mtu 1500 qdisc pfifo_fast qlen 3
link/ppp
inet x.x.x.x peer y.y.y.y/32 scope global ppp0
where x.x.x.x is your newly obtained external IP address.
To watch the PPP traffic you can use the following command: pppstats -w1 (press CTRL+C to stop)
To disconnect an active PPP connection use the command: killall pppd
2.7 If all works OK and you are happy with the connection, you can enable the option to start a connection automatically every time the receiver is powered on. To enable this option you have to specify the peer file name (from /var/etc/ppp/peers directory) in pgi.conf (PPP parameter). For the example above, the parameter will be as follows: PPP="gprs". Don't forget about the possibility to manually control PPP connections (see 1.5 above)
3. High Speed 3G/CDMA/HSDPA USB modems
==============================================================================
3.0 All in all, setting up the PPPd service to work with the high-speed USB modems is no different at all to the procedure for setting up a GPRS connection (described above in section 2). There is, however, slightly more work required to get the serial device initially recognised. The problem with many of the existing high-speed USB modems comes from their hardware feature designed for Windows OS. This feature is known as Zero-CD and works as follows. When you connect your USB modem to a PC for the first time, it presents itself not as a real modem but as a storage device which contains (Windows) drivers and some additional (Windows) software. After you install these drivers, the behaviour changes. Now every time you connect this modem to the same system, the already-installed (Windows) drivers automatically change the device operation mode from "storage device" to "data", so that the actual modem functionality can be used. This works OK in Windows, but does not work at all (or very poorly) in Linux. Linux kernel will see devices such as a CD-ROM or flash media.
You can easily check if your modem is one of such "double-standards" devices. Connect the device to the receiver's USB port and type the following command in the Telnet session: dmesg
If the output looks similar to the following (in this example a Toshiba G450 USB 3G modem is used):
usb 2-1: new full speed USB device using ST40-ohci and address 3
usb 2-1: configuration #1 chosen from 1 choice
scsi2 : SCSI emulation for USB Mass Storage devices
usb-storage: device found at X
usb-storage: waiting for device to settle before scanning
Vendor: Toshiba Model: Rev: X.XX
Type: CD-ROM ANSI SCSI revision: XX
usb-storage: device scan complete
The above output means that the modem has the Zero-CD feature and has been recognised by the kernel as a CD-ROM drive so it has to be switched into a modem mode. If, on the other hand, you would see something like the following:
usb 2-1: new full speed USB device using ST40-ohci and address XX
usb 2-1: configuration #1 chosen from 1 choice
... that means that the modem does not need mode switching and most likely will work as is.
3.1 What to do if the modem requires switching its operating mode? It is necessary to point out that some USB modems can be switched into a permanent "data" mode with their own (usually Windows) software. This mode of operation is always preferred, but not many devices support such a feature. You should Google for your specific device behaviour. For example, a lot of Huawei 3G USB modems can be permanently switched with the following AT commands:
Modem only: AT^U2DIAG=0
Modem + CD-ROM: AT^U2DIAG=1
Modem + CD-ROM + Card Reader: AT^U2DIAG=255
Modem + Card Reader: AT^U2DIAG=256
Although, before you can issue such commands your device must already be in the modem-only mode. Therefore, it is likely that you will have to make use of usb_modeswitch utility.
3.2 In all other cases where permanent switching is impossible a usb_modeswitch utility should be used to get the device working in the right mode. The utility has a database of supported devices which it uses during the switching process. If your device requires mode switching, it is important to check whether your device is present in that database. To see your actual device's ID, use "lsusb" command in Telnet. To check if your USB ID is present in the usb_modeswitch database, execute the following Telnet command: ls -1 /usr/share/usb_modeswitch If your ID is NOT in the list of the supported devices then either usb_modeswitch knows nothing about your device or your device does not need mode switching. If your ID is in the list, then there is a relatively good chance that it can be switched into the right mode, although it is never guaranteed to work with all of the listed devices since the older Linux kernel used in this receiver is rather picky about USB communications.
NOTE: The usb_modeswitch database is updated from time to time with new device models and can be found on the usb_modeswitch website ( http://www.draisberghof.de/usb_modeswitch/ ). It is possible to update the usb_modeswitch database on the receiver without the need to install new firmware image. You only need to place the updated files into the /var/etc/usbmodeswitch.d directory.
3.3 If everything is set up correctly, the modem will be switched into the data mode upon the reboot and there will be one or more devices created in the /dev directory. The switch is only successful if there is new device created in /dev called /dev/ttyUSB0 (there may be more than one ttyUSB device for some modems) with an alias device called /dev/gsmmodem. If nothing of this sort happens, the best way to start troubleshooting is to enable usb_modeswitch logging in /var/etc/usb_modeswitch.conf and then check the log files in the /var/log directory (do not forget to reboot every time you change something in the configuration files).
3.4 The rest of the settings for the actual chat-script and PPPd peer config are similar to what is described for a GPRS connection above (steps 2.3 - 2.7) The difference will be in the serial device name (/dev/gsmmodem instead of /dev/ttyACM0) and the port speed (typically 460800 instead of 115200). Most likely some AT-commands in the chat script will have to be changed to enable UMTS/3G mode. There are some templates available for 3G connections in /var/etc/ppp/chats and /var/etc/ppp/peers directories which will have to be modified to suit your situation (see 2.4 above).
3.5 Certain high-speed modems that require SIM cards to function may need their PIN code function deactivated (if possible) using the software supplied with the device. If you do not look after this you may end up with a locked device and will have to use a PUK code to unlock it. Some devices support entering a PIN code via AT-commands. You should check all the required settings via AT commands using the supplied picocom utility (see 2.4 above).
4. Analog modems and other RS232 devices
==============================================================================
4.0 The built-in RS232 port cannot be used for connecting serial devices as it is already being used for debugging and some models like the 91HD do not have it at all. It is possible to turn the receiver's USB port into a standard serial port using a USB-to-Serial converter (sold separately). These adapters are cheap and easy to find online. They are being sold under various names on eBay and other online stores dealing in PC components. The only requirement is that the converter MUST be Prolific PL2303 chipset based (NOT the FTDI chipset!). Thus, using such a device, ANY analog modem (even your ancient dial-up V.xx modem) can be used. Some mobile phones also have RS232 compatible outputs (a few older Siemens models are known to work this way) and can be used to establish GRPS connection.
4.1 Once you have connected your USB-to-Serial converter to the receiver's USB port, execute the following command in a Telnet session: dmesg
You should see output similar to the following:
pl2303: no version magic, tainting kernel.
drivers/usb/serial/usb-serial.c: USB Serial support registered for pl2303
pl2303 2-1:1.0: pl2303 converter detected
usb 2-1: pl2303 converter now attached to ttyUSB0
usbcore: registered new driver pl2303
drivers/usb/serial/pl2303.c: Prolific PL2303 USB to serial adaptor driver
If you see a message like "pl2303 converter now attached to ttyUSB0" it means that your converter has been successfully recognised and a new serial device has been created.
4.2 Check the newly created serial device ttyUSB0 using the following command: ls -ls /dev/ttyUSB*
crw-rw---- 1 root root 188, 0 Mar 18 12:29 /dev/ttyUSB0
4.3 The rest of the configuration is identical to the one described in steps 2.3 - 2.7 above. The difference will be that the serial device name is now not /dev/ttyACM0 but /dev/ttyUSB0 instead. Naturally, you have to adjust the chat-script and the PPPd peer file to suit your connection type.
5. PPPoE (PPP over Ethernet) using built-in LAN adapter
==============================================================================
5.0 There is no need to load any special drivers to enable PPPoE connection for your ISP. All the necessary components have already been installed in the PGI firmware and the existing configuration templates can be used with minimal changes.
5.1 Edit the template called /var/etc/ppp/peers/pppoe. Most likely you will only need to change the "name" parameter to match your PPPoE login name.
5.2 Put your PPPoE connection password into /var/etc/ppp/chap-secrets (just replace the "password" with your own one) in the supplied template.
5.3 Put the peer file name (the file described in 5.1) into pgi.conf, i.e. PPP="pppoe" and restart the receiver. The connection will be established automatically. For manual connection testing you can use the same procedures described in 2.6 above (replace "gprs" with "pppoe" in the pppd command)
5.4 To check for PPPoE concentrators in your LAN you can use a small utility called pppoe-discovery. This is for information only and does not affect any configuration. A sample output with detected access concentrator is shown below:
[PGI ~]$ pppoe-discovery
Access-Concentrator: teleprov009
--------------------------------------------------
AC-Ethernet-Address: 00:10:33:11:ea:26
6. Additional notes on PPP connections
==============================================================================
In this section there are several important notes about using PPP connections with PPPd. They should be studied carefully before you start any troubleshooting.
6.1 Default Route also known as the IP Gateway
Suppose you are connected to your receiver over its LAN interface called eth0, which obviously has its own IP settings. It doesn't matter how the settings were configured (statically or using DHCP), but one of those settings is called the default route, which can point to your Internet router or simply nowhere, depending on how your network is set up. When the PPP connection is established using PPPd, a new network interface called ppp0 is being created. That interface receives some IP configuration (normally, automatically from the ISP). If, during the PPP connection attempt, your system already has a default gateway (which is most likely when at least one network interface is already configured) then the new default gateway sent by your PPP connection provider will simply be ignored. This may lead to a situation where you have successfully connected the PPP interface with a correct IP configuration, but Internet access does not function. That happens because of all your requests are still trying to go over the "old" default route, and not the one proposed to you by your ISP. To avoid such problem, there exists a special script in PGI image, called /var/etc/ppp/ip-pre-up which runs just before the actual PPP interface is brought up (after the connection has already been established). This script does a few other things (see below) but what it also does is delete your current default route (it saves it into a file though). This makes it possible to set up a new default route as soon as you get its value from ISP automatically and the Internet connection will function OK. When the PPP connection is terminated another script called /var/etc/ppp/ip-down runs and automatically restores the previously saved default route. You can use these scripts for any other pre- and post-configuration associated with your PPP connections.
6.2 DNS settings
The situation with DNS settings is almost identical to the one described above in 6.1. Many ISPs send their own DNS settings during the connection phase and once the PPPd service receives them, it creates a file called /var/etc/ppp/resolv.conf with those new settings. The problem is that the file in this location has no effect on the actual system until it is placed directly into the /var directory. The PGI team took care of this in the already mentioned /var/etc/ppp/ip-pre-up and /var/etc/ppp/ip-down scripts, which will do all the dirty work for you. The scripts will copy the new DNS settings into the correct location and will restore the old settings once the PPP connection has been terminated. If your provider does NOT send the DNS settings, you may need to adjust these scripts to set the DNS settings statically or in some other way that fits your situation.
6.3 Working with iptables
Every time a PPP connection is established your receiver will most likely get an external IP on the Internet (also known as public IP). Most ISPs will not do anything special to protect your connection from the outside world, so in 99.9% cases you will end up with a connection that has an external IP address which is COMPLETELY OPEN TO THE OUTSIDE WORLD. The idea of just about anybody in this world being able to control your receiver and its files, as well as use it as a stop-over on the way to compromise the rest of your home network, most likely does not sound very appealing to you! To prevent such incidents and to protect your receiver from the outside world, the PGI team has included full iptables support in their image. In short, iptables can be used as the very effective Linux firewall, although do not expect a fancy GUI for its setup. If you really want to take full advantage of all iptables functionality you have to become a Linux networking specialist. Luckily, PGI provides a very simple, yet effective, set of iptables rules 'out of the box'. These rules are activated using the already mentioned /var/etc/ppp/ip-pre-up script. The rules will reject all INCOMING connections from the ppp0 interface, thus making your receiver invisible on the Internet. The outgoing connections will work OK. The rules are not meant to be final or the best ever - feel free to change them as you see fit.
The iptables abilities do not end here. If configured properly, iptables can be used to enable Internet connection sharing, where your receiver can act as a "router". You can use NAT or masquerading technologies, you can set various logging options or allow certain services through. Although the fine tuning of iptables may require in-depth knowledge and experience, you can find a lot of ready-made iptables rules on the Internet and modify them to suit your own requirements.
Good luck connecting!
PGI Team
אינדקס
