"Let's move that data!"

SSHelper download QR code  Direct download link

Figure 1: SSHelper on a small screen. Click the image to see a larger display.

• The Program

  • SSHelper is an advanced, multi-protocol, secure server for the Android platform.
  • SSHelper requires Android version 3.2, API 13, or newer.
  • SSHelper works just fine with a normal, unrooted Android device — i.e. your device.
  • SSHelper works as an application and as a service. As a service it runs in the background, providing secure communications protocols without requiring user attention.
  • SSHelper supports interactive Secure Shell (hereafter SSH) sessions and various kinds of transfers including scp, sftp, and rsync, on all common platforms:
    • On Windows, SSHelper works with WinSCP, PuTTY and similar programs.
    • On Linux, apart from normal SSH shell session activities, SSHelper can be used directly with file browsers for seamless filesystem browsing and transfers by specifying the "sftp:" protocol.
    • On the Mac, SSHelper works with Cyberduck and similar programs.
  • SSHelper is free, open-source and there are no ads. It's licensed under the GPL and the source is freely available.

• The Programmer

  Hello — I'm Paul Lutus, author of SSHelper. I've been writing software for about 35 years and have written some very well-known titles (Apple Writer, Arachnophilia). SSHelper is my first Android application — I wrote it simply because there were no Android programs that could give me what I needed. Existing programs were missing features and protocols, primarily support for rsync, a very efficient way to synchronize two directory trees.

  I hope you like SSHelper. And stay tuned — I'll be writing more Android programs in the future.

I'll start with the simplest instructions, then in a later section I'll provide details for those who want them.

• Getting SSHelper

  Here are some easy ways to get SSHelper:

  • At the top of this page is a QR code (the box with the pattern) that can be used to transfer SSHelper directly to your camera-equipped Android device by way of a QR code reader (on many units with a camera, Android comes with a QR code reader). Read the code with your Android device's camera and QR software, download the SSHelper installation file and install it.
  • Second option. Below the QR code is a download link to the SSHelper installation file (and  here is that link again). This approach only works if you're browsing this page with your Android device. Click the link and, as above, download the SSHelper file and install it.

• Setting Up

  • When you run SSHelper the first time, it installs itself, its supporting programs (dropbear, busybox, rsync and sftp-server) and creates a directory structure to support its activities.
  • When SSHelper is done installing itself, it will automatically start its SSH server on port 2222, the default port for non-rooted Android devices using SSH.
  • To verify that SSHelper has started normally:
    • Look at the top of the display and check the appearance of the status LEDs:

       Server  Wireless

      These LEDs show that the Secure Shell server started successfully and there is an active wireless connection. Contrast this with the session shown in Figure 1 at the top of the page, where no wireless connection is available (because it's not a real device, it's an Android development emulator).
    • Touch the  Activities icon and see if there are log entries that look more or less like this:

      2011-10-31 20:31:22 opening dropbear server 3333 on port 2222
      dropbear [3333]: Oct 31 20:31:22 Not backgrounding
                              

      This also indicates normal operation.
  • The next step is to get your device's IP address. Touch the  Configuration icon and make note of the "Server Address". You will need this address to connect with your device.

