UMTSkeeper: keep your UMTS/GPRS/GSM connection alive automatically

by Mintaka

This page is about UMTSkeeper version 1 (BASH version) which is discontinued. Consider upgrading to UMTSkeeper version 2.


umtskeeper screenshot
Screenshot of the UMTSkeeper statistics page (version 1.03).
Click image to enlarge.

Installation

UMTSkeeper uses the Sakis3G script by Sakis Dimopoulos to set up the modem and connect to the net. You can download Sakis3G from the Sakis3G website http://www.sakis3g.org/ (the author of UMTSkeeper is not afiliated with Sakis Dimopoulos). I take the "binary free" version, yet the "full" (including usb_modeswitch) will do as well. Read the manual!
If Sakis' website is down then you can get it from the Internet Archive Wayback Machine: http://web.archive.org/web/*/http://www.sakis3g.org/. There is a (binary free) version available on Sourceforge.net, too: http://downloads.sourceforge.net/project/vim-n4n0/sakis3g.tar.gz (thanks BigCowPi for the link).

I'll do the commands that have to be given as the root user (or superuser, the general linux system administrator), using the sudo program, which asks you for your own password every time and which is the standard way on freshly installed Ubuntu systems. On other systems you may type su to become root. (sidenote: to activate the root account on Ubuntu, define a password for it: sudo passwd)
Also, for packet installation, I will use the apt-get command, which is standard on Debian based distributions (also various flavors of *ubuntu and Raspbian). On other distributions I assume that you are familiar with whatever packet installer it uses (yum etc.).

Prepare

Before you proceed, make sure you have read and understood the license agreement. For your convenience, I made an excerpt. It's not an endless read of tyring legal stuff.

UMTSkeeper and Sakis3G should reside in the same directory. In this example it's /home/mintaka/umtskeeper/ - a subdirectory of my home directory, where mintaka is my user name. Substitute mintaka with your own user name. (Alternatively, you can put it in any location you find suitable). Typing pwd will show you the exact location you are working in which you will need later when you automate things (thanks BigCowPi for simplyfying this procedure).

If you don't yet have internet on your target system, download and transport the files there. The archive contains a "readme" file with these instructions as well.

In a terminal, download and extract both scripts and make them executable (input line-by-line):

cd ~
pwd
mkdir umtskeeper
cd umtskeeper/
wget "http://www.sakis3g.org/versions/latest/binary-free/sakis3g.gz"
gunzip sakis3g.gz
chmod +x sakis3g
wget "http://mintakaconciencia.net/squares/umtskeeper1/src/umtskeeper.tar.gz"
tar -xzvf umtskeeper.tar.gz
chmod +x umtskeeper

Also make sure that your system properly detects the modem. The usual type of modem available will first register as a storage device to the system, containing a Windows executable which installs the modem manager software (on Windows, that is). On Linux, these devices may need to be switched to modem mode with the program usb_modeswitch, which should be available in your packet repositories (try sudo apt-get install usb-modeswitch before you go compile it yourself). There's also a "binary" version available on the Sakis3G website which includes usb_modeswitch. Many modems are pre-configured in usb_modeswitch to work out-of-the-box, so there's no more to be done there. If your modem is not switched automatically then you can find more on configuring usb_modeswitch on the usb_modeswitch site and its forum.

The clever way is to first connect manually with Sakis3G in interactive mode. Sakis3G will give you hints for the options to use. Do it as root:

sudo ./sakis3g --interactive

Hint: if you are asked for APN user or APN password but you have none, enter "0".

Ubuntu users: do not set up an automatic connect with the GNOME network manager because it interferes with Sakis3G. You will likely use a headless machine, therefore the NM will not be useful anyway, so consider to uninstall it. This might apply to other distributions as well, I didn't test. You can still set up your network connections in /etc/network/interfaces. To remove, type sudo apt-get remove network-manager.

First Run

If your connection works in interactive mode, unplug and re-plug your modem and try with UMTSkeeper with all the switches and options, also as root.
For example (this is a single line, mind the quotes!):

sudo ./umtskeeper --sakisoperators "USBINTERFACE='0' OTHER='USBMODEM' USBMODEM='12d1:140c' SIM_PIN='1234' APN='CUSTOM_APN' CUSTOM_APN='provider.com' APN_USER='0' APN_PASS='0'" --sakisswitches "--sudo --console" --devicename 'Huawei' --log --silent --monthstart 8 --nat 'no'

