TODO forever when life runs faster than you can afford

Sakis3G: All-in-one script

Notice: This page provides links and instructions referring to an old version of Sakis3G script. Page is still available only for historical reasons. Please visit www.sakis3g.org for latest Sakis3G script version.

Αυτή η σελίδα υπάρχει και στα Ελληνικά.
This page was last updated on 2010/02/24. Latest script version is 0.1.3g released on 2010/02/24.

Introduction

I run multiple personal computers at home. Some of them are normal PCs, some other laptops and netbooks. Some are only used by me, some others by family members. Whoever is on the go, grabs one 3G modem and leaves. Five laptops at home, you suddenly have a modem broken, you contact operator/ISP and you receive an other type of 3G modem. You now have to run through all PCs to set it up. While I was keep getting better and faster into doing it, I could not afford doing it forever.

My pain is "almost" over. I wrote a script that implements what I consider simplest solution for creating 3G connections in a newly installed system.

See more screenshots and videos here.

Contents

• Introduction
  • About | See also: Screenshots and Videos
  • License and Disclaimer | Credits | Contributors
  • Installation procedure for impatient
• Fitness
  • Features
  • Known limitations
  • Supported modems
  • Supported networks | Also read: How to add your own operator
• Installing
  • Installation
    Also read: How to install on Debian, when 3G is the only connection method.
    Also read: Using your bluetooth enabled phone with Sakis3G.
    Also read: Sakis3G as a udev rule.
  • Dependencies
  • File system modifications
• Configuring
• Known problems | Also read: Troubleshooting
• Contributing
• Latest release notes | Also read: Full change log
• F.A.Q.

About

So, this whole page is dedicated to a shell script. This shell script is supposed to work out-of-the-box for establishing a 3G connection with any combination of supported modem/operator. If both your modem and operator are supported, chances are that you can be connected 30 seconds after downloading script. See list of supported modems/operators below. Last legacy version is 0.1.3g (which is too close to earliest version). However, it serves me well.

Notice: This page provides links and instructions referring to an old version of Sakis3G script. Page is still available only for historical reasons. Please visit www.sakis3g.org for latest Sakis3G script version.

My basic requirements were:

1. As less as possible disk size requirements: 337 KB
2. As few as possible third part dependencies: Nothing more than you should need if manually setting up.
3. As fast as possible installation procedure: There is no installation, download and make it executable.
4. As clean as possible installation procedure: No files are installed on your disk. Configuration is embedded. No need for wvdial, pppd, chat, udev, hal, usb_modeswitch configuration files.
5. As good as possible user experience: "sakis3g connect" or "sakis3g disconnect", or no argument at all for having a simple X GUI.

This script comes to fill in the gap of no/partial support to some distributions for using USB modems, or to work around the "clumsy way" others do. While major distributions will gradually find their way into reliably, and in a unified way, support these devices, this script will end-up as a lightweight replacement to NetworkManager/ModemManager bundle, or gnome-ppp/wvdial bundle, or kppp for small footprint distributions.

(Back to contents)

License and Disclaimer

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details:

http://www.gnu.org/licenses/gpl.txt

Above statement includes additional charges you may receive from your operator by using this program, defects to your SIM card including but not limited to being PIN blocked, defects on your hardware, 3G service abuse ban etc. USE WITH CARE. Author has no responsibility for what may happen to you.

Author is not related in any way with any of the companies, being operators or modem manufacturers, other than being a customer to some of them. Logos and trademarks presented in this page belong to their respective owners.

(Back to contents)

Credits

This version is embedded with 1.1.0 version of Usb-ModeSwitch, which itself is made by Josua Dietze, available at:

http://www.draisberghof.de/usb_modeswitch/

under GNU GPL and contains device database as of 2010/02/21. For this reason, you should contact Josua Dietze only when your device is not properly switched. For problems other than that, you should contact Sakis3G author.

Whenever Usb-ModeSwitch or its database gets updated, you should expect an updated version of Sakis3G after a while. If your modem does not get switched (remains in storage mode), you should contact Usb-ModeSwitch forums, at is might be a new device:

http://www.draisberghof.de/usb_modeswitch/bb/

to receive further instructions for troubleshooting. If your modem gets switched, still it does not work, you should contact the author of Sakis3G.

This script is embedded with 1.8 version of 9menu. Source code is available at:

ftp://ftp.freefriends.org/arnold/Source/9menu.shar.gz

