SAKIS3G(1)

NAME
sakis3g - Manages 3G modems and connections

SYNOPSIS

 sakis3g [ actors ] [ switches ] [ variables ]
 sakis3g disassemble destination
 sakis3g getfile file
 sakis3g ls
 sakis3g usb_modeswitch [ arguments ]
 sakis3g man [ sakis3g | sakis3g.conf | usb_modeswitch ]
 sakis3g version
 sakis3g help

DESCRIPTION

Sakis3G is a shell script which is supposed to work out-of-the-box for establishing a 3G connection with any combination of modem or operator. If you are lucky enough, you may be connected 30 seconds after downloading script.

Sakis3G script is built around some fundamental requirements:

1.  As less as possible disk size requirements.

2.  As few as possible third-party 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 operation: No files are installed/modified on your disk.

5.  No configuration is required: No need for configuring wvdial, pppd, udev, hal or usb_modeswitch.

6.  As good as possible user experience: "sakis3g connect" or "sakis3g disconnect", or no arguments at all for a simple UI to appear.

    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 to gnome-ppp/wvdial bundle, or to kppp for small footprint distributions.

INVOCATION METHODS

[ actors ] [ switches ] [ variables ]
    Using this syntax, you can define:

*   Actions for Sakis3G script to follow, by defining action's corresponding actor.

*   Alter actors' behaviour, by setting switches.

*   Provide values to actors, by using variables.

    You should consult sakis3g.conf(5) for information on switches and variables available. For a list of available actors see below.

disassemble destination
    Extracts Sakis3G embedded package within destination directory and exits.

getfile file
    Extracts file from Sakis3G embedded package and displays it on standard output.

*   Relative path of file is also supported if file is able to uniquely identify file within package.

*   Wildcard characters are not supported.

*   File should exist within Sakis3G embedded package.

ls  Displays contents of Sakis3G embedded package and exits. No further arguments exist, allowing output to be filtered.

usb_modeswitch [ arguments ]
    Provides direct access to the embedded Usb-ModeSwitch binary. Any subsequent command line arguments are passed to Usb-ModeSwitch. Consult usb_modeswitch(1) for a detailed list of acceptable arguments.

man [ sakis3g | sakis3g.conf | usb_modeswitch ]
    Displays one of:

*   sakis3g(1)

*   sakis3g.conf(5)

*   usb_modeswitch(1)

    If no argument is specified, sakis3g(1) is displayed.

version, --version
    Displays Sakis3G script's version and exits.

help, --help
    Displays a minimal help page and exists.

ACTORS

Each actor refers to a specific action Sakis3G script should execute. Many programs provide a similar functionality, allowing to execute a specific action by explicitly defining it through command line. When no actor is defined in command line, behavior depends upon selected user interface. As a general rule, when using an interactive UI, menu actor is implied leading to Main Menu appearing.

CHAINS

Sakis3G script allows defining more than one actors, which altogether form a Chain.

*   An actor may be referenced twice or more within a chain, leading into being executed an equivalent count of times.

*   Whenever an actor is terminated (successfully or not), it sets its result code accordingly.

*   If result code is not 0 (zero), which denotes success, or if no other actor is specified in chain, then Sakis3G script itself terminates, returning result code previously set, as exit status.

*   If result code equals to 0 (zero), next actor in chain is executed.

COMMON ACTORS

connect, start
    Attempts to establish a data connection with operator.

reconnect, restart
    Drops current data connection and, using same connection settings, connects again. Useful when data connection seems stalled (it is still up but no traffic occurs).

disconnect, stop
    Drops all currently running P-t-P connections.

switchonly
    Only switches a USB modem.

recompile
    Recompiles embedded Usb-ModeSwitch version for your system.

status
    Displays connection status.

info
    Displays information about current connection.

report
    Generates a report for providing feedback.

desktop
    Creates a shortcut for Sakis3G script on your desktop.

helper
    Enables Helper mode for script to occupy a slot in notification area.

SPECIAL ACTORS

In order to allow more sophisticated chains there are some special actors available. Special actors never display errors or notifications, allowing to avoid expected error messages:

connected
    Returns 0 (zero) if currently connected.

disconnected
    Returns 0 (zero) if not currently connected.

plugged
    Returns 0 (zero) when a USB modem is currently plugged.

unplugged
    Returns 0 (zero) when no USB modem is currently plugged.

