e86f86e77126a1bc4470febe933bb7aab4879c40
[chromiumos/platform/assets.git] / chromeapps / nassh / doc / faq.txt
1
2
3                             .--~~~~~~~~~~~~~------.
4                            /--===============------\
5                            | |```````````````|     |
6                            | |               |     |
7                            | |      >_<      |     |
8                            | |               |     |
9                            | |_______________|     |
10                            |                   ::::|
11                            '======================='
12                            //-"-"-"-"-"-"-"-"-"-"-\\
13                           //_"_"_"_"_"_"_"_"_"_"_"_\\
14                           [-------------------------]
15                           \_________________________/
16
17
18
19                             hterm and  Secure Shell
20                           Frequently  Asked Questions
21
22                                  Version 0.8.2
23                                 August 27, 2012
24
25
26 Hello World.  This is the hterm/Secure Shell FAQ.  If you have a question that
27 is not answered here, please ask it on the chromium-hterm mailing list located
28 at <http://goo.gl/RYHiK>.
29
30
31 > What is "Secure Shell"?
32
33   Secure Shell is a Chrome Application that combines the "ssh" command (see
34   http://openssh.org/ for details) ported to NativeClient with the "hterm"
35   terminal emulator to provide a secure shell client for the Chrome browser.
36
37   Secure Shell provides similar functionality to PuTTY on Microsoft Windows(c)
38   systems, and the ssh command-line application on Mac OS X and Linux systems.
39
40
41 > What is "hterm"?
42
43   "HTML Terminal", or hterm, is an xterm-compatible terminal emulator written
44   entirely in JavaScript.
45
46   It is intended to be fast enough and correct enough to compete with native
47   terminals such as xterm, gnome-terminal, konsole and Terminal.app.
48
49   hterm is only a terminal emulator.  It does not provide SSH access (or any
50   other text-based command) on its own.
51
52
53 > How do Secure Shell and hterm relate to the "crosh" (Ctrl-Alt-T) command in
54   Chrome OS?
55
56   See chromeos-crosh.txt in this directory for the details.
57
58   TL;DR - Don't use crosh for ssh any more, use the Secure Shell app instead.
59   The crosh shell will use the newer terminal emulator from Secure Shell when
60   possible.
61
62
63 > How do hterm and Secure Shell differ from existing web terminals?
64
65   hterm stands out from many existing web terminals in that it was built from
66   the start to match the performance and correctness of "native" terminals such
67   as xterm and Terminal.app.
68
69   It can handle large bursts of text quickly, support very large scrollback
70   buffers, and it closely matches xterm's behavior.  The keyboard even mostly
71   works.  (ha!  See the note about how to get Ctrl-W below.)
72
73   The Secure Shell app is different because it does not require a proxy or
74   relay server to function.  Secure Shell can make a direct connection to
75   a standard sshd server on any port of the destination machine.  Other
76   web terminals require a proxy server in the middle.  In some cases you
77   are even required to hand the proxy your credentials in plain text.
78
79
80 > Is my connection proxied in any way?
81
82   No.  By default all connections are made directly to the sshd server on the
83   destination machine.
84
85
86 > But, what if I *want* to ssh over HTTP?
87
88   Secure Shell also knows how to connect to an HTTP-to-ssh relay that was
89   built inside Google.  Unfortunately that relay isn't open source, and Google
90   doesn't maintain a public pool of relays.
91
92   However, you're free to build one that works the same way.  There should be
93   enough documentation in nassh_google_relay.js to reverse engineer a
94   compatible relay.
95
96   If you're interested in writing an alternative relay library, please mention
97   it on the mailing list.
98
99
100 > Is my connection really secure?
101
102   The Secure Shell app uses ssh to manage the encrypted communication channels.
103   This makes it about as secure as any other connection based on the ssh
104   command.
105
106   It does have the added advantage of running ssh as a sandboxed
107   Native Client plugin, which in theory makes it more secure than an
108   unsandboxed ssh connection.
109
110   Additionally, the Secure Shell application follows a strict Content Security
111   Policy that does not allow access to the JavaScript 'eval' function.  This
112   helps lower the risk that a terminal exploit could run arbitrary JavaScript.
113
114
115 > What should I do if I notice a bug?
116
117   First, please continue reading this FAQ to make sure your issue isn't
118   mentioned.  Then check the bug list at <http://goo.gl/hpqWk>.
119
120   If you don't see the issue there, you can search the archives of the
121   chromium-hterm mailing list here: <http://goo.gl/RYHiK>.
122
123   If all else fails then join the chromium-hterm mailing list and post
124   about what you've found.
125
126   If your bug involves some mis-interpreted escape sequence and you want
127   to file a really useful bug report, then add in a recording of the
128   session.  For bonus points, track down the troublesome sequence and
129   include the offset into the log file.  For more information about how to
130   do this, see the "Debugging escape sequences" section in the hack.txt file
131   in this directory.
132
133
134 > Is there a mailing list to discuss hterm or Secure Shell?
135
136   Yes, the public chromium-hterm mailing list is here: <http://goo.gl/RYHiK>.
137
138
139 > Can I connect using a public key pair or certificate?
140
141   You can import identity files from the connection dialog.  Select the
142   "Import..." link to bring up a file picker.
143
144   You must import two files for each identity.  One should be the private key
145   and should not have a file extension.  The other should be the public key,
146   and must end in ".pub".  For example, "id_rsa" and "id_rsa.pub".
147
148   If you have a key stored in a single ".pem" file, you must split it into two
149   files before importing.
150
151   This will import your public/private key files into the HTML5 filesystem
152   associated with Secure Shell.  There should be no way for another extension,
153   app, or web page to access this sandboxed filesystem.
154
155   +-------------------------------------------------------------------------+
156   | Keep in mind that HTML5 filesystems are relatively new.  As always,     |
157   | it's possible that there are still exploits to be found or disclosed.   |
158   |                                                                         |
159   | Additionaly, Chrome stores HTML5 filesystems as normal files (with mode |
160   | 600, "-rw-------") under your profile directory.  Non-Chrome            |
161   | applications on your system may be able to access these files.          |
162   |                                                                         |
163   | For your own good, protect your important private keys with a strong    |
164   | passphrase.                                                             |
165   +-------------------------------------------------------------------------+
166
167   You can also import a traditional ssh 'config' file using this dialog.
168   Nearly anything that ssh might care about from your ~/.ssh directory can go
169   here.
170
171   See <http://www.openbsd.org/cgi-bin/man.cgi?query=ssh_config> for more
172   information about the ssh configuration syntax.  Keep in mind that any
173   directives that would require access outside of the NaCl sandbox will not
174   function properly.  This includes (but is not limited to) X11 forwarding,
175   syslog functionality, and anything that requires a domain socket.
176
177
178 > Can Secure Shell use my ~/.ssh/config file?
179
180   Probably.  It depends on what it does.  See the answer to the previous
181   question for more details.
182
183
184 > How do I remove a key?
185
186   From the connection dialog, select an identity from the dropdown and press
187   the DELETE key.  This will remove both the private and public key files from
188   the HTML5 filesystem.
189
190
191 > How do I remove ALL keys?
192
193   Open the JavaScript console and type...
194
195     term_.command.removeDirectory('/.ssh/')
196
197   This will remove any non-key files you may have uploaded as well.  It will
198   *not* affect your preferences.
199
200
201 > Does Secure Shell support a keychain of some sort?
202
203   Sorry, not yet.  This is a bit of a technical challenge given the nature
204   of the NaCl sandbox.  We have a few options that we're exploring.  Feel
205   free to post your ideas to the mailing list.
206
207   (And yes, we're already considering integrating with the Chrome NSS
208   certificate store.)
209
210
211 > Can I use Secure Shell for port forwarding?
212
213   Yes.  Enter your port forwarding options in the "SSH Arguments" field of
214   the connect dialog.  The port forward will be active for the duration of
215   the Secure Shell session.
216
217
218 > What is the "Terminal Profile" field for?
219
220   This is the last field in the connect dialog.  It allows you to select
221   which set of terminal preferences to use for the connection.
222
223   If you name a terminal profile that doesn't yet exist, it will be created
224   and all preferences will be set to their default value.  Any preference
225   changes will affect the active terminal profile only.
226
227   For example, enter "light" as the name of a terminal profile for a new
228   connection.  Once you've connected, change the color scheme to
229   black-on-white (as described in the FAQ entried below).  That change will
230   be associated with the "light" profile, and you'll be able to re-use it for
231   other saved connections.
232
233
234 > How do I set terminal preferences?
235
236   The Secure Shell application does not currently have a preferences page.
237   It's in the works, and will be available before Secure Shell leaves
238   "beta" status.  For now, you need to open the JavaScript console to
239   change the user preferences.  Sorry about that.
240
241   In general, you open the JavaScript console and type something like...
242
243      term_.prefs_.set('pref-name', 'pref-value')
244
245   Preferences are saved in your local storage, so they're remembered the
246   next time you launch Secure Shell.
247
248   If you want to check the current value of a preference, type this...
249
250      term_.prefs_.get('pref-name')
251
252   To reset a single preference to its default state, type this...
253
254      term_.prefs_.reset('pref-name')
255
256   To reset all preferences to their default state, type this...
257
258      localStorage.clear()
259
260   Most preference changes take effect immediately, in all open instances of
261   Secure Shell.  The exception is the 'environment' setting, which won't
262   take effect until the next time you reconnect.
263
264   Some common preferences are listed in questions that follow.  For the full
265   list, you'll have to read through the "setProfile" function in terminal.js.
266   It's here: <http://goo.gl/FDEXb>, around line 130.
267
268
269 > How do I change the audible bell sound?
270
271   Open the JavaScript console and type...
272
273      term_.prefs_.set('audible-bell-sound', 'http://example.com/bell.ogg')
274
275   Change the example url to point to the sound file you want to use.
276   Unfortunately, local file: urls are not supported at this time.  If you
277   want to get fancy you could construct a data: url, but the details of
278   that are beyond the scope of this FAQ.
279
280
281 > How do I disable the audible bell?
282
283   Open the JavaScript console and type...
284
285      term_.prefs_.set('audible-bell-sound', '')
286
287
288 > How do I change the color scheme?
289
290   You can change the foreground, background or cursor color preferences from
291   the JavaScript console like this...
292
293      term_.prefs_.set('background-color', 'wheat')
294      term_.prefs_.set('foreground-color', '#533300')
295      term_.prefs_.set('cursor-color', 'rgba(100, 100, 10, 0.5)')
296
297   You can use any valid CSS color value for any of these colors.  You need
298   to use a semi-transparent color (the fourth parameter in the rgba value)
299   for the cursor if you want to be able to see the character behind it.
300
301
302 > How do I change the font face?
303
304   Open the JavaScript console and type...
305
306      term_.prefs_.set('font-family', 'Lucida Console')
307
308   Replace 'Lucida Console' with your favorite monospace font.
309
310   Keep in mind that some fonts, especially on Mac OS X systems, have bold
311   characters that are larger than the non-bold version.  hterm will print a
312   warning to the JS console if it detects that you've selected a font like
313   this.  It will also disable "real" bold characters, using only bright
314   colors to indicate bold.
315
316
317 > How do I change the default font size?
318
319   Open the JavaScript console and type...
320
321      term_.prefs_.set('font-size', 15)
322
323   Replace 15 with your desired font size in pixels.  15 is the default, so
324   you'll have to pick a different number to have any effect at all.
325
326
327 > Can I quickly make temporarily changes to the font size?
328
329   Yes.  The Ctrl-Plus, Ctrl-Minus and Ctrl-Zero keys can increase, decrease,
330   or reset the current font size.  This zoomed size is not remembered the
331   next time you start hterm.  See the previous question if you want something
332   that will stick.
333
334   It's useful to know that hterm has to handle font zooming on its own.
335   Without interference from the browser's built-in zoom function.
336
337   The browser zoom introduces rounding errors in pixel measurements that
338   make it difficult (maybe impossible) for hterm to accurately position the
339   cursor on the screen.  (It could do a little better than it does but
340   probably not enough to be worth the effort.)
341
342   To mitigate this, hterm will display a warning message when your browser
343   zoom is not 100%.  In this mode the Ctrl-Plus, Ctrl-Minus and Ctrl-Zero
344   keys are passed directly to the browser.  Just press Ctrl-Zero to reset your
345   zoom and dismiss the warning.
346
347   hterm should start handling Ctrl-Plus, Ctrl-Minus and Ctrl-Zero on its
348   own once your zoom setting is fixed.
349
350
351 > Why do I get a warning about my browser zoom?
352
353   Because hterm requires you to set your browser to 100%, or 1:1 zoom.
354   Try Ctrl-Zero or the Wrench->Zoom menu to reset your browser zoom.  The
355   warning should go away after you correct the zoom level.
356
357   See the previous question for more information.
358
359
360 > How do I disable anti-aliasing?
361
362   Open the JavaScript console and type...
363
364      term_.prefs_.set('font-smoothing', 'none')
365
366   This directly modifies the '-webkit-font-smoothing' CSS property for the
367   terminal.  As such, 'none', 'antialiased', and 'subpixel-antialiased' are
368   all valid values.
369
370   The default setting is 'antialiased'.
371
372
373 > How do I make the cursor blink?
374
375   Open the JavaScript console and type...
376
377      term_.prefs_.set('cursor-blink', true)
378
379   Notice that true is NOT in quotes.  This is especially important if you try
380   to turn blinking back off, with...
381
382      term_.prefs_.set('cursor-blink', false)
383
384   or you could just revert to the default value of false with...
385
386      term_.prefs_.reset('cursor-blink')
387
388
389 > Why does hterm ignore the cursor blink escape sequence?
390
391   Most terminals ignore attempts by the host to change the blink-state of the
392   cursor.  This lets you choose between a blink/steady cursor via the
393   cursor-blink preference, without having the host change your setting.
394
395   By default, hterm also ignores this escape sequence.  To enable it, set the
396   'enable-dec12' preference to true.
397
398      term_.prefs_.set('enable-dec12', true)
399
400 > How do I change the TERM environment variable?
401
402   Open the JavaScript console and type...
403
404      term_.prefs_.set('environment', {TERM: 'hterm'})
405
406   Notice that only 'hterm' is quoted, not the entire value.  You can replace
407   'hterm' with whichever value you prefer.
408
409   The default TERM value is 'xterm-256color'.  If you prefer to simulate a
410   16 color xterm, try setting TERM to 'xterm'.
411
412   You will have to reconnect for this setting to take effect.
413
414
415 > How do I enter accented characters?
416
417   That depends on your platform and which accented characters you want to
418   enter.
419
420   In xterm, you could use Alt-plus-a-letter-or-number to select from the
421   upper 128 characters.  The palette of 128 characters was "hardcoded" and
422   not dependent on your keyboard locale.  You can set hterm to do the same
423   thing by opening the JavaScript console and typing...
424
425      term_.prefs_.set('alt-sends-what', '8-bit')
426
427   However, if you are on Mac OS X and you prefer that Alt sends a character
428   based on your keyboard locale, try this instead...
429
430      term_.prefs_.set('alt-sends-what', 'browser-key')
431
432   Note that composed characters (those that require multiple keystrokes) are
433   not currently supported by this mode.
434
435   If you are running Chrome OS on a Chromebook you can select your keyboard
436   locale from the system settings and just use the Right-Alt (the small one,
437   on the right) to enter accented characters.  No need to change the
438   'alt-sends-what' preference at all.
439
440   The default value for 'alt-sends-what' is 'escape'.  This makes Alt work
441   mostly like a traditional Meta key.
442
443   If you really, really want Alt to be an alias for the Meta key in every
444   sense, use...
445
446      term_.prefs_.set('alt-is-meta', true)
447
448
449 > How do I make backspace send ^H?
450
451   By default, hterm sends a delete (DEL, '\x7f') character for the
452   backspace key.  Sounds crazy, but it tends to be the right thing for
453   most people.  If you'd prefer it send the backspace (BS, '\x08', aka ^H)
454   character, then open the JavaScript console and type...
455
456      term_.prefs_.set('backspace-sends-backspace', true)
457
458
459 > How do I remove a known host fingerprint (aka known_hosts) entry?
460
461   If you know the index of the offending host entry (it's usually reported
462   by ssh if the connection fails) you can open the JavaScript console and
463   type...
464
465      term_.command.removeKnownHostByIndex(index)
466
467   Replace index with the numeric, one-based host index.
468
469   If you don't know the index, or you'd like to clear all known hosts,
470   type...
471
472      term_.command.removeAllKnownHosts()
473
474
475 > How do I send Ctrl-W, Ctrl-N or Ctrl-T to the terminal?
476
477   Chrome blocks tab contents from getting access to these (and a few other)
478   keys.  You can open Secure Shell in a dedicated window to get around
479   this limitation.  Just right-click on the Secure Shell icon and enable
480   "Open as Window".
481
482   After that, any time you launch Secure Shell it will open in a new window
483   and respond properly to these accelerator keys.
484
485   Note that the "Open as Window" option is not available on the Mac.  However,
486   Mac keyboards typically have distinct Control, Alt, and Command keys, so it's
487   less of an issue on that platform.  Secure Shell cannot treat Command as
488   Control or Meta, but there are some third party keyboard utilities that may
489   provide a solution.
490
491
492 > How do I copy text from the terminal?
493
494   By default, Secure Shell automatically copies your active selection to the
495   clipboard.
496
497   You can disable this by setting the 'copy-on-select' preference to false.
498   If you disable it you'll need to use one of the following key sequences
499   to copy to the clipboard...
500
501   * Under Mac OS X the normal Command-C sequence works.
502
503   * On other platforms Ctrl-C will perform a Copy only when text is selected.
504     When there is no current selection Ctrl-C will send a "^C" to the host.
505
506     Note that after copying text to the clipboard the active selection will be
507     cleared.  If you happen to have text selected but want to send "^C",
508     just hit Ctrl-C twice.
509
510   * Under all platforms you can also use the "Copy" command from the Wrench
511     menu, when running Secure Shell in a browser tab.
512
513
514 > How do I paste text to the terminal?
515
516   By default, Shift-Insert pastes the clipboard on all platforms.  If you'd
517   prefer to be able to send Shift-Insert to the host, set the
518   'shift-insert-paste' preference to false.
519
520   Also...
521
522   * Under Mac OS X the normal Command-V sequence can be used to paste from
523     the clipboard.
524
525   * On other platforms use Ctrl-Shift-V to paste from the clipboard.
526
527   * Under X11, you can use middle-mouse-click to paste from the X clipboard.
528
529   * Under all platforms you can also use the "Paste" command from the Wrench
530     menu.
531
532
533 > Why does the cursor blink in emacs?
534
535   This answer only applies if you've set the 'enable-dec12' preference to true.
536
537   Do you normally use Terminal.app or xterm?  Those terminals (and many others)
538   ignore the "ESC [ ? 12 h" and "ESC [ ? 12 l" sequences (DEC Private Mode 12).
539   Emacs uses these sequences (on purpose) to enable and disable cursor blink.
540
541   If you prefer a steady cursor in emacs, set visible-cursor to nil as
542   described in <http://goo.gl/i9THb>.
543
544
545 > Why does the color scheme look funny in emacs/vi/vim?
546
547   hterm's default value for the TERM environment variable is
548   'xterm-256color'.  This causes emacs, vi, and some other programs to
549   use a different color palette than when TERM='xterm'.
550
551   You may notice these programs use a font color that is difficult to read
552   over a dark background (such as dark blue).
553
554   You can fix vi with ':set bg=dark'.  Emacs can be started in "reverse
555   video" mode with 'emacs -rv'.
556
557   If you just want your old 16 color palette back, open the JavaScript
558   console and type...
559
560      term_.prefs_.set('environment', {TERM: 'xterm'})
561
562   Then restart Secure Shell.
563
564
565 > Can I use my mouse with Secure Shell?
566
567   Sort of.  Both emacs and vi have mouse modes that are compatible with Secure
568   Shell.
569
570   In emacs, use `M-x xterm-mouse-mode` and `M-x mouse-wheel-mode`.  This will
571   allow you to position the cursor with a mouse click, and use the wheel
572   (or two-finger scroll) to scroll the buffer.
573
574   In vi, use ":set mouse=a" to enable mouse mode.  Vi's mouse mode is slightly
575   different from emacs in that it manages your text selection.  Some people
576   prefer this, others may go crazy.
577
578   A quick way to get your native selection back is to set the
579   'mouse-cell-motion-trick' to true.  This will make vi's mouse support
580   essentially the same as emacs.
581
582   With the cell motion trick enabled, you lose the ability to select more
583   than one screenful of text with the mouse.  Instead of using this trick,
584   you may want to script vi so that it sends the current selection to
585   Secure Shell to be copied to the system clipboard.  See the next question
586   for some more information on this.
587
588
589 > Does hterm support the "OSC 52", aka "clipboard operations" sequence?
590
591   Clipboard writing is allowed by default, but you can disable it if you're
592   paranoid.  Set the 'enable-clipboard-write' preference to false to disable
593   the control sequence.
594
595   Clipboard read is not implemented.  Reading is a security hole you probably
596   didn't want anyway.
597
598   Clipboard writes are triggered by an escape sequence from the host.  Here's
599   an example...
600
601     $ echo -e "\x1b]52;c;Y29weXBhc3RhIQ==\x07"
602
603   The sequence "\x1b]52;" identifies this as a clipboard operation.  The "c;"
604   option selects the system clipboard.  "Y29weXBhc3RhIQ==" is the base64 encoded
605   value to place on the clipboard, in this case it's the string "copypasta!".
606   Finally, "\x07" terminates the sequence.
607
608   If you execute this command when 'enable-clipboard-write' on you should see
609   the "Selection Copied" message appear in the terminal, and your system
610   clipboard should contain the text, "copypasta!".
611
612   Note that the specification for OSC 52 mentions destinations other than
613   the "c;" system clipboard.  Hterm treats them all as the system clipboard.
614
615
616 > Can I synchronize my emacs selection with the system clipboard?
617
618   Yes, as long as you're not using tmux.  See ../etc/osc52.el (also,
619   <http://goo.gl/5vWiS>) for the details.
620
621
622 > Is there a way to try early releases of Secure Shell?
623
624   Yes.  First, you need to subscribe to the mailing list mentioned above.
625   Subscribers have access to the "Dev" version in the Chrome Web Store, which
626   is located here: <http://goo.gl/cFZlv>.
627
628   Please keep in mind that the Dev version has gone through significantly less
629   testing than the Beta.  Fortunately, you can install both and switch back
630   to Beta if you have trouble with Dev.
631
632
633 > Where is the source code?
634
635   The hterm source is here: <http://goo.gl/EqrV0>.  This includes the
636   front-end code for Secure Shell.
637
638   The Native Client wrapper around ssh is here: <http://goo.gl/760JC>.
639
640
641 > Is there a change log?
642
643   Yes.  Look under the doc/ directory of the hterm source.
644
645   There are two change logs.  One shows changes to the development version
646   of Secure Shell.  The other shows stable releases.
647
648   In general, the dev series of the form 0.X.Y.Z becomes the stable
649   version 0.X.Y.  So SecureShell-dev-0.7.2.0, 0.7.2.1 and 0.7.2.2 all lead up
650   to SecureShell-0.7.2.
651
652
653 > What if I want to make changes to the source?
654
655   Read the hack.txt file in this directory.