9menu is free software, and is Copyright (c) 1994 by David Hogan and
Arnold Robbins. Permission is granted to all sentient beings to use
this software, to make copies of it, and to distribute those copies,
provided that:


(1) the copyright and licence notices are left intact
(2) the recipients are aware that it is free software
(3) any unapproved changes in functionality are either
(i) only distributed as patches
or (ii) distributed as a new program which is not called 9menu
and whose documentation gives credit where it is due
(4) the authors are not held responsible for any defects
or shortcomings in the software, or damages caused by it.


There is no warranty for this software. Have a nice day.


(Back to contents)

Contributors

Following people have contributed in Sakis3G script:

• Dimitrios Tsolakis (wizarddim is the local part, on Greek yahoo)
  Confirmed Huawei E170 modem works with version 0.0.9.
• Jean-Pierre VAISSIERE (jpiebrig-nav is the local part, on French yahoo)
  Confirmed GBC PL68 modem works with version 0.1.2.
  Confirmed version 0.1.2 works with Tigo HR network.
• Josua Dietze (Usb-ModeSwitch author)
  Identified and fixed a regression issue, introduced by 0.1.2, that was preventing correct tty device detection on several (close to all) modems. Proposed fix was included in 0.1.3.

(Back to contents)

Installation procedure for impatient

This shell script only needs to be downloaded and be turned to an executable. Mind dependencies (see below).

Fastest way to install it on a typical Linux system is:

Notice: This page provides links and instructions referring to an old version of Sakis3G script. Page is still available only for historical reasons. Please visit www.sakis3g.org for latest Sakis3G script version.

1. Have a root terminal open.
2. Install dependencies:
   • [Debian GNU/Linux] "apt-get install ppp sharutils".
   • [Ubuntu] "sudo apt-get install ppp sharutils".
   • [openSUSE] "yast -i ppp sharutils".
   • [Mandriva] "urpmi ppp sharutils".
3. If you intend to use it from desktop, also consider:
   • [Debian GNU/Linux] "apt-get install xterm 9menu xosd-bin".
   • [Ubuntu] "sudo apt-get install xterm 9menu xosd-bin".
   • [openSUSE] "yast -i xterm xosd".
   • [Mandriva] "urpmi xterm".
4. Switch to directory you want it installed, e.g. "cd /usr/bin"
5. Download script: "wget 'http://sakis.tel4u.gr/sakis3g/legacy/sakis3g.gz'"
6. Uncompress: "gunzip sakis3g.gz"
7. Make script executable: "chmod +x sakis3g"


Debian GNU/Linux:
apt-get install ppp sharutils xterm 9menu xosd-bin wget
cd /usr/bin
wget 'http://sakis.tel4u.gr/sakis3g/legacy/sakis3g.gz'
gunzip sakis3g.gz
chmod +x sakis3g


Ubuntu:
sudo bash
apt-get install ppp sharutils xterm 9menu xosd-bin wget
cd /usr/bin
wget 'http://sakis.tel4u.gr/sakis3g/legacy/sakis3g.gz'
gunzip sakis3g.gz
chmod +x sakis3g


openSUSE:
yast -i ppp sharutils xterm xosd wget
cd /usr/bin
wget 'http://sakis.tel4u.gr/sakis3g/legacy/sakis3g.gz'
gunzip sakis3g.gz
chmod +x sakis3g


Mandriva:
urpmi ppp sharutils xterm wget
cd /usr/bin
wget 'http://sakis.tel4u.gr/sakis3g/legacy/sakis3g.gz'
gunzip sakis3g.gz
chmod +x sakis3g


Executing it from your desktop, you will be requested to provide root password, in order to setup connection. If you intend using your bluetooth enabled cellular phone as your modem, you also need to install bluez-utils package and properly setup rfcomm communication with phone. Then edit BLUETOOTH_PHONE_rfcomm configuration option within Sakis3G script.

Important: For SIM card safety reasons, this script does its best to only allow exactly 4-digit PIN numbers. If you use a shorter/longer than 4-digits PIN number, it will not work. Plug your SIM card to your cellular phone, and have PIN changed to exactly 4 digits.

Note: Subscribers to resellers of German Vistream (Solomo, GlobalSim etc.) my encounter problems using Sakis3G script since their SIM requires 5-digit PIN numbers.

Important: If 9menu is not available in your system, and your operator offers more than one APN, you need to set FORCE_APN variable for connection to succeed.

(Back to contents)

Features