umtskeeper: process not found

First, it tries to kill all running UMTSkeeper instances, therefore the output is process not found (no other UMTSkeeper is active at the time). UMTSkeeper will stay running. To end it, press the key combination CTRL+C.

When run for the first time some log files will be created, among them /var/log/umtskeeper.log (the main log file), umtskeeper.stat.html (HTML statistics file to view in your web browser), and umtskeeper.stat (the file which keeps the numbers for the next run). To view umtskeeper.log, best open a second terminal and use cat or tail to view its content. It should contain something like this:

  1. cat /var/log/umtskeeper.log

  2. 2013-07-23 12:16:05 Start: interval=4*8s
  3. Monthly stats file not found, setting up a new one.
  4. Daily stats file not found, setting up a new one.
  5. Hourly stats file not found, setting up a new one.
  6. Internet status:
  7. Cell network: No modem plugged.
  8. 2013-07-23 12:16:41 Internet connection is DOWN. Calling Sakis3G connect...
  9. Sakis3G cmdLine: nice ./sakis3g connect --sudo --console USBINTERFACE='0' OTHER='USBMODEM' USBMODEM='12d1:140c' SIM_PIN='1234' APN='CUSTOM_APN' CUSTOM_APN='provider.com' APN_USER='0' APN_PASS='0'
  10. Sakis3G says...
  11. E1550 connected to PROVIDER (13579).
  12. 2013-07-23 12:17:14 Testing connection...
  13. 2013-07-23 12:17:24 Success... we are online!
  14. Main stats file not found.
  15. Main stats file is incomplete. This can happen if UMTSkeeper is killed. Trying to load backup file. This can cause slight inacurracies in the statistics.
  16. Main stats file backup not found. Possibly running the first time.

Sidenote: You can watch the log flow by typing tail -f /var/log/umtskeeper.log if you like. End the watch with the key combination CTRL+C.

If you unplug your modem now and re-plug it again then the connection should be established automatically. Give usb_modeswitch and Sakis3G a little patience.

Automatic Start