• Making First Contact

  • For this step, you will need to have:

    • The server's address (see above), which is a four-part number that looks more or less like this: 192.168.1.132.
    • A laptop or desktop machine able to connect with your Android device using a wireless connection.
    • A suitable SSH client program for your platform. I have listed some possibilities above, in a range between full-fledged file browsers that understand SSH, to simple command-line programs for less exotic interactions.
  • Let's get started. Let's say I have SSHelper running on my Motorola Xoom. By clicking the  Configuration icon I notice that SSHelper's IP address is 192.168.0.74 and the port is the default — 2222. I write these down.

  • Here is how to connect to your Android device up using WinSCP on Windows:

  • For this example we move to a Windows machine and run WinSCP, a popular SSH client program for Windows.
  • When it runs, WinSCP asks for a host name. Your Android isn't likely to have a host name on your local network, so instead type in the IP address you acquired from SSHelper above.
  • Next, WinSCP wants to know a port number. Type in 2222.
  • For "User name", type anything, it doesn't matter, but type in something.
  • For "Password", type "admin", the default SSHelper password.
  • Skip "Private key file" for now.
  • For file protocol, choose "SFTP" if it isn't already selected. This is one of the many protocols SSHelper recognizes.
  • Now click "Login".
  • WinSCP will show a dialog warning about connecting to an unknown server. Click "Yes."
  • WinSCP will then show a login banner that originates with SSHelper — this is a convenient way for you to be reasonably sure you're connected to the SSHelper server. Click "Continue".
  • Next, if you installed WinSCP with the Commander interface option (recommended), you will see a two-pane window with your local file system listed on the left and the Android/SSHelper filesystem listed on the right.
  • Now skip ahead to "Here's how to navigate on all platforms" below.

  • Here is how to connect to your Android device from a Linux desktop:

  • Open a file browser — Dolphin (KDE) or Nautilus (Gnome):
    • On the Dolphin file browser (KDE), to make an address bar visible, click next to the folder located above the main data window (the flyout text will be "Click to Edit Location") and type "sftp://(ip address):2222". A typical entry might be "sftp://192.168.0.24:2222", but using the address your acquired earlier.
    • On the Nautilus browser (Gnome), choose menu item "Go" ... "Location" and type "sftp://(ip address):2222", just as above.
  • On both the Dolphin and Nautilus file browsers, you are next asked for a username and password — enter anything for the user name, and "admin" for a password.
  • Contrary to what is said below, the Nautilus browser won't go to the SSHelper Home Page, instead it will most likely go to the Android root directory. If this is your experience, simply click the "/sdcard" directory to get back on track with the examples to follow.
  • A hint for you sophisticated Linux users: to avoid having to repeatedly type in the nonstandard "2222" port, create a file named "config" under your home page .ssh directory with this content:

    host (IP address)
      port 2222
                          

    After you have created this configuration file, you will be able to gain access to your android device in the default way: "sftp://(IP address)" or, from a shell, "ssh (IP address)".

  • Here's how to navigate on all platforms:

  • When you first make contact, SSHelper shows its home directory (with the exception noted above), which on your Android device is /data/data/com.arachnoid.sshelper/home.
  • But because of how Android deals with security issues, when you are using your Android device directly, you are a different user and your home directory is (most likely) /sdcard, where your e-books, music and other resources are located. Therefore most of your SSHelper activities will be with respect to the /sdcard directory.
  • To go to that that directory from the SSHelper Home Page, click the "SDCardLink" link that is provided in the home directory.
  • If the above action was successful, you will be in the most useful location on your Android device. It's where you store your own media — downloaded videos, books, music. For example, the directory named "eBooks" contains any e-books you may have acquired, or that came with the device.

At this point, the reader will be able to transfer large amounts of data to and from the Android device — synchronize directories, explore the Android file system, and many other things. This completes the basic introduction to SSHelper.

This section is a detailed list of SSHelper's features. On the SSHelper display is a row of tabs:

•  Activity

  The activity tab contains a log of SSHelper's actions and states. It is a very useful way to analyze problems and to monitor user interactions. According to a logging convention, all the listed dates and times are in UTC, not local time.