• Hardware:
  • Automatic detection of modem.
  • Automatic mode switch, if modem is ZeroCD.
  • Supports using a bluetooth enabled cellular phone, as fallback, when no supported modem found.
  • Automatic load/unload of required driver with appropriate arguments.
  • Automatic detection of appropriate modem device node.
• Communication:
  • Able to provide PIN to SIM card if required.
  • Automatic operator detection or manual operator selection to prevent roaming.
  • Detects and drops connections with wrong DNS servers, or forces working DNS servers.
  • Forces pppd peer to be the default gateway.
• Integration:
  • Provides hooking mechanism to execute your own scripts whenever successfully connected.
  • Ready to be used as an init.d script.
  • Ready to be used as a udev rule.
  • Allows each user to provide its own PIN number.
  • Allows hidden system wide PIN to override user settings.
  • Directly calls pppd, or uses wvdial if installed.
  • Updates HAL about modem capabilities.
• Functionality:
  • If modem is not supported by Sakis3G, still it exists in Usb_ModeSwitch device database, default initialization strings are sent to it.
  • If not root already, prompts for root password, or can also use sudo.
  • Able to create desktop shortcut for accelerating daily use.
  • User is presented menu driven interface.
  • If aosd_cat (common on Debian/GNU Linux running EeePCs) or xosd is installed, OSD messages appear on user's X session.

(Back to contents)

Known limitations

• For SIM card safety reasons, this script does its best to only allow exactly 4-digit PIN numbers. If you use a shorter/longer than 4-digits PIN number, it will not work.
• Unpredicted behavior if more than one modem units with identical USB IDs are connected.
• Due to the fundamental requirement that script should change nothing on filesystem(s), it does not store your network configuration prior into getting connected with your 3G/GSM provider. As a result, after being disconnect, it does not revert back /etc/resolv.conf to the configuration prior to making the connection nor it restores your previous default gateway to your routing table. If your existing infrastructure provides DNS servers and gateways from DHCP, you could/should try to disconnect and reconnect to those to get a working setup. If you were not connected to any other network while establishing 3G connection, this limitation does not apply.
• This script does not allow sending SMS and I do not intend to do it in the future.
• This script does not in any way interfere with your iptables configuration and does intend to do it in the future. If you want to manage your iptables configuration, use connection_hook option. As a note, if you encounter problems while sharing (do NAT through) your 3G ppp connection, consider using the following command:
  
iptables -I FORWARD -p tcp --tcp-flags SYN,RST SYN -j TCPMSS --clamp-mss-to-pmtu


(Back to contents)

Supported modems

Notice: This page provides links and instructions referring to an old version of Sakis3G script. Page is still available only for historical reasons. Please visit www.sakis3g.org for latest Sakis3G script version.

Sakis3G script is able/supposed to work with most 3G modems, being USB or even bluetooth. Modems are used with default initialization commands which are (supposed to be) working with most of them. However, some of them indeed require special handling to establish a (reliable) connection. If Sakis3G script is unable to automatically identify your modem, will ask you to indicate it. There are only two ways that Sakis3G script can automatically identify your modem, so don't panic if it does not:

1. Your modem is indeed one of those "weird modems" that need special handling and Sakis3G knows how to handle it.
2. Your modem is a known ZeroCD modem that exists within Usb-ModeSwitch device database. Sakis3G will have a look at that database before reporting failure to detect it.

As it turns out, if your modem is not automatically detected, possibly it just means that its not "weird" in any way, or it is just a too recent "weird" modem.

Modems below are confirmed to be working with Sakis3G:

1. Alcatel One touch X200
2. GBC PL68
3. Huawei Ε170, E220, E230, E270, E870 (Experimental)
4. ZTE MF636

If your modem is not working with default settings, please consider following trouble shooting guide. If it still does not work, email me output when running it with DEBUG variable set and I will have an updated version released immediately after.
(Back to contents)

Supported networks

Notice: This page provides links and instructions referring to an old version of Sakis3G script. Page is still available only for historical reasons. Please visit www.sakis3g.org for latest Sakis3G script version.

Sakis3G script, currently supports major networks across 39 countries. Detailed information available here.

Note: Some operators offer multiple APNs. Choosing the wrong APN, may even trigger additional (roaming) costs. If using 9menu interface, you will be prompted to select the correct one anytime you attempt to connect. If not using 9menu interface, you need to supply FORCE_APN variable.

Additional operators can be supported if provided with:

1. Name and Network ID of operator.
2. PDP context (that is AT+CGDCONT arguments).
3. Username and password (if required by operator).
4. Phone number that should be called.

