This page provides detailed instructions and hints for installing Sakis3G script on GuruPlug devices running manufacturer pre-installed "armel" port of Debian GNU/Linux 5.0 (Lenny).

• If you intend using Sakis3G script on an architect other than a GuruPlug system, you should refer to official Sakis3G wiki for instructions on installation and recompilation.
• If you are running another one distribution on your GuruPlug system, you may still find this one page useful. Moreover, since you made it into performing this transition, I will be assuming you are also capable to translate steps described to your own distribution's taste.

This guide may initially look frightening long. This is to ensure everything is written in detail and to minimize skill required. Experienced users are expected to have finished within 15 minutes. No more.

Going through the end will allow you to setup your GuruPlug as a wireless router for your 3G/UMTS/GPRS connection, even without requiring your intervention for getting connected.

See it on video

Introduction

GuruPlug is embossed with "The Power To Connect" moto on its front side. This statement is not much far away from reality, given the connectivity options offered by:

• 1x or 2x (depending on model) Gbit Ethernet port(s),
• 802.11b/g WiFi adapter (working in Access Point mode as well), and
• embedded Bluetooth™ adapter.

Beyond already built-in equipment, connectivity options can be further expanded through available USB 2.0 ports. Using those ports, one can attach additional networking devices, ranging from LAN and WAN adapters to USB-2-USB connections.

While stock kernel, shipped with device, might not offer widest variety of modules available within Linux kernel's tree, it still provides enough for establishing a 3G/UMTS/GPRS data connection through USB and Bluetooth™ modems and mobile phones.

This page provides instructions for setting up 3G/UMTS/GPRS connections, on GuruPlugs, using Sakis3G script.

Table of contents

1. Hardware requirements
2. Software dependencies
3. Installing Sakis3G script
   1. Over network
   2. Using a USB disk
4. Configuring Sakis3G script
   1. Determine configuration
   2. USB modem
   3. With a Bluetooth modem
   4. Optional configuration
      1. Use those LEDs for something
      2. Make sure pppd is used
      3. Max out connection speed
      4. Help it stay online
5. Automatic connection upon device attachment
   1. Persist over power outage
6. Sharing internet connection

Hardware requirements

In order to implement instructions described below you need three things:

1. A GuruPlug device in a bootable state (that is, not bricked).
2. A 3G/UMTS/GPRS modem/mobile phone, either a USB or a Bluetooth™ one.
3. A way to transfer a single file (Sakis3G script) to your GuruPlug device:
   • An internet connection, or
   • a USB disk for temporarily storing it.

A JTAG board is not required for any one of the steps illustrated below.

(Back to contents)

Software dependencies

Pre-installed Debian Lenny installation already provides everything required, for using Sakis3G script. You need to install no additional packages.

(Back to contents)

Installing Sakis3G script

You can still download and install Sakis3G script, using generic installation instructions outlined on www.sakis3g.org and official Sakis3G wiki: it is possible, and will perfectly work.

However, you can avoid installing development environment, for recompiling it for the armel architect, by downloading and installing GuruPlug precompiled version available from current page.

Current page outlines following methods, for you to select applicable one, for installing Sakis3G script on GuruPlug:

• Install over an internet connection, if available, or
• transfer it by using a USB disk, if not.

(Back to contents)

Installing Sakis3G script/ Over network

If you can find your way out, into providing your GuruPlug with an internet connection, you can use commands below for downloading and installing GuruPlug precompiled version of Sakis3G script. If your GuruPlug has no internet access, you can still use a USB disk for installing.

cd /usr/bin
wget "http://www.sakis3g.org/versions/latest/guruplug/sakis3g.gz"
echo "6c88a9961ba8861f2f668c178c02403f  sakis3g.gz" | md5sum -c
gunzip sakis3g.gz
chmod +x sakis3g

A complete download, should display following text after md5sum -c command:

sakis3g.gz: OK

Whereas an invalid/interrupted download will instead display (if your download was interrupted, you need to abort and repeat procedure):

sakis3g.gz: FAILED
md5sum: WARNING: 1 of 1 computed checksum did NOT match

If you have successfully complete this step, you can skip to configuration section.

(Back to contents)

Installing Sakis3G script/ Using a USB disk

If there is no way (other than 3G modem) for your GuruPlug to gain internet access, you can still store GuruPlug precompiled version of Sakis3G script on a USB disk, and then have that USB disk plugged on your GuruPlug.

Follow these steps:

Step #1: Plug your USB disk on a computer having internet access (e.g. the one you are reading this page right now from).

Step #2: Navigate once more to current page (http://www.sakis3g.org/guruplug.html#usbdisk).

Step #3: Right click on this link and select "Save Link/Target as...".

Step #4: Select root directory of USB disk as download's destination.

Step #5: After download is complete, unmount (or "Safely remove") USB disk from computer.