•  Configuration

  The configuration tab contains a list of user-selectable options and data entry fields:

  Item	Description
  Server Address	This field is predefined. It contains the address your Android device was assigned by the network. Later, we will discuss methods to make this a permanent, unchanging address for convenience in making contact with the device from your local network.
  Port Number	This is part of the network protocol used in communicating with your device. For a non-rooted Android device, only port numbers above 1024 are allowed. The classical SSH port number of 22 is not assignable without rooting your phone, which I don't generally recommend. The fact that one may not assign the classic SSH port of 22 seems like an annoyance, because one must specify a port when making contact. But as it happens, there is a way to tell your computer to do this automatically — details below. To change the port number, touch the port number entry field and a soft keyboard will appear to accept your entry.
  Server Password	This is the password you use to contact your Android device. The default is "admin". As it turns out, the best and most secure way to set up SSHelper is to arrange a no-password configuration. In that configuration, you're automatically logged on without having to enter a password, but ironically it is more secure than allowing password entries. The full details are below.
  Client Password	This is a bit technical, but there are client programs included in the SSHelper suite, programs that allow you to contact outside servers from your Android device, This entry sets that password for those transactions.
  Disable password logins	This option allows you to prevent attempts to log onto your Android device using a password. It's part of a more secure scheme in which SSH keys are exchanged between server and client to allow automatic secure login, then, since there is no more need to enter a password, the option is disabled to prevent third party attempts to guess your password. Full details below.
  Disable root logins	This prevents acceptance of a login with root authority. For a non-rooted Android device it has no meaning, but if your device has been rooted, be sure to enable this option.
  Allow port forwards from any host	This option simplifies certain transactions that involve more than one network hop.
  Run SSHelper service at boot	This option automatically runs the SSHelper service when you turn on your Android device. This means you can log onto the SSHelper server as described above, but there is no application running, which saves system resources and simplifies access to SSHelper, once you have chosen and tested the options you need.
  Enable Wifi while running	This option automatically enables the device's Wifi service. For nearly all SSHelper activities, an operating Wifi service is required. This is a simply way to assure that the service is running.
  Prevent standby while running	On many Android devices, after a period of inactivity the unit goes into standby mode, and this option prevents it. The result is faster network transactions, but this may not be as important as allowing your device to enter standby with reduced power consumption. I recommend that users test SSHelper both ways and make a choice on that basis.
  Allow voice messages	This option allows SSHelper to use a synthesized voice to tell you what's going on. The voice synthesis feature is not available on all Android devices, but as time passes it's increasingly common. Some users may find the voice prompts annoying, so they can be disabled with this option.
  Show passwords	This option displays the password entries in plain-text.
  Cancel/Undo (button)	As the user makes configuration changes, the old configurations are saved and can be recalled. This is a way to recover from bad or erroneous choices.
  Defaults (button)	This option resets all the SSHelper options to their defaults. This is also a way to recover from bad or erroneous configuration entries.
  Restart server with new values (button)	This option makes the SSHelper server restart using the new choices. Many option entries do this automatically, but not all. This is simply a way to be sure that your choices have taken effect.

•  Terminal

  The terminal feature opens a shell session with your device. This feature isn't particularly easy to use, for a number of reasons. One is that the Android soft keyboard is missing a number of keys that are regarded as essential to shell sessions, like escape, any control keys, or arrow keys. Instead of trying to use this terminal feature, I strongly recommend that users open a Secure Shell session from a desktop or laptop computer, where all the shell session features one expects from a modern shell will be available — history, line editing, color-coded file listings, and so forth.
  
  The terminal feature can be used to recover from certain problems where the only access is local, for example an orphan server process that's blocking the default port, but cannot be stopped by the usual remedy of restarting the server by touching the restart menu icon. In this case, typing "killall dropbear" in the terminal emulator may solve the problem.

•  Home/Help

  This tab opens a Web browser and loads this page — the SSHelper Home Page. This option allows the user to read the instructions while configuring SSHelper. It also uses substantial system resources, noticeable on smaller Android devices. So if this option makes your Android device suddenly slow down, you may want to avoid it.

SSHelper also has an option menu (on devices with large displays, the menu items are sometimes all visible on the action bar):

•  Keyboard

  In some contexts you will need a keyboard to make an entry but the soft keyboard won't appear automatically. This option makes the keyboard appear.

•  Restart

  This option restarts the SSHelper server. Touching the status LEDs also has this effect. Restarting the SSHelper server doesn't disrupt ongoing Secure Shell transactions of various kinds, only the process of logging on.

•  Stop & Quit

  This option stops the SSHelper login server and exits the program. As is normal for Android applications, the application can be restarted from the background list. The point of this option is to disable the login server if that is desired. This option won't affect ongoing Secure Shell transactions, only the ability to log on.

• Pay it forward

  This menu option isn't visible on the action bar even on the largest Android displays, and on small devices it isn't accessible at all. It's not exactly an SSHelper feature, it's just a reminder to pay it forward. SSHelper really is free, and this is not a string attached, just an optional suggestion (more on this topic below).

SSHelper provides secure, reliable interaction with your android device through use of the Secure Shell Protocol and its variations. SSHelper can be used without any special setup (all you need to remember is the default password — "admin"), but the supported protocols are both more usable and more secure if certain setup procedures are carried out.