You can find list of supported operators of your version by calling "sakis3g help". Instructions for adding your own operator can be found here.

(Back to contents)

Installation

While installing this script is indeed a matter of downloading and switching to executable, there are some dependencies that need to be resolved. Installation procedure described below refers to Debian GNU/Linux Lenny. Other distribution users may have to work out with package names used by their distribution.

Notice: This page provides links and instructions referring to an old version of Sakis3G script. Page is still available only for historical reasons. Please visit www.sakis3g.org for latest Sakis3G script version.

1. Install pppd and chat. They are used for contacting modem and establishing a DATA connection with your operator. This script will refuse to work if they are not installed.
   
apt-get install ppp

2. If your modem needs mode switch, this script will utilize the embedded 1.1.0 version of Usb-ModeSwitch to switch it. Script will need uudecode, available from package sharutils, to decode embedded binary.
   
apt-get install sharutils

3. If you are going to use this script from your desktop, xterm must (if not already) be installed. It is used by script to prompt you for PIN if SIM card requires it, and to display connection log if configured to do so.
   
apt-get install xterm

   You may optionally add either menu driven interface, or OSD (On-Screen-Display) messages.
   • To add menu driven interface, install 9menu, (if on i386 architect, you can rely on "sharutils" for script to use its own 9menu version).
     
apt-get install 9menu

   • To add fancy OSD messages, install aosd_cat or xosd-bin.
     
apt-get install aosd_cat


apt-get install xosd-bin


   If both 9menu and aosd_cat/xosd are installed, 9menu is automatically used. This preference can be changed in configuration. If both 9menu and xosd are installed, 9menu is used to present UI and xosd to display progress information if VERBOSE variable is set.

4. If you intend using your bluetooth enabled cellular phone as a backup modem, you need bluez-utils.
   
apt-get install bluez-utils

5. Download and install script.
   • Switch to directory you want it installed
     
cd /usr/bin

   • Download script
     
wget "http://sakis.tel4u.gr/sakis3g/legacy/sakis3g.gz"

   • Uncompress
     
gunzip sakis3g.gz

   • Fix script permissions.
     
chown root:dialout sakis3g
chmod 750 sakis3g

   • If you are going to use this script along with alwayssudo configuration option, you need to setup sudo. Type:
     
visudo

     Go at the end of file and add line:
     
%dialout ALL=(root) NOPASSWD: /usr/bin/sakis3g

     Press Ctrl+X, answer Yes.
   • Add users that should be able to use create 3G connections to dialout group.
     
adduser john dialout


(Back to contents)

Dependencies

If you need to install this script to a distribution other than Debian, you should be aware of its detailed dependencies:

• "/bin/sh" as it is a shell script.
• Various common utils that should anyway be available, such as: head, tail, cat, cut, wc, echo, printf, read, test, setsid, getent, ps, which, sort, uniq.
• The following super user utils: lsusb, modprobe, netstat, route.
• "chat" for negotiating with modem (supply PIN, manual operator selection etc).
• "pppd" for establishing ppp connection.
• "wget" for receiving operator icons from the internet.
• If you want to use this script from your desktop, the following are required:
  • "xterm" for user to supply PIN if required, and for showing wvdial/pppd console if requested by configuration,
  • "gksu"/"kdesu" (or plain "su" at worst case) is required unless option alwayssudo is specified, in which case "sudo" is required instead for getting root priviledges.
• If you want to use this script from your desktop, the following are recommended:
  • "9menu" or "aosd_cat" or "osd_cat".
• If you execute this script from a terminal, the following are required:
  • "su" or "sudo" for getting root priviledges.
• If your modem needs switching, the following are also required:
  • "uudecode" for decoding embedded Usb-ModeSwitch binary,
  • "libusb" for Usb-ModeSwitch to work.
• "wvdial" is NOT required. However, if it is installed, "wvdial" is by default used instead of directly calling pppd. Can be reverted back to directly using pppd by configuring.
• "rfcomm" if you intend using your bluetooth phone as modem.

(Back to contents)

File system modifications

Apart what files you may optionally create to hold PIN information, this script will create the following files on your file system, by itself:

• .3gnet inside calling user's home directory.
• Various files inside your /tmp directory, which are purged upon successful operation.
• /etc/ppp/peers/sakis3g while ppp negotiation is taking place.

Only $HOME/.3gnet and /tmp/sakis3g.3gnet should persist when this script is not running.

