Linux iBurst Connection Script

 I always do things to make my life easier, and one of the ways I achieve this is scripts to automate tasks or make them more informative/easy to use.

One of these tasks is connecting to the internet on my iBurst connection at home. This is for the USB modem which uses PPPoE over an ethernet device emulated by the driver.

Originally I had to use "pon iburst" to connect, then check /var/log/messages to ifconfig to see if and when I am connected. Over time I started scripting this and this post is the result of that script.

It has matured quite a bit over the past few years. A list of features can be summarized as follows:

1. When instructed to connect will invoke "pon " (for a configured peer).
2. Shows connection progress using a zenity dialog.
3. All important feedback like errors are reported via zenity message boxes.
4. A successful connect is reported via Gnome's informational messages using notify-send. This is only if the notify-send command is available and you are logged into a Gnome session. The fallback is to use a zenity message box.
5. The assigned IP address will be displayed in the message when connected successfully.
6. If pppd dies it will fail the connection attempt immediately and report this.
7. If the connection attempt remains for a long time without getting an IP address, it will be timed out after a configured amount of time.
8. If the connection attempt fails for any reason it will ensure pppd exits and kill it if necessary.
9. Connects and disconnects can be cancelled. Script will ensure pppd exits and kill it if necessary.
10. When killing pppd the script will use increasing levels of aggressiveness to work around being interrupted by blocking processes.
11. If a connection existed previously it will disconnect unless otherwise instructed with command line switches.
12. Can reliably detect if an existing iBurst connection is already active.
13. Can be instructed to connect quietly.
14. If the iBurst device isn't plugged into it will display an error.
15. This error can be suppressed by a command line switch (useful in automation like if executed when you log in).
16. Supports hooks for pre and post connect, successful disconnect and any error.
17. Thorough logging to a configured log file.
18. When executed as a non-root user will wrap itself inside a sudo session. This way if the sudo is configured to allow execution of the script without a password, then you can run the script as any of the allowed users.
19. Automatically controls the up/down state of the iBurst driver interface (usually ib0). This was discovered from experience and experimentation and increases stability and maximum success with connection attempts. 
20. Some misc other stability and reliability tweaks in the way connections are managed.

This is quiet an extensive list of features. I have found the script to be very reliable these days and can probably say that I connect successfully 100% of the time. The only times I have problems is when the ISP has delays in authenticating me. I haven't had any problems in the past few months where I need to manually play around with plugging/unplugging the device, up/downing the interface, etc.

So I decided to share it.

How to Use

Requirements to use it:

1. Have zenity installed: apt-get install zenity
2. If using Gnome, recommended to have notify-send installed: apt-get install libnotify-bin
3. Have a PPPD peer setup that can be connected using: /usr/bin/pon peername
4. Download the script at: http://sites.google.com/site/qbeukesblog/connect.iburst.sh

With the above requirements satisfied you can edit the script and change the configuration options in the beginning. Most important option is the IB_IFACE and PEER variables. PEER should be the name of the peer used supplied to /usr/bin/pon. IB_IFACE should be the network device name created by the iBurst driver. This is usually ib0.

Then if you're going to execute this command as a non-root user, add the following to your /etc/sudoers file. Remember to replace in your username and the full path to the connect script.

your-username ALL=(root) NOPASSWD: /opt/iburst/connect.iburst.sh

After this you can simply use the following commands to use the script. These commands assume the script is on the command path.

Connect to the configured peer. Will disconnect if there is already an active connection:

connect.iburst.sh

Connect to the configured peer. If already connected will do nothing.

connect.iburst.sh --no-disconnect

Only attempt a connection if the iBurst device is plugged in. This is detected by checking if the IB_IFACE interface is available.

connect.iburst.sh --conditional

Only attempt a connection if the iBurst device is plugged in. Also, if already connecting nothing will be done.

connect.iburst.sh --no-disconnect --conditional

Hooks

If you want to use the hooks, you need to create a directory called connect.iburst.hooks in the same location the script is executed from. So if you execute the script from /opt/iburst, you need to create the directory at /opt/iburst/connect.burst.hooks. If you want to put the directory in a different location, you can do so by editing the HOOKS_DIR variable in the beginning of the script.

From here you can create hooks for 4 types of events:

1. before: Pre Connect
2. disconnect: Successful disconnect. Hooks receives 1 argument, which is the trigger for the disconnect.
3. success: Post Successful Connect. Hooks receives 1 argument, which is the IP address.
4. error: Error condition

The files inside the hooks directory need to be named as follows:

hookid.eventname.sh

Here hookid is simply a name to identify the hook. You can choose this name and it may be anything valid in a filename. 

The eventname is the name of one of the 4 hook events, as listed above (before, disconnect, success or error).

Finally you just need the .sh extension.

As a note, for any given event, these hooks are executed in no specific order. They are also executed synchronously, so any commands that won't exit needs to be executed in the background manually.

Then, for the hook to be executed the file needs to be executable. 

For an example, if we wanted to make a hook that will execute a dynamic DNS update whenever we are connected successfully, we would want to hook into the success event, so we'd call the script dynamicdns.success.sh.

The success event supplies 1 argument to the script, which is the IP address we were assigned. We could then make use of this IP address when doing the DNS update. 

Example Setup

In my setup, I have the script and it's hooks installed at /usr/zbin/connect.iburst.sh and /usr/zbin/connect.iburst.hooks.

Then I have the script configured in my sudoers file so I can execute it without a password.

When I log into Gnome, on my panel I have a shortcut icon the I can click to connect explicitly. This will execute /usr/zbin/connect.iburst.sh. This way it will disconnect if it's already connected.

Finally I also added a command to my Gnome startup, so that whenever I log in and the iBurst device is plugged in a connection will be created. Further, if a connection already exists it won't disconnect and reconnect. This could be the case where I, for example, would log out and log back in for whatever reason. This is achieved by adding the following command line to startup:

connect.iburst.sh --no-disconnect --conditional

Download

The script can be downloaded from here: http://sites.google.com/site/qbeukesblog/connect.iburst.sh