• Here is how to simultaneously improve operational security and eliminate password entry:

  These instructions are for Linux, but a nearly identical approach work in Windows.

  • Step 1. If you haven't already done this, generate a pair of SSH authentication keys on your desktop/laptop (don't do this if you've already created a key pair). From a shell session in your home directory:

    $ ssh-keygen -t rsa -f .ssh/id_rsa -N ''
                        

    The above command will produce a key pair in your user-level SSH directory (/home/username/.ssh). The pair are "id_rsa", the private key, and "id_rsa.pub", the public key.

  • Step 2. Copy the public key to your Android device:

    $ scp -P 2222 .ssh/id_rsa.pub (android IP address):.ssh/authorized_keys

    SSHelper will ask for a password for the above transaction, but that will be the last time it asks for a password.

  • Step 3. Disable password logins in SSHelper:

    Move to your Android device, touch the  Configuration icon, and check the "Disable password logins" option. You don't need to use a password any more, and password logins only create a security vulnerability.

  • Step 4 (optional). If you're the only person who uses your Android device, the procedure is complete. But if more than one person needs access to your device, use this modified procedure:

    • The additional user should create an SSH key pair as above, in their own user directory.
    • They should copy the additional public key to the Android device this way:

      $ cat .ssh/id_rsa.pub | ssh -p 2222 (ip address) 'cat >> .ssh/authorized_keys'

      This procedure appends the new public key onto SSHelper's existing list of authorized keys. This procedure can be repeated as often as necessary.

• Here is how to avoid having to type in "-p 2222" for each SSHelper transaction:

  This problem is caused by Android security, which in general is a "good thing™", but is sometimes annoying. In this case, non-root access means applications like SSHelper can't use port numbers below 1024.

  Over time the standard user-level SSH port has become 2222, although you can change it if you have a reason to. But there is a relatively simple way to make your desktop/laptop SSH client aware of this nonstandard port and use it by default for your Android device. Here's how:

  • If it doesn't already exist, create a new file in your user-level SSH directory: .ssh/config
  • Give the file this content:

    host (ip address)
      port 2222
                      

  • After this step, SSH desktop/laptop clients will no longer need to be told which port to use.