switched
    Returns 0 (zero) when a USB modem is currently plugged, and no switchable modem is detected.

switchable
    Returns 0 (zero) when a switchable modem is detected.

wait, sleep
    Waits for one second and then unconditionally returns 0 (zero). Using this actor as the last one, within a chain, is pointless.

OPERATOR ACTORS

In order to allow even more sophisticated chains, special actors imitating what we usually call unary operators, are also offered:

ignore
    Unconditionally converts result of next actor to 0 (zero), forcing chain to continue traversing.

not Reverses result of next actor.

Note:
    Keep in mind that while "not connected" is equal to "disconnected", you should be cautious when using "not" operator and avoid making false assumptions. As an example, "not switched" is not (always) equivalent to "switchable", and vice versa.

ACTION ACTORS

about
    Displays copyright information about Sakis3G script.

clicked
    When a desktop shortcut is created, this actor is by default placed as argument. It initiates menu actor, unless selected UI is interactive terminal or terminal, in which case it initiates toggle actor. You can later modify desktop shortcut, to explicitly call an actor of your taste instead.

connect, start
    Attempts to establish a data connection with your operator, calling prepare actor if necessary.

desktop
    Attempts to create a shortcut for Sakis3G script on calling user's desktop.

disconnect, stop
    Attempts to terminate all currently running P-t-P connections.

helper
    Forces Sakis3G script to enter Helper mode. This actor prevents the rest of the chain from ever being executed.

info
    Displays information about currently established connection. Fails if invoked while not connected.

menu
    Displays Main Menu of Sakis3G script. Returns:

*   0 (zero) if user selected Cancel , or

*   98 if user selected Exit, thus terminating execution of chain.

modem, select
    Executes device selection procedure. Returns 0 (zero) if a modem was selected. This actor does not perform any setup operation. Using this actor as the last one, within a chain, is pointless.

moremenu, more, menumore
    Displays More actions menu of Sakis3G script. Returns:

*   0 (zero) if user selected Cancel , or

*   98 if user selected Exit, thus terminating execution of chain.

prepare, init
    It attempts to PIN unlock modem, register network and update HAL. Calls setup actor if required.

recompile
    Attempts to recompile embedded Usb-ModeSwitch binary for you.

reconnect, restart
    Attempts to drop current connection (if any), and then attempts to connect again.

report
    Generates a report for providing feedback. Fails if invoked while not connected.

setup
    Attempts to load required kernel module and create appropriate tty node (if not created already), calling switchonly actor if required.

state
    Provided for convenience. Suggests variable values and switches that could help you repeat result of previously executed actor(s), by avoiding to answer as many questions as possible. Always returns 0 (zero).

status
    Displays information about current connection status. Returns:

*   0 (zero) if currently connected.

*   6 (six) if not currently connected.

switchonly
    Attempts to only switch selected USB modem, calling modem actor if necessary.

toggle
    Attempts to toggle current connection status:

*   Attempts to disconnect if currently connected, or

*   attempts to connect if not yet connected.

udevrule
    Provided for convenience. Suggests a udev rule file, that could be used, for repeating results of previously executed actor(s), immediately upon physical connection of USB modem. Always returns 0 (zero).

USER INTERFACE

Sakis3G script will attempt to automatically determine best fitted UI upon each one execution. Automatic selection will only happen if a UI is not explicitly set using SGUI variable, or corresponding switches, or UI explicitly set, through these methods, is not available.

There are several aspects taken into consideration when Sakis3G script attempts to detect best fitted UI:

1.  Existence or not of a valid local X session display on which access is granted,

2.  One or more of the following switches being set:

*   --console switch forcing the use of text mode UIs only.

*   --interactive switch allowing the use of an interactive UI.

*   --osd switch requesting for OSD messages being displayed.

*   --balloons switch requesting for "balloon-like" notifications being presented through libnotify.

3.  Availability of respective utilities within system's PATH.

If more than one UI providers are available, the one that will be used is determined according to the following list (most to least preferred):

1.  kdialog,

2.  zenity,

3.  Xdialog,

4.  Terminal emulator in the following order:

*   gnome-terminal

*   konsole

*   xterm

5.  whiptail,

6.  dialog,

7.  interactive terminal, which resembles an elementary UI through shell builtin functions.

