<html><head><title>SimpleSSHD</title>
<meta name="HandheldFriendly" content="true"/>
<style type="text/css">
pre {
margin-left: 1em;
}
</style>
</head>
<body>
<p style="float:right; width:30%;"><img style="width:100%;" src="icon.png"></p>
<h1>SimpleSSHD</h1>
<p>SimpleSSHD is an SSH2 server based on dropbear that supports scp,
sftp, and rsync. It only supports public-key based authentication (no
password/interactive auth except for bootstrapping). It does not use
root, which means it must listen on a port over 1024 (defaults to port
2222).</p>
<h2>Quick start</h2>
<ul>
<li> Install SimpleSSHD.
<li> On any computer which will connect to your Android device, set the
port to 2222. With OpenSSH, this can be done by putting these lines in
<tt>~/.ssh/config</tt>:
<pre>
Host myphone
Port 2222
</pre>
<li> Launch SimpleSSHD, and in Settings enable "Start on Boot", then
manually start it for the first time.
<li> Create <tt>/sdcard/ssh/authorized_keys</tt>
<li> Optionally make <tt>/sdcard/ssh/.profile</tt>
</ul>
<p>If SimpleSSHD does not find an <tt>authorized_keys</tt> file when a
client connects, then it generates a single-use password at that time and
displays it in the console log. So the procedure to login the first time
is to initiate the ssh connection, then look at the phone and type in the
password that is on the screen in the SimpleSSHD app. It is recommended
to use that shell session to install the <tt>authorized_keys</tt>
file.</p>
<p>Once <tt>authorized_keys</tt> exists, only public key authentication
is supported. If you screw up your <tt>authorized_keys</tt> file, use
the options menu (upper right) -> Reset Keys.</p>
<p>Once you get setup, you may want BusyBox. Check out
<a href="https://play.google.com/store/apps/details?id=org.galexander.busybox">SimpleBusyBox</a>.</p>
<h2>Settings</h2>
<p>Generally speaking, you must re-start the SimpleSSHD service for any
of these settings to take effect.</p>
<dl>
<dt>Start on Boot</dt>
<dd>Automatically start the SimpleSSHD service when the phone powers on.</dd>
<dt>Foreground Service</dt>
<dd>Run the SimpleSSHD service as an Android "foreground service." This
means a notification will be displayed for the service (you might be able
to block the notification by long tapping the notification).
On newer versions of Android (since Marshmallow), this may also make
SimpleSSHD more responsive if the phone has been in Doze mode. It does
not seem to increase battery consumption much.</dd>
<dt>Start on Open</dt>
<dd>Run the SimpleSSHD service whenever the app is launched. The "STOP"
button will be replaced with a "QUIT" button that stops the service and
exits the app. This is useful if you want to only run the service when
you really need it -- start the app to start listening for connections,
and then click "QUIT" when you are done.</dd>
<dt>Port Number</dt>
<dd>This is the port number that SimpleSSHD will listen on. It must be
greater than 1024 (because SimpleSSHD does not have root).</dd>
<dt>SSH Path</dt>
<dd>Path for general dropbear files, which defaults to
<tt>/sdcard/ssh</tt>. Most importantly, this is where
<tt>authorized_keys</tt> is found. It is also where host keys wind up
(they are created on demand), and where temporary files go. This path
should probably be under <tt>/sdcard</tt>.</dd>
<dt>Login Shell</dt>
<dd>Path to the command shell. The default Android shell is
<tt>/system/bin/sh</tt>, but you may prefer to use the one that comes with
busybox or whatever. If you set it to the su binary (i.e.,
<tt>/system/xbin/su</tt>), then scp, sftp, and rsync will run as root and
should be able to access files outside of the sdcard. If the name of the
shell contains "su" in it, instead of putting "-" before argv[0] to
indicate the login shell, it puts "-" as argv[1]. That is, a regular
login shell would be invoked as "-sh", but su will be invoked as
"su -".</dd>
<dt>Buffer hack for rsync+SuperSU</dt>
<dd>A bug in SuperSU interacts with an infelicity in rsync to cause an
occasional deadlock. This is a real pain because I use SuperSU+rsync
for system-wide backups, which will always eventually trigger the
deadlock. To work around this, there is a "Buffer hack" option that
should be enabled if you use rsync with SuperSU. It adds a miniscule
overhead to rsync, but isn't harmful even if you aren't using
SuperSU.</dd>
<dt>Home Directory</dt>
<dd>The login shell's home directory, which also defaults
to <tt>/sdcard/ssh</tt>. This is where your ssh session starts out, and is
where <tt>.profile</tt> will be found if it is present.</dd>
<dt>Extra Commandline</dt>
<dd>You can specify additional commandline options for dropbear server.
The options which are hardcoded are:
<blockquote><pre>-R -F -p :portno</pre></blockquote>
You can use <tt>\</tt> or <tt>"</tt> to escape characters in this
commandline.</dd>
<dt>Environment Variables</dt>
<dd>You can specify environment variables to define before executing the
shell. There is one variable per line, with a
"<em>name</em><tt>=</tt><em>value</em>" format.
A common use would be "<tt>ENV=/sdcard/ssh/.profile</tt>", if your device has a
build of <tt>mksh</tt> that does not execute a <tt>.profile</tt>
automatically.</dd>
<h2>Frequently Asked Questions</h2>
<p>Here are some common complaints:</p>
<ul>
<li> Writing to an SD card is not generally possible -- your mileage may
vary. Modern Android (since about Kit Kat) only allows write access to
an SD card through the Android Java API, but shell commands usually use
Unix APIs (POSIX, C). I don't know a work-around. Most phones let you
write to <tt>/sdcard</tt>, but it's often in the phone's internal memory.
<li> <tt>rsync</tt> will do too much work for an update, because there is
usually no way to update the ctime, mtime, or atime on files in
<tt>/sdcard</tt>. Use <tt>rynsc --size-only</tt>, and it will compare
the file sizes instead of the modification time.
<li> For the same reason, <tt>rsync -a</tt> will generally fail. Use
<tt>rsync -r</tt> instead.
<li> "<tt>Not backgrounding</tt>" is just the string that dropbear
outputs when it isn't asked to <tt>fork()</tt> when it starts up -- it's
harmless.
<li> If you really must specify which IP to listen on, consider setting
<b>Port Number</b> to 22 (which will fail and be ignored), and then add
<tt>-p 192.168.1.123:2222</tt> to <b>Extra Commandline</b>.
</ul>
<h2>Change Log</h2>
<ul>
<li> <b>2018/05/16 Version 18:</b> Use correct idiom for <tt>su</tt> as a
login shell (so busybox <tt>su</tt> can work). Add environment variables
to settings.
<li> <b>2018/03/24 Version 17:</b> Add native x86 support.
<li> <b>2017/10/28 Version 16:</b> Fix rsync on Android 8.0 (Oreo).
<li> <b>2016/10/17 Version 15:</b> Fix crash on pre-Nougat versions of Android.
<li> <b>2016/10/16 Version 14:</b> Support single-use passwords for
bootstrapping.
<li> <b>2016/10/16 Version 13:</b> Support foreground service (fewer
stalls with newer Android). Add "Start on Open" mode.
<li> <b>2016/08/08 Version 1.11:</b> Fix stall initializing random number generator.
<li> <b>2016/07/22 Version 1.10:</b> Enable TCP port forwarding.
<li> <b>2016/07/04 Version 1.9:</b> Restart sshd if the system kills it.
<li> <b>2016/06/21 Version 1.8:</b> sftp, rsync, and scp now work on
files bigger than 2GB.
<li> <b>2016/06/19 Version 1.7:</b> Don't clear environment variables (so
you can use <tt>am</tt> or <tt>pm</tt> more easily). Add "Authorized
Keys" menu option to help maintain the <tt>authorized_keys</tt> file.
<li> <b>2016/06/12 Version 1.6:</b> Fix typo that broke scp/sftp/rsync in
version 1.5.
<li> <b>2016/06/11 Version 1.5:</b> SuperSU+rsync hack now limits the
buffer size to 1MB.
<li> <b>2015/11/23 Version 1.4:</b> Don't abort if IP address lookup fails, and make proper "About" menu.
<li> <b>2015/06/21 Version 1.3:</b> Hack to make rsync work with SuperSU.
<li> <b>2015/01/18 Version 1.2:</b> Displays the IP address it's listening on.
<li> <b>2014/12/29 Version 1.1:</b> Works with Lollipop now.
<li> <b>2014/12/22 Version 1.0:</b> Initial public release.
</ul>
<h2>About</h2>
<p>SimpleSSHD is built using parts from open source projects:
<a href="https://matt.ucc.asn.au/dropbear/dropbear.html">Dropbear SSH</a>,
<a href="http://www.openssh.com/">openssh</a> (for scp and sftp-server),
and <a href="http://rsync.samba.org/">rsync</a>. Those projects in turn
are built on other projects. A lot of people's work is represented here,
and very little of my own.</p>
<p>But if you find bugs/infelicities, it's probably my fault, so email
me:<br>
<img src="/email.png"></p>
<p>To get the source:</p>
<pre>git clone http://galexander.org/git/simplesshd.git</pre>
</body></html>