mirror of
http://galexander.org/git/simplesshd.git
synced 2024-11-27 09:48:08 +00:00
205 lines
8.5 KiB
HTML
205 lines
8.5 KiB
HTML
<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 "name=value" format.
|
|
A common use would be "ENV=/sdcard/ssh/.profile", if your device has a
|
|
build of <tt>mksh</tt> that does not execute a .profile
|
|
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 setting.
|
|
<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>
|