• Here is how to give your Android device a permanent address on your local network:

  (Yes, this topic list is getting rather far afield from simply setting up and running SSHelper. But these are important things to know and will make your local network perform more efficiently.)

  Did you notice in the above examples how we used (ip address) to identify the Android device? That's fine as long as your local network isn't using DHCP (Dynamic Host Configuration Protocol), which, in exchange for making network configuration easier and more robust, tends to assign IP addresses somewhat randomly. But it's very likely that your local network does use DHCP, which means two things:

  • Unless you look at the configuration tab in SSHelper each time you turn on your Android device, you won't know which IP address has been assigned to it.
  • Configuration entries like that in .ssh/config described above are only valid for one IP assignment — if you turn off your Android device, chances are the next time you run it, it will have a different address. This will invalidate the configuration entry.

  The solution to these problems is to use DHCP "static leases" in your wireless router. This approach has a number of advantages on a local network — you can make configuration entries like that described above and expect them to remain valid, you can access a device using the same name or IP address perpetually, and you can reliably connect with other machines or devices on your local network, a feature not expected in networks with DHCP address assignment.

  Unfortunately, according to this article, what I am calling "static leases" has different names and procedures for virtually every router manufacturer:

  • DD-WRT, the makers of the software I have installed on my Linksys routers, calls it "Static DHCP Assignment". Parenthetically I can recommend this software without reservation — it's quite good, and it's free.
  • The official dhcpd documentation calls it "fixed-address" assignment.
  • Netgear calls it "Address Reservation".
  • Cisco/Linksys (with factory software) calls it "DHCP reservation" or "Static DHCP". Ironically, many Linksys routers won't support the feature with factory software, but will after third-party software is installed.

  All these schemes rely on the fact that every networked device has a unique number assigned to it — a MAC (Media Access Control) number, shared by no other device in the world. Here's what a MAC looks like: 64:6a:2c:8e:1e:63. Each of those digits is hexadecimal, and there are 12 of them, so the address space has 12¹⁶ members (that's about 1.84 x 10¹⁷).

  Given the wide variety of routers and methods for assigning static addresses, I will provide the broad outline of the topic and hope my readers will be able to work out the details for their specific networks. Here are two options and effort levels:

  • Option 1: Just assign a permanent address to the Android device, thus making it reliably accessible on the local network.
  • Option 2: Reconfigure the local network to use static leases for every machine that needs to contact any other machine, but retain the other advantages of DHCP (primarily the fact that no configuration is required at the machine level).

  Here's how to set up Option 1:

  • Log onto your Android device

    From a desktop/laptop machine, open a shell session and:

    $ ssh -p 2222 (ip address)
    (after login complete)
    $ ifconfig
                        

    In the listing from the above command, notice a line that looks like this:

    wlan0     Link encap:Ethernet  HWaddr 64:6a:2c:8e:1e:63
                        

    The "HWaddr" is the number you want.

  • Configure your router to assign this MAC a permanent address

    As explained above, this procedure varies from manufacturer to manufacturer, but for a Linksys router with DD-WRT software installed, simply choose menu item "Services" ... "services", and notice a window labeled "Static leases".

    • Click "Add" to create a new entry.
    • For "MAC Address", type in the 12-digit hexadecimal address obtained above, formatted the same way: xx:xx:xx:xx:xx:xx.
    • For "Host Name", type in your preferred name for your Android device. This is only to help you keep track of your assignments, it's not a name that will be recognized by the local network.
    • For "Address", enter a local network IP address (example: 192.168.0.33, but your network address range may differ) that is not used for anything else. This address must be outside the range from which DHCP assigns addresses, and it must not conflict with any fixed address assignments set up for other devices.

    Having completed the above, reboot the router, then reboot your Android device to see if the assignment is carried out. If it is, then you have a reliable IP address for your Android device to use in SSH configuration as well as for logging on.

  Here's how to set up Option 2:

  • Perform the above MAC location steps for each machine on your local network — make a list of MAC addresses for all the machines and devices that need to communicate with each other.
  • Configure your router as described above, but make as many entries as you have machines and devices that need to reliably communicate. Make note of the assigned IP addresses for the next step.
  • One more step that wasn't in Option 1 — give your machines distinctive names that will be recognized by the local network:
    • On each desktop/laptop machine on your local network there is a master file named "hosts", containing machine names and addresses. Although largely neglected in modern times, this file can be used to convert user-assigned names to IP addresses. On Linux machines the file is /etc/hosts. On Windows machines it is C:\Windows\system32\drivers\etc\hosts.
    • To write into the hosts file, you need to have root authority. Exercise this authority carefully.
    • Here is how the hosts file should look after you have added a few machine names and addresses:

      127.0.0.1       localhost.localdomain  localhost
      192.168.0.1     machine1.com           machine1
      192.168.0.2     machine2.com           machine2
      192.168.0.3     machine3.com           machine3
      192.168.0.4     myAndroid.com          myAndroid
                              

    • To actually edit the hosts file, issue one of these commands:

      • Linux: $ sudo kwrite /etc/hosts
      • Windows: > notepad \windows\system32\drivers\etc\hosts
      
      
    • Use any names you care to assign to your machines, but don't put spaces in their names.
    • Save the file and test it. Its effect should be immediate — you should be able to refer to your network machines by their names.
    • Copy the edited hosts file to each machine on your network, so each of them will be able to use machine names instead of addresses.

  At the end of all the above procedures, instead of having to type "$ ssh -p 2222 192.168.0.33", then entering a password, you can type "$ ssh myAndroid" and be connected with no password. And when using file browsers, the advantages are even more striking — just type "sftp://myAndroid".

• I have one more note about local networks and routers:

  In the DD-WRT software, there is a program called "Dnsmasq", essentially a DHCP server and DNS forwarder that is supposed to confer advantages if enabled. When I first acquired my Android device (A Motorola Xoom), I discovered that Secure Shell sessions would time out and disconnect in two minutes or less, which made long transactions like file transfers impossible.

  At first I suspected there was something about the Android software that was causing this problem, but after some intense detective work over several days, I finally discovered that Dnsmasq was terminating its dynamic address leases way too early. I disable Dnsmasq and the problem vanished.

  I mention this because it was a serious problem whose cause was perversely subtle and counterintuitive. And very difficult to track down.