8.  terminal, which is no UI at all. Sometimes useful to set (e.g. when using Sakis3G from within another shell script).

Note:
    9menu is never automatically selected. It can only be used by explicitly setting either one of those two:
         --9menu
         SGUI="9menu"

GRAPHICAL UI

Graphical UI is only used if:

*   A valid local X session display is available, and

*   access is granted to that display, and

*   --console switch is not set, and

*   at least one of the following is available:

*   zenity, or

*   kdialog, or

*   Xdialog, or

*   9menu, or

*   gnome-terminal or konsole or xterm

Note:
    You can redirect Sakis3G script to a specific display using DISPLAY and LOCALAUTHORITY variables.

CONFIGURATION FILES

Variables and switches can either be supplied on command line, or be placed within configuration file(s). It is not possible to define an actor within a configuration file. For detailed information about configuration files, please consult sakis3g.conf(5).

EXAMPLES

Example #1: Extract source of Sakis3G script within /usr/src folder:
     # sakis3g disassemble /usr/src
     # ls -ld /usr/src/sakis3g-*
     drwxr-x--- 2 sakis sakis 4096 2010-04-14 06:04 sakis3g-0.2.0
     #

Example #2: Determine status according to result code:
     #!/bin/sh
     /usr/bin/sakis3g silent status
     ret=$?
     if [ "${ret}" -eq "0" ]; then
        echo "Connected."
     elif [ "${ret}" -eq "6" ]; then
        /usr/bin/sakis3g silent plugged
        ret=$?
        if [ "${ret}" -eq "0" ]; then
           echo "Not connected."
        else
           echo "No modem plugged."
        fi
     else
        echo "Error ${ret} occurred." >> /dev/stderr
     fi

Example #3: Extract source of embedded Usb-ModeSwitch version and compile a binary for your own use:
     $ sakis3g getfile usb_modeswitch.h > usb_modeswitch.h
     $ sakis3g getfile usb_modeswitch.c > usb_modeswitch.c
     $ gcc -Wall -lusb -o "usb_modeswitch" "usb_modeswitch.c"

Example #4: Check version of embedded Usb-ModeSwitch binary.
     $ sakis3g usb_modeswitch --version

Example #5: Directly use embedded Usb-ModeSwitch binary to switch a ZTE device:
 $ sakis3g usb_modeswitch -v 19d2 -p 2000
 -M "55534243123456782000000080000c85010101180101010101000000000000"

Example #6: Display man page of embedded Usb-ModeSwitch version:
     $ sakis3g man usb_modeswitch

Example #7: Display Sakis3G script's man page:
     $ sakis3g man

Example #8: info actor will only be executed if connect actor succeeded into establishing data connection:
     $ sakis3g connect info

Example #9: On this example, connect actor will never be executed!
     $ sakis3g disconnect info connect Let us discover reason behind:

*   If disconnect actor failed (e.g. you did not provide it with root password), chain will anyway stop.

*   If disconnect actor succeeded, then info actor will anyway fail, since no active connection exists.

Example #10: Executing switchonly actor while no switchable device exists, results into error "No switchable modem found" being displayed. Using this example, you avoid seeing the error message, by aborting chain before switchonly actor being executed:
     $ sakis3g switchable switchonly

Example #11: Re-implementing reconnect actor:
     $ sakis3g ignore disconnect connect

Example #12: Re-implementing toggle actor:
     $ sakis3g connected disconnect || sakis3g disconnected connect

Note:
    Using this example, instead of toggle actor, is a waste of cpu-cycles.

Example #13: Implementing a more clever reconnect like behavior. This may be useful when your operator sometimes drops connection after a while:
     $ sakis3g ignore disconnect connect wait wait wait wait not connected connect

Example #14: A native language statement:
     $ sakis3g If not connected anywhere, then connect somewhere.

*   "If": Unrecognized, ignored.

*   "not": not operator reversing next actor.

*   "connected": connected special actor.

*   "anywhere,": Additional unrecognized text, in order to be able to use comma ",". Using it next to "connected" would lead into "connected," being parsed which would be ignored as unrecognized.

*   "then": Unrecognized, ignored.

*   "connect": connect actor.

*   "somewhere.": Additional unrecognized text, in order to be able to use dot ".". Using it next to "connect" would lead into "connect." being parsed which would be ignored as unrecognized.

