PC Connectivity

Maemo PC Connectivity provides tools to simplify setting up of communication between the Tablet and the PC at two parts:

- Connection setup: To configure a TCP/IP connection based on different mechanisms (USB, Bluetooth, WLAN) and different operating systems (Linux, Mac OS and Windows)

- Communication tools: remote shell (SSH, SBRSH), secure remote copy (SCP), mounting file systems (SSHFS, NFS, SMB)

What is SBRSH?

Sbrsh means  " Scratchbox Remote Shell". It is a remote shell solution such as ssh. It allows you to run programs in the Tablet from the host PC, but using the host filesystem, instead of the one from the device. 

The official Scratchbox Remote Shell documentation is here , though it has not yet been updated for sshfs usage.

How SBRSH works?

The following steps show a common use of SBRSH:

1. The user configures sbrsh client in the host PC giving the folders to be remotely mounted in the Tablet (usually its home folder)

2. The user run "sbrsh myprogram" from the host PC to test on tablet if its program is working properly

3. sbrsh client (PC) sends this request to the sbrsh server (tablet) 

4. The sbrsh server (tablet) mounts the PC folders in the Tablet according to the configuration files set by the user (step 1)

5. The sbrsh server (tablets) runs the command ("myprogram" in this example) and redirects its standard output to the sbrsh client (PC)

6. sbrsh client (PC) receives the output and shows to the user

Tablet configuration

Configuration file /etc/default/sbrshd

You can configure sbrsh basic functionality in "/etc/default/sbrshd" , by uncommenting lines and setting variables to different values. Some useful options are DEBUG and EXPIRATION. You must restart the sbrsh daemon after changing this configuration file:

        # /etc/init.d/sbrsh restart

The DEBUG option triggers logging to "/var/log/sbrshd.log" (or whatever value DEBUG_FILE has). This can be useful if you are having trouble connecting. Note: you may run "sbrshd --enable-debug" or "sbrshd --disable-debug" to toggle this option dynamically.

The NO_SANDBOX option is usually false, meaning a sandbox is used. This means that the filesystem from your host (usually the scratchbox rootstrap) is exposed to the Tablet. Otherwise, you will be executing programs against the actual Tablet filesystem.

The EXPIRATION option controls how long in minutes sbrshd will wait before unmounting shares. Since the typical sandboxed usage of sbrshd will cause a significant delay the first time you connect – because most of the shared libraries and shell-related binaries from the host must be passed over the wire – you will usually want a longer delay.

The installation of the maemo-pc-connectivity meta package has configured these for you for no debugging, sandboxed enabled, and a 15 minute expiration.

Configuration file "/etc/sbrsh.conf"

You have to give sbrshd access right to the host PC editing the file /etc/sbrshd.conf. You need to manually edit this file and add an entry for your host IP Address. Just add the host PC address as a new line (e.g 192.168.2.14).

Note: sbrsh does not use a secure protocol, so be judicious in granting access!

Explanation about sandbox mode

Sbrshd supports remote command execution in two differents mode:

  • sandbox - allows remote execution of commands in the Tablet considering the local environment from where the command is executed. This meaning that the filesystem from your host (usually the scratchbox rootstrap) is exposed to the Tablet.
  • no sandbox - the default mode. The remote execution of commands in the device occurs against the current Tablet filesystem.

Host PC configuration

Passwordless ssh validation

Exchange ssh keys between the host PC and the Tablet. The easier way to do that is through the "exchange-ssh-key"  script, which is part of the host-pc-connectivity package (see the installation instrunctions). The line below is an example on how to use the scipt:

$ exchange-ssh-key -l <local_address> -r <remote_address> -s <remote_user>

where:

        <local_address> is the host PC IP (e.g. 192.168.2.14)

        <remote_address> is the tablet IP (e.g. 192.168.2.15)

        <remote_user> the user on tablet to exchange the keys with (e.g. root)

sbrsh configuration

In order to use sbrsh (the client), you need a file describing which named configuration targets to select from and which file systems they export to the host.

In standalone mode, by default, "~/.sbrsh" is used, and "sbrsh -c <file>" may override this. The first target in the file is used by default, and "sbrsh -t <target>" may override this.

In CPU transparency mode, the configuration file is determined from the SDK target location, and the first target is used. See details from below.

sbrsh file format

Sbrsh uses SSHFS or NFS in "background" to mount the host PC file systems in the tablet. To setup what host PC folders will be mounted in the tablet, add the configuration on the file "~/.sbrsh". The configuration format is as follows:

# <target name> <hostname>[:<port>]
# nfs|bind|sshfs <host filesystem> <target mountpoint> [<options>]
# ...

A blank line separates entries and in sbrsh client version 7.6 or later a hash mark "#" denotes commented lines.

"nfs" or "sshfs" lines describe the protocol for exporting host PC file systems to the Tablet. We recommend sshfs for new users since this line is all you need. For NFS you need to edit NFS system configurations as well so the setup is more complicated.

The mounts must appear in order of increasing depth. For instance, the root must be mounted first, followed by entries that live inside the root, etc.

"bind" lines override the host filesystem exports by overriding portions of the filesystem from the target. This is essential for filesystems which contain Tablet specific files (/tmp, /var, /sys, /dev, /proc ... see details below).

Notice that when changing the sbrsh configuration file, "sbrsh [-c <file> -t <target>] --umount" should be done before editing the configuration because these commands read the current sbrsh configuration and don't remember previous mounts. Otherwise you might experience strange errors or failures to mount.

Example configuration

Example sbrsh configuration file "~/.sbrsh" for username you and target DIABLO_ARMEL :

sshfs-target 192.168.2.15
ssh you @192.168.2.14:/scratchbox/users/you /targets/DIABLO_ARMEL/ / rw,nonempty,allow_other
ssh you @192.168.2.14:/scratchbox/users/you /home/you / /home/you rw,nonempty,allow_other
bind /tmp /tmp
bind /dev /dev
bind /dev/pts /dev/pts
bind /proc /proc
bind /sys /sys
bind /var /var

To use sbrsh as CPU transparency in scratchbox

  • Place this configuration in "/scratchbox/users/you/targets/DIABLO_ARMEL.sbrsh"

  • Either create a new target using sb-conf or sb-menu, or edit DIABLO_ARMEL target configuration in "/scratchbox/users/you /targets/DIABLO_ARMEL.config" configuration file.

  • Change "SBOX_CPUTRANSPARENCY_METHOD" to read :

    SBOX_CPUTRANSPARENCY_METHOD=/scratchbox/devkits/cputransp/bin/sbrsh

Test sbrsh

If you changed the ssh key with the "root"  user in the device, you need to specify this in the command line. Try running the following command on the host PC to see if the mount works:

~ $ sbrsh -r 0,0,root ls /
bin cdrom etc home lib mnt proc sbin sys usr
boot dev floppy initrd media opt root srv tmp var  

Troubleshoot

Authentication failed error:

~ $ sbrsh /bin/sh
sbrsh: authentication failed

This means you forgot to add your host PC's IP address to the Tablet's /etc/sbrsh.conf file.

Connection reset by peer error:

~ $ sbrsh /bin/sh
sbrsh server: read: Connection reset by peer
sbrsh server: Can't mount to point: /var/sbrshd/you@192.168.2.14/sshfs-target/

This happens because you do not have the same user in both machines (tablet and PC). Use the option "-r"  to specify the user you will run the command in the tablet side, e.g. "-r 0,0,root".

Then, be sure your ssh keys has been sucessfuly exchanged between your user, and the "root"  user in the tablet. Try to ssh in both directions and none password should be required (passwordless login).

Can't execute command (Permission denied) error:

~ $ sbrsh /bin/sh
sbrsh server: Can't execute command: /bin/sh (Permission denied)

This error is misleading – it usually means you're missing a mount for the root directory on the Tablet, when sandbox mode is enabled (the default). The error comes from "chroot()" .

Can't execute command (No such file or directory) error:

/scratchbox/users/you/home/you $ sbrsh myprogram
sbrsh server: Can't execute command: myprogram (No such file or directory)

Be sure the resolved program path is visible from the Tablet or specify a full path. If you map, e.g., "/scratchbox/users/you/home/you /" to "/home/you /" , then run "sbrsh /home/you /myprogram" instead.

osso_initialize() failed error:

~ $ sbrsh maemoapp


maemoapp[2096]: GLIB ERROR ** default – file ... assertion failed: (result->osso)

or

maemoapp[2096]: osso_initialize() failed

OSSO applications initialize the DBUS connection very early, so DBUS problems are probably the cause.

When launching maemo applications, you must override the "DBUS_SESSION_BUS_ADDRESS" environment variable. The value from your host system is probably completely incorrect (especially since "/tmp" is bind-mounted to the target).

Try this instead:

DBUS_SESSION_BUS_ADDRESS=unix:path=/tmp/session_bus_socket sbrsh maemoapp