Step #6: Plug USB disk on GuruPlug.

Step #7: Issue following commands:

cd /usr/bin
cp /media/usb/sakis3g.gz .
echo "6c88a9961ba8861f2f668c178c02403f  sakis3g.gz" | md5sum -c
gunzip sakis3g.gz
chmod +x sakis3g

A complete download, should display following text after md5sum -c command:

sakis3g.gz: OK

Whereas an invalid/interrupted download will instead display (if your download was interrupted, you need to abort and repeat procedure):

sakis3g.gz: FAILED
md5sum: WARNING: 1 of 1 computed checksum did NOT match

If everything worked properly, you can continue with next step.

(Back to contents)

Configuring Sakis3G script

Configuring Sakis3G script is not required. Sakis3G script is capable to get you connected out-of-the-box (with no configuration at all), thanks to a wide variety of auto detection methods.

Information unable to be automatically determined, will end up being requested from user instead. Common such details include:

• PIN number your SIM card might need,
• correct APN to use, according to your data plan/contract type with your operator or,
• if your operator is not found within list of known operators, about APN, APN username and password required for establishing connection. This information is, usually, easily acquired by calling your operator's customer support hotline.

Sole reason behind configuring Sakis3G is to avoid providing answers, over and over, against the exact same questions. Since GuruPlug lacks usual input/output equipment (i.e. keyboard and monitor), establishing a proper configuration is highly recommended. This will minimize/eliminate feedback required, for establishing connection in the future.

(Back to contents)

Configuring Sakis3G script/ Determining configuration

Sakis3G script, during each startup, checks whether file /etc/sakis3g.conf exists. Before going scared, be pleased to know that Sakis3G script will help you determine required configuration. There is no need to go through Sakis3G manual and learn about all those configuration variables.

Sakis3G will be asking you questions (as few as possible), rather than failing lacking your feedback. In the end, you will end up being connected, and whatever configuration required, for avoiding answering same questions again, will be suggested to you.

Procedure varies slightly, depending on your modem's type:

• USB modem or mobile phone,
• Bluetooth modem or mobile phone.

(Back to contents)

Configuring Sakis3G script/ USB modem

In order to determine /etc/sakis3g.conf contents, when using a USB modem, you need to plug modem and then invoke Sakis3G script like this:

# sakis3g --interactive --nostorage connect state

In my case, all I was requested to provide a value for, had been:

• My PIN number, which refers to SIM_PIN variable, and,
• correct APN to be used, which refers to APN variable,

So all I have to do is (if you were asked more questions, you should include those as well):

echo "nostorage" >> /etc/sakis3g.conf
echo "SIM_PIN=1491" >> /etc/sakis3g.conf
echo "APN=\"gint.b-online.gr\"" >> /etc/sakis3g.conf

You may wonder about nostorage switch we've been using so far. Some kernel versions, including those supplied with GuruPlug, tend to reset USB modem whenever their storage part (their embedded Card Reader facility) is not working as expected. Supplying nostorage switch to Sakis3G script, instructs it to eliminate storage part of USB modem (also rendering Card Reader part of USB modem unusable). This way, USB device reset is less likely to happen.

Let's now test configuration. Unplug modem out of GuruPlug and reinsert it. If all have gone well, Sakis3G should ask nothing this time.

Try connecting, by specifying connect argument only:

# sakis3g connect
HSPA Data Card connected to WIND GR (20210).
#

In case configuration supplied had been enough, script should connect without implications. Should a question arise, have that answered (and later include it within configuration file) as well, and try again.

(Back to contents)

Configuring Sakis3G script/ With a Bluetooth modem

Before invoking Sakis3G script, you should make sure:

• Your Bluetooth modem is in discoverable state, and
• Bluetooth stack on GuruPlug is running:

  # /etc/init.d/bluetooth start

In order to determine /etc/sakis3g.conf contents, when wishing to use a Bluetooth modem or phone, you need to invoke Sakis3G script like this:

# sakis3g --interactive MODEM=OTHER OTHER=BLUETOOTH connect state

Script will then take you through a series of screens for setting up your connection with your Bluetooth device. During those steps, your Bluetooth device will be contacted several times. You should take the chance and set GuruPlug as a "Trusted device" on your phone.

Each screen represents a question you need to answer. For each one of those questions, a variable needs to be set within configuration file. For the time being, just go on and provide answers through those screens.

Slideshow below illustrates the series of questions I answered when attempting to connect through my Bluetooth enabled phone.

Of all variables and switches proposed, I only supplied those highlighted:

To automatically repeat result of last action, use following command line:
/usr/bin/sakis3g connect --pppd OTHER="BLUETOOTH" MODEM="OTHER"
APN="internet.vodafone.gr" APN_USER="user" APN_PASS="pass"
RFCOMM_TTY="/dev/rfcomm2" RFSERVICE="1" RFCHANNEL="1"
BLUETOOTH="00:25:44:44:44:44"