Last, you want to start UMTSkeeper automatically after boot. Put a line into /etc/rc.local like this (it's a single line which will make it run in the background and redirect screen output to an error.log file): /etc/rc.local has to be edited by the root user. Replace the path /home/mintaka/ in this example by the path you found out previously.

/home/mintaka/umtskeeper/umtskeeper --sakisoperators "USBINTERFACE='0' OTHER='USBMODEM' USBMODEM='12d1:140c' SIM_PIN='1234' APN='CUSTOM_APN' CUSTOM_APN='provider.com' APN_USER='0' APN_PASS='0'" --sakisswitches "--sudo --console" --devicename 'Huawei' --log --silent --monthstart 8 --nat 'no' --htmlpath '/home/www/' &>> /home/mintaka/umtskeeper/error.log &

A line for only logging transfer statistics on wlan0 would for example look like this:

/home/mintaka/umtskeeper/umtskeeper --logonly --log --silent --monthstart 14 --iface 'wlan0' --htmlpath '/home/www/' &>> /home/mintaka/umtskeeper/error.log &

Parameters and Customization

Commands:

--resetmonth
Manually reset the monthly transfer counter.

Options:

--log
Log to file (default: don't log). See also: logfile.
--logonly
Do not connect to internet. Use this for only logging statistics on a connection. Recommended only for (W)LAN devices (default: do connect).
--nostats
Don't write statistics files (default: write them).
--silent
Suppress screen output (default: verbose)

Parameters:

--iface <iface>
Network interface to monitor (default: ppp0).
--nat <iface>
Enable internet connection forwarding (NAT). <iface> is the name of the network adapter that connects to the internet. Often, this is ppp0 (look it up with ifconfig when the connection is up). Set to 'no' if no forwarding is required (default: no).
--interval <s>
Test connection in intervals of s statistics cycles (1 cycle is about 4 seconds) (default: 8).
--logfile "<file>"
To specify an alternative log file (default: /var/log/umtskeeper.log). This implies the option 'log'.
--devicename "<string>"
Set device name (eventually needed for device reset, this should be a unique identifier containing only letters and numbers. Get it with lsusb (don't listen to what Sakis3G says).
Example: lsusb may return the device name string: ZTE WCDMA Technologies MSM MF110/MF627/MF636. Any unique part of this name is ok to take as the device name. So, --devicename "MF636" would be appropriate here.
--statpath "<path>"
Write statistics files to this location. The statpath should not contain space characters. This is recommended if the script is started from an SD card or other flash media (like on the Raspberry Pi), in the case you have an USB HDD attached anyway. Because the stat files are written every few seconds, the writing could cause wear on the flash device - so if you have a USB harddrive connected, better write to that one. Be sure to (auto-)mount the USB HDD before umtskeeper is started (give it an auto-mount entry in /etc/fstab)! (default: script path)
--htmlpath "<path>"
Webserver path to copy the stats HTML file to (default: empty - do not copy)
--limitday <limit>
Set daily transfer limit (in bytes)
--limitmonth <limit>
Set monthly transfer limit (in bytes)
--monthstart <day>
Day of month when monthly count begins. This is typically the day on which your monthly contract starts.
--sakisswitches "<switches>"
Set switches to pass to Sakis3g.
--sakisoperators "<operators>"
Set operators to pass to Sakis3g.

Graph Parameters:

These are more esoteric settings that change the scale of the graphs. You may need to adjust them to your own speeds and habits. In order to change these, open the script in a text editor (starting from line 74 or so).
There are 4 sets of graph settings:

Downloads

Please read the license agreement before you use this program. It won't hurt - for your convenience, I made an excerpt.

Download UMTSkeeper (MD5: 0602666c9a7144132b3af2a09dbbfc1c)
Changelog
Sakis3G website (alternatively from the Wayback Machine)

Links

Further Reading and Acknowledgements

BigCowPi (Andy Thomson) has a great tutorial on turning the Raspberry Pi into a cell network internet gateway and wireless router, using UMTSkeeper/Sakis3G. This should also work with other computers. Also, there is a tutorial about setting up a NAS (network storage) using the RasPi which can be combined with the gateway/router function, and a good collection of other RasPi related stuff. Check out his site.

Many thanks to afraid.org for Free DNS hosting.

References

Sakis3G (alternatively from the Wayback Machine)
usb_modeswitch

License and Disclaimer

This program is released under a double license

Primarily, the Hacktivismo Enhanced-Source Software License Agreement (HESSLA), which can be found in full and with an additional statement about its objectives, at http://www.hacktivismo.com/about/hessla.php;
and for compatibility reasons, the GNU General Public License (GPL), see http://www.gnu.org/licenses/.

While the GPL contains the terms and conditions under which this software and derivative works thereof can be freely distributed, and thus is aimed primarily at software developers, the HESSLA, while granting the same rights and obligations to modify and distribute the software, contains additional terms that govern the use of this software. This makes the HESSLA function as a contract between the author and the user, rather than just being a copyleft agreement.
In particular, the HESSLA contains objectives on security standards (section 9), the adherence of the use of the software to respecting human rights, political freedom and privacy standards (section 10), as well as special terms on the use of the software by governmental entities and governmental persons (section 14).
For the purpose of including this software or portions thereof in GNU GPL licensed projects, this software is also licensed under the GPL. You may distribute this software or derivatives under the GNU GPL, provided that your distribution is also subject to the HESSLA.

The HESSLA

UMTSkeeper is free software: you can redistribute it and/or modify it under the terms of the Hacktivismo Enhanced-Source Software License Agreement (HESSLA) as published by Hacktivismo, either version 1, or prior, of the License, or (at your option) any later version.
By using this software, you express that you read and understood this license agreement, and that you are a Qualified Licensee of the software as laid out in section 0.8 at the time you use this software, meaning that you will not use this software for infringement of human rights or the right for privacy. You will not use this software for surveillance purposes or to otherwise spy on people, neither for doing any harm to a human being.
See the Hacktivismo Enhanced-Source Software License Agreement (HESSLA) at http://www.hacktivismo.com/ for more details.

GNU GPL

UMTSkeeper 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.
See the GNU General Public License for more details: http://www.gnu.org/licenses/gpl.txt

Disclaimer

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.

And this should be common sense:
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. The author of this program or authors of any of its dependencies have no responsibility for what may happen to you.

The 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 mentioned by this package belong to their respective owners.