Example #15: Exercising our manners:
     $ sakis3g Can you please connect for me?

*   "Can", "you": Unrecognized, ignored.

*   "please": A synonym of --voodoo switch.

*   "connect": connect actor.

*   "for", "me?": Additional unrecognized text, in order to be able to use question mark "?". Using it next to "connect" would lead into "connect?" being parsed which would be ignored as unrecognized.

EXIT STATUS

The exit status of Sakis3G script is set to indicate whether any error was detected, or the reason for the script being terminated. Values used are:

 0    No error occured, or
     Connected. [ status actor ]

 1    Failed to become root through sudo, or
     Unexpected internal error.

 2    Reserved.

 3    No method for acquiring root privileges.

 4    Required utility not found within PATH.

 5    Sakis3G itself, not found within PATH.

 6    Not connected, or unable to detect if connected. [ status actor ]

 7    Unable to locate/enumerate connected USB devices.

 8    Error while setting up modem.

 9    Failed to unload existing driver.

 10    Failed to locate appropriate driver for use with USB modem.

 11    Failed to load appropriate driver for USB modem.

 12    Wrong PIN. Aborting to prevent SIM LOCK.

 13    Modem is unable to register a network.

 95    Failed to connect (wvdial or pppd failed to connect).

 98    User interaction required or user requested to terminate.

 99    Unknown error.

KNOWN PROBLEMS

Known problems should be fixed in the future:

1. Connecting with an operator using CDMA is not yet possible.

2. If OSD messages output method is osd_cat/xosd and font defined by XOSDFONT configuration variable does not exist, nothing appears on X screen. Use xfontsel or xlsfonts utilities to construct/locate a valid font string for your system.

3. If you connect using Sakis3G script and then disconnect and connect back by using other software, script may incorrectly report status of connection according to information from previous connection.

4. Ironic messages may appear when invoking script using only non-recognized arguments.

LIMITATIONS

This page refers to known limitations of Sakis3G script. Known limitations are problems, issues or functionality which one should not expect to be fixed/added in the future.

1. 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 SIM card to a cellular phone and have its PIN number limited to 4 digits.

2. Unpredicted behavior if more than one modem units with identical USB IDs are connected.

3. 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 disconnected:

1.  it does not revert /etc/resolv.conf back to the configuration prior to making the connection,

2.  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 network to get a working setup again.

*   If you were not connected to any other network while establishing 3G connection, this limitation does not apply.

4. This script does not allow sending SMS.

5. This script does not allow monitoring of signal quality and band.

6. 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 variable to invoke a tailor-made command.

*   As a note, if you encounter problems while sharing (do NAT through) your 3G connection, consider using the following command:

    iptables -I FORWARD -p tcp --tcp-flags SYN,RST SYN
             -j TCPMSS --clamp-mss-to-pmtu

7. While disconnecting, this script will kill all running pppd instances, thus eliminating any other P-t-P connections you might have running. If you have a complex setup (i.e. bridging across ppp connections), you should NOT (need to) use this script, as it also messes up with your routing tables: you were warned.

FILES

Sakis3G script never touches anything on your filesystem(s), except when:

*   explicitly instructed to create a desktop shortcut, and when

*   explicitly instructed to generate a log.

/tmp/sakis3g.3gnet
    Temporary file containing information useful to Sakis3G script for presenting connection information.

/etc/sakis3g.conf
    Sakis3G configuration file. Consult sakis3g.conf(5) for more information.

~/.3gpin
    Allows user to define its own PIN number. This value gets overriden if SIM_PIN variable is set through command line or within a configuration file.

Other than that, you may only temporarily witness some file(s) appearing on your /tmp directory.

SEE ALSO

sakis3g.conf(5), usb_modeswitch(1), pppd(8), wvdial(1), udev(1), udevd(8), hald(8)

AUTHOR

Sakis3G script and this man page are written by Sakis Dimopoulos (sakis at project's domain). Official page of project is at:

    http://www.sakis3g.org/

Official documentation of latest Sakis3G script version, is available at:

    http://wiki.sakis3g.org/

LICENSE

Sakis3G script 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 of this program or authors of any of its dependencies have 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 mentioned by this package belong to their respective owners.

This program, in order to remain as self-contained as possible, includes original source packages of some of its dependencies. You should consult their respective COPYING and README files to identify terms under which they are redistributed by Sakis3G script.