In order to both accelerate things, and cease the need for Bluetooth device being discoverable, we will do some changes:

• We will load contents of BLUETOOTH variable on UNDISCOVERABLE variable, and on BLUETOOTH variable we will instead place word "UNDISCOVERABLE", and
• will use variable RFCHANNEL as well, and will instead place word "RFCHANNEL" on RFSERVICE variable.

These all changes will prevent scanning devices within range and services available on our Bluetooth device in future connection attempts.

Let's now apply configuration on file /etc/sakis3g.conf:

echo "MODEM=OTHER" >> /etc/sakis3g.conf
echo "OTHER=BLUETOOTH" >> /etc/sakis3g.conf
echo "BLUETOOTH=UNDISCOVERABLE" >> /etc/sakis3g.conf
echo "UNDISCOVERABLE=\"00:25:44:44:44:44\"" >> /etc/sakis3g.conf
echo "RFSERVICE=RFCHANNEL" >> /etc/sakis3g.conf
echo "RFCHANNEL=1" >> /etc/sakis3g.conf
echo "APN=\"internet.vodafone.gr\"" >> /etc/sakis3g.conf

Connecting and disconnecting, regardless of mobile phone being discoverable or not, should now just be a matter of:

# sakis3g connect
Nokia 6500s-1 connected to vodafone GR (20205).
#

# sakis3g disconnect
Disconnected.
#

(Back to contents)

Configuring Sakis3G script/ Optional configuration

This paragraph suggests optional configuration one can use to improve experience when using Sakis3G script. It is not required that follow steps below, however I recommend that you do it.

Use those LEDs for something

Starting from version 0.2.0d, Sakis3G script provides --guruplug switch.

Using this switch, Sakis3G will be using LEDs available on GuruPlug for indicating success, error and progress indication:

• Success is indicated by both LEDs blinking green for 5 seconds.
• An error is indicated by both LEDs blinking red for 5 seconds.
• Progress is indicated by both LEDs being green, while they swap which one blinks whenever progress is advanced.
• If a step is persisted/retried (i.e. while waiting for modem to register network) blinking led gets a red background.
• Sakis3G script will restore LEDs, on the state they had been before being invoked, upon exit.

echo "guruplug" >> /etc/sakis3g.conf

Make sure pppd is used

Sakis3G is able to use both pppd and wvdial as a back-end for establishing connection. When wvdial is found within PATH, it is used by default. When is not, pppd is used directly.

GuruPlug, by default, does not come with wvdial installed. But if you have it manually installed it will be used. Connecting through wvdial, which in-turn connects through pppd is both useless and painful for resource-limited GuruPlug.

You can enforce use of pppd by using --pppd switch:

echo "pppd" >> /etc/sakis3g.conf

Max out connection speed

Sakis3G, by default, uses 460800 bps for connecting. This value should be safe for anyone, but definitely not the maximum one can achieve. You can start experimenting with various higher values, until you locate maximum one your pppd version, modem and operator allow connecting with.

Use BAUD variable. Example assumes you have already configured Sakis3G and no additional arguments are required:

# sakis3g connect BAUD=7200000
# sakis3g disconnect

Try with those values (or with even greater than this) until you encounter maximum one working:

• 7200000
• 5760000
• 4000000
• 3500000
• 3000000
• 2500000
• 2000000
• 1500000
• 1152000
• 1000000
• 921600
• 576000
• 500000

When you have determined maximum value which can be used, you should as well include it on configuration file (replacing XXXXXXX with that value):

echo "BAUD=XXXXXXX" >> /etc/sakis3g.conf

Help it stay online

Some modems (and some operators) tend to interrupt a running connection after a certain period of inactivity. This one attitude can be both annoying and frustrating when you are used into the always-on concept DSL lines offer.

If you are sure (see warning above) you need to prevent it from happening, there is a way to generate dummy traffic through Sakis3G configuration. Bad news is that method will be generating additional CPU load.

Append your /etc/sakis3g.conf file with the following line:

echo "CONNECTION_HOOK=\"killall ping; ping -i 3 8.8.8.8 &\"" >> /etc/sakis3g.conf

This will result into pinging Google DNS server every 3 seconds. Eventually fooling, whoever had been interrupting connection, into considering it active.

(Back to contents)

Automatic connection upon device attachment

Instead having to first login on GuruPlug, for invoking Sakis3G, you can configure GuruPlug to automatically trigger Sakis3G upon physical connection of your modem. This way, connecting through your USB modem, will be just a matter of physically connecting and disconnecting modem (enabling use of GuruPlug LEDs can assist into providing feedback of what is going on).

Sakis3G script can help you with this one too. Do those steps:

1. Unplug USB modem (Doing so is important),
2. Replug USB modem,
3. Use these commands:

   # sakis3g connect udevrule | \
   > grep "^ACTION" >> /etc/udev/rules.d/10-sakis3g.rules
   # udevadm control --reload_rules

   File /etc/udev/rules.d/10-sakis3g.conf should contain your own equivalent of this one:

   ACTION=="add", SUBSYSTEM=="usb", ATTRS{idVendor}=="1bbb", ATTRS{idProduct}=="f000", ATTRS{bInterfaceNumber}=="00", RUN+="/usr/bin/sakis3g connect --pppd --googledns --guruplug APN=gint.b-online.gr APN_USER=web APN_PASS=web SIM_PIN=1491 USBDRIVER=option MODEM=OTHER OTHER=USBMODEM USBMODEM=1bbb:f000 BAUD=4000000"

Now test it. Experiment by plugging and unplugging your modem onto GuruPlug.

Persist over power outage

Now that you've made it automatically connecting upon physical connection and disconnection of device, you may find out that connection is not restored after GuruPlug has recovered from a power outage. Reason is udev rules never producing the "add" event.

Sakis3G is able to recognize and interpret usual "start" and "stop" arguments passed by init scripts. All you have to do is symlink it within appropriate runlevel's init scripts. Whenever a Linux system is started, is directed to enter a specific runlevel. On Debian systems, this runlevel is "2". To make sure this is your case as well, issue following command:

# runlevel
N 2

Navigate on appropriate runlevel's "run-parts" directory and symlink Sakis3G script:

# cd /etc/rc2.d/
# ln -s /usr/bin/sakis3g S99sakis3g

Keep your modem plugged, and instruct GuruPlug to reboot. Connection should come up after GuruPlug has finished booting.

# reboot

(Back to contents)

Sharing internet connection

Copy and paste following text within your terminal. This will create file /etc/ppp/ip-up.d/0002share and set execution flag for it. Whenever a P-t-P connection is initiated, netfilter configuration of GuruPlug will be set for allowing internet access to anyone able to reach GuruPlug (by wired or wireless means).

cat <<endl > /etc/ppp/ip-up.d/0002share
#!/bin/sh -e

IPTABLES="/sbin/iptables"

# Determine ppp interface
pppinterface="\$1"
[ "a\${pppinterface}" = "a" ] && pppinterface="\${IFNAME}"
[ "a\${pppinterface}" = "a" ] && pppinterface=\`/sbin/ifconfig ppp | grep "^ppp" | head -1 | cut "-d " -f1\`
[ "a\${pppinterface}" = "a" ] && exit 0

# Determine the rest of the interfaces
internalinterfaces=\`/sbin/ifconfig -a | grep -v "^ " | grep -v "^ppp" | cut "-d " -f1\`

# Load required modules
modprobe ip_tables; modprobe ip_conntrack

# Delete previous entries
\${IPTABLES} --flush
\${IPTABLES} --table nat --flush
\${IPTABLES} --delete-chain
\${IPTABLES} --table nat --delete-chain

# Default policy for input and output is ACCEPT
# after all, this is just a limited firewall thing.
\${IPTABLES} -P INPUT ACCEPT
\${IPTABLES} -F INPUT
\${IPTABLES} -P OUTPUT ACCEPT
\${IPTABLES} -F OUTPUT

# Default policy for forward is DROP
\${IPTABLES} -P FORWARD DROP
\${IPTABLES} -F FORWARD

# Delete previous NAT rules
\${IPTABLES} -t nat -F

# Workaround required for some operators.
# Uncomment it if computers behind GuruPlug
# are unable to access *some* sites.
# Verified to be required for:
# - GR COSMOTE (20201)
#\${IPTABLES} -I FORWARD -p tcp --tcp-flags SYN,RST SYN -j TCPMSS --clamp-mss-to-pmtu

# Allow masquearading on ppp interface
\${IPTABLES} --table nat --append POSTROUTING --out-interface \${pppinterface} -j MASQUERADE

for i in \${internalinterfaces}
do
         # Allow related connections in
         \${IPTABLES} -A FORWARD -i \${pppinterface} -o \${i} -m state --state ESTABLISHED,RELATED -j ACCEPT
         # Allow internet access to internal interfaces
         \${IPTABLES} --append FORWARD -i \${i} -j ACCEPT
done
# Drop all the rest forward requests from outside world
\${IPTABLES} --append FORWARD --in-interface \${pppinterface} -j DROP

# Set kernel flags
echo 1 > /proc/sys/net/ipv4/ip_forward
echo 1 > /proc/sys/net/ipv4/ip_dynaddr

endl
chmod +x /etc/ppp/ip-up.d/0002share
 

Now reconnect and enjoy your wireless router:

# sakis3g disconnect
# sakis3g connect

(Back to contents)