• Rsync notes (updated 4.12.2012)

  • The rsync application and protocol is a very efficient way to move data between machines, synchronize directory trees, and perform similar activities. At the time of writing SSHelper is the only Android application that fully supports it.
  • Because most rsync transfers will take place to or from the directories under /sdcard, and because the "user" associated with /sdcard doesn't have the same permissions as the SSHelper "user", certain things cannot be done. Specifically, the SSHelper "user" can read and write files from/to /sdcard, list directories and so forth, but for some reason cannot change file permissions or timestamps.
  • Therefore, to avoid a flood of impertinent error messages as well as to avoid endless re-updating of already-updated files, while synchronizing a directory on /sdcard from a desktop or laptop machine, I recommend that rsync be used this way:

    $ rsync -av --no-perms --no-times --size-only
      (source path)/ (android name or address):(dest path)/
                        

    (all on one line)

    The above options call for rsync to archive ("-a") the source directory and all subdirectories to the destination, be verbose ("-v") about what it's doing, don't try to modify destination times or permissions ("--no-perms --no-times") and , when comparing source and destination files, only compare sizes ("--size-only"), since the destination files' times and permissions will be wrong.

    The reason for these options is if rsync is allowed to compare times and permissions, because it wasn't able to correctly set the updated files' times and permissions as explained above, it will "solve" the problem by copying all the files over again, every time the operation is carried out. It's expected that a size comparison will detect and update changed files in most cases.

    There's one more option the user may want to include: delete ("--delete"). This option deletes any files on the destination directory tree that aren't on the source. Including this option assures that the destination directory tree will be identical to the source, even after deleting files from the source.

  • To summarize the above, even though rsync can create a file in the /sdcard directory tree, it then can't change its permissions or its time stamp. I personally regard this as a bug, but that doesn't mean it will go away any time soon.
  • Notwithstanding the above bug, rsync is a very efficient way to update a music or photo collection, or any other large archive that needs periodic updates in a way that may involve many small changes.
  • The absence of rsync support was on a short list of critical, unmet needs that led to my decision to write SSHelper. I regard rsync support as essential to efficient filesystem management.

SSHelper is free, it doesn't show ads, it's not crippleware or shareware, and I don't want your money. I just thought I would make that clear up front.

Years ago, in connection with my software development activities, I came up with an idea I called CareWare. But as the years went by I became somewhat disenchanted with the original idea and I now find it somewhat overheated (even though it's my idea).

So lately, moved as I am by conflicting forces — on one hand wanting to change the world, but on the other not wanting to even appear disrespectful of other people's choices — I've decided to just say pay it forward if you want. But there's no obligation to do that.

There's a menu item in SSHelper that says essentially the same thing: I am confident that you will know what to do. That is all. End of line.

SSHelper is Copyright 2011, P. lutus and is released under the GPL.

SSHelper uses code from the following projects:

• Dropbear — license
• OpenSSH — license
• OpenSSL — license
• BusyBox — license
• Rsync — license
• Cross-compiled for the ARM platform with CodeSourcery

Here is a source archive for SSHelper, organized as an Eclipse Android project.

Version History (reverse chronological order)

• 01-08-2013 Version 1.8. On user request, added Android WRITE_MEDIA_STORAGE permission to the set of permissions, even though this doesn't seem to work on a non-rooted Android device at present, in the hope that someone in Android development will get the message and enable this permission.
• 04-21-2012 Version 1.7. Fixed a problem with the start-at-boot option.
• 02-23-2012 Version 1.6. Fixed several bugs that crept in after the change to Android ICS, all of which revolved around AsyncTask threads, which are becoming increasingly unreliable, so changed to ordinary threads in some cases.
• 11-16-2011 Version 1.5. Fixed a bug in the service initialization code.
• 11-15-2011 Version 1.4. Revised the service code again, for greater robustness.
• 11-15-2011 Version 1.3. Revised the background service launch method to keep Android from stopping it.
• 11-12-2011 Version 1.2. Rewrote code to avoid leaking the Text-To-Speech resource.
• 11-02-2011 Version 1.1. Released updated package after realizing I only support Android API 13 and above.
• 11-01-2011 Version 1.0. Initial Public Release.