(Back to contents)

Known problems

Known problems should be fixed when I find time.

• If you use this script with 9menu interface for several connect/disconnect sessions without closing it, its memory footprint, process tree and CPU usage increase due to recursive shell calls. Upon connection, is safe to select "Close". Connection is not dropped.
• Unpredictable behaviour if /dev/tty* devices already exist from other devices attached, or from two modems connected at the same time, and they are both on the same USB bus, and HAL is not available. Issue "lsusb -t" to review what else devices exists on the same USB bus. You may try to connect your modem to another USB port to workaround this issue.
• Due to embedding a pre-compiled Usb_ModeSwitch binary for i386 architect, modems attached to architects other than i386/amd64 are not mode switched.
• If output method is xosd and font defined by XOSDFONT configuration variable does not exist, nothing appears on X screen, just an ABORT message on terminal. Use "xfontsel" to contruct a valid font string for your system.

(Back to contents)

Contributing

If you contribute in any way to this script, please, make sure you inform me whether you want your name and/or email, be written in next version or not. If you don't specify, I will include it by default.

I am interested for:

• Reports of success/failure on other distributions.
• More operators' information.
• More modems' information.
• Patches that should fix/accelerate functionality.
• More ideas. However, I cannot guarantee that I will be able to fulfil your expectations.

(Back to contents)

Latest release notes


Full Sakis3G change log is available here.

0.1.3g	2010/02/24
Upgraded to Usb-ModeSwitch device database that was released on 2010/02/21.
0.1.3f	2010/02/14
Added support for 85 networks across 25 counties.
0.1.3e	2010/02/11
Script now utilizes modems that while not advertising their GSM capabilities, they still provide their IMEI number (which indicates GSM functionality).
0.1.3d	2010/02/10
Added support for operators in Belgium, Luxembourg and Netherlands. Updated Vodafone (GR) APNs.
0.1.3c	2010/02/07
Added support for operators in Cyprus, France and Spain. Better KDE4 integration.
0.1.3b	2010/02/05
Upgraded to Usb-ModeSwitch device database that was released on 2010/02/03. Fixed several issues.
0.1.3	2010/02/04
This version is an "emergency" release which fixes regression issues introduced by 0.1.2. Improved udev integration. Added logposition configuration variable which indicates log file that should be used when running as a udev rule. Fixed the following issues: Josua Dietze provided a bug report and a patch for serial device autodetection procedure which fixes a regression issue, introduced by 0.1.2, preventing many modems from having their correct tty device chosen. Fixed a regression issue, introduced by 0.1.2, which required a modem to be connected even when executing with the "help" argument. When first using script, 9menu interface does not any more appear as "Unnamed window".
0.1.2	2010/02/01
Added better serial tty detection. This method will allow more unknown modems to work. User is now notified if tty device is occupied by another process. This will help users understand whether their modemmanager is messing with their ports. Added support for user defined modems. To use a user defined modem, USBMODEM variable must contain USB IDs in "XXXX:XXXX" hex form. If a specific driver is also required, USBDRIVER variable can be used and should contain the module required to be loaded. When no known/switched modem is found, and USBMODEM variable is not set, 9menu users are presented a list of currently connected USB devices to choose their modem from. An embedded 9menu binary is now included in script, utilized on i386 distributions that do not offer 9menu. Script now works flawlessly on LiveCD images that do not provide writable home directories. Added support for the following operators: 70401: Claro (Guatemala) 70402: Tigo (Guatemala) Added support for modem 1c9e:f000 GBC PL68. Fixed the following issues: Drastically improved workflow to avoid executing same things twice or more. Overral operation is now faster. Does not any more randomly pickup a modem when more than one modems are available. 9menu users are provided a list of modems to choose from. OSD and command line users must provide its name or USB IDs as an extra command line argument. Argument must be long enough to distinguish just one modem. If two ZTE modems are connected, then doing "sakis3g connect ZTE" will fail, while "sakis3g connect MF636" will work (if they are not both of the same model). If more than one modems are connected, does not any more silently proceed with second one, if first one failed to connect for whatever reason. Fixed a long existing issue preventing some switchable devices from being properly switched. Was providing wrong configuration file to Usb-ModeSwitch. Affected devices are a subset of devices with IDs: 05c6:1000 and 19d2:2000. Setting stick_to_console does not any more imply alwayssudo. You must explicitly set alwayssudo for sudo to be used. Added copyright notices.

(Back to contents)