2 .\" shellinaboxd.man -- Make command line applications available as AJAX web applications
3 .\" Copyright (C) 2008-2009 Markus Gutschke <markus@shellinabox.com>
5 .\" This program is free software; you can redistribute it and/or modify
6 .\" it under the terms of the GNU General Public License version 2 as
7 .\" published by the Free Software Foundation.
9 .\" This program is distributed in the hope that it will be useful,
10 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
11 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 .\" GNU General Public License for more details.
14 .\" You should have received a copy of the GNU General Public License along
15 .\" with this program; if not, write to the Free Software Foundation, Inc.,
16 .\" 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
18 .\" In addition to these license terms, the author grants the following
19 .\" additional rights:
21 .\" If you modify this program, or any covered work, by linking or
22 .\" combining it with the OpenSSL project's OpenSSL library (or a
23 .\" modified version of that library), containing parts covered by the
24 .\" terms of the OpenSSL or SSLeay licenses, the author
25 .\" grants you additional permission to convey the resulting work.
26 .\" Corresponding Source for a non-source form of such a combination
27 .\" shall include the source code for the parts of OpenSSL used as well
28 .\" as that of the covered work.
30 .\" You may at your option choose to remove this additional permission from
31 .\" the work, or from any part of it.
33 .\" It is possible to build this program in a way that it loads OpenSSL
34 .\" libraries at run-time. If doing so, the following notices are required
35 .\" by the OpenSSL and SSLeay licenses:
37 .\" This product includes software developed by the OpenSSL Project
38 .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)
40 .\" This product includes cryptographic software written by Eric Young
41 .\" (eay@cryptsoft.com)
44 .\" The most up-to-date version of this program is always available from
45 .\" http://shellinabox.com
47 .TH SHELLINABOXD 1 "Dec 25, 2008"
49 shellinaboxd \- publish command line shell through AJAX interface
53 [\ \fB-b\fP\ | \fB--background\fP[\fB=\fP\fIpidfile\fP]\ ]
54 [\ \fB-c\fP\ | \fB--cert=\fP\fIcertdir\fP\ ]
55 [\ \fB--cert-fd=\fP\fIfd\fP\ ]
56 [\ \fB--cgi\fP[\fB=\fP\fIportrange\fP]\ ]
57 [\ \fB-d\fP\ | \fB--debug\fP\ ]
58 [\ \fB-f\fP\ | \fB--static-file=\fP\fIurl\fP:\fIfile\fP\ ]
59 [\ \fB-g\fP\ | \fB--group=\fP\fIgid\fP\ ]
60 [\ \fB-h\fP\ | \fB--help\fP\ ]
61 [\ \fB--linkify\fP=[\fBnone\fP|\fBnormal\fP|\fBaggressive\fP]\ ]
62 [\ \fB--localhost-only\fP\ ]
64 [\ \fB-n\fP\ | \fB--numeric\fP\ ]
65 [\ \fB-p\fP\ | \fB--port=\fP\fIport\fP\ ]
66 [\ \fB-s\fP\ | \fB--service=\fP\fIservice\fP\ ]
67 [\ \fB-t\fP\ | \fB--disable-ssl\fP\ ]
68 [\ \fB--disable-ssl-menu\fP\ ]
69 [\ \fB-q\fP\ | \fB--quiet\fP\ ]
70 [\ \fB-u\fP\ | \fB--user=\fP\fIuid\fP\ ]
71 [\ \fB-v\fP\ | \fB--verbose\fP\ ]
76 daemon implements a webserver that listens on the specified
78 The web server publishes one or more
80 that will be displayed in a VT100 emulator implemented as an AJAX web
81 application. By default, the port is 4200 and the default service URL is
82 .IR http://localhost:4200/ .
86 was requested, the server launches
88 querying the user for their username and password. It then starts the
89 user's default login shell.
91 Any modern JavaScript and CSS enabled browser will be able to access the
94 without requiring additional plugins.
96 The following command line parameters control the operation of the daemon:
98 \fB-b\fP\ | \fB--background\fP[\fB=\fP\fIpidfile\fP]
101 as a background daemon process. Optionally, write the process id to
104 \fB-c\fP\ |\ \fB--cert=\fP\fIcertdir\fP
105 If built with SSL/TLS support enabled, the daemon will look in
107 for any certificates. If unspecified, this defaults to the current
110 If the browser negotiated a
111 .B Server Name Identification
112 the daemon will look for a matching
113 .I certificate-\f[BI]SERVERNAME\fP.pem
114 file. This allows for virtual hosting of multiple server names on the
115 same IP address and port.
119 handshake took place, it falls back on using the certificate in the
123 The administrator should make sure that there are matching
124 certificates for each of the virtual hosts on this server, and that
129 If no suitable certificate is installed,
131 will attempt to invoke
133 and create a new self-signed certificate. This only succeeds if, after
136 has write permissions for
139 Most browsers show a warning message when encountering a self-signed
140 certificate and then allow the user the option of accepting the
141 certificate. Due to this usability problem, and due to the perceived
142 security implications, the use of auto-generated self-signed
143 certificates is intended for testing or in intranet deployments, only.
145 \fB--cert-fd=\fP\fIfd\fP
146 Instead of providing a
148 directory, it is also possible to provide a filedescriptor
150 where the certificate and key can be retrieved. While this option disables
152 support, it does offer an alternative solution for securely providing
153 the private key data to the daemon.
155 \fB--cgi\fP[\fB=\fP\fIportrange\fP]
158 as a permanent process, it can be demand-loaded as a CGI web server
159 extension. When doing so, it will spawn a server that lives for the
160 duration of the user's session. If an optional
164 has been provided, the server limits itself to these port numbers. They
165 should be configured to pass through the firewall.
169 option is mutually exclusive with the
175 In order to be useful as a CGI script, the
177 binary probably will have to be made
179 This is currently a discouraged configuration. Use with care.
181 \fB-d\fP\ |\ \fB--debug\fP
182 Enables debugging mode, resulting in lots of log messages on
184 This option is mutually exclusive with
189 \fB-f\fP\ |\ \fB--static-file=\fP\fIurl\fP:\fIfile\fP
190 The daemon serves various built-in resources from URLs underneath the
192 mount points. One or more
194 options allow for overriding these resources with customized externally
199 can either be an absolute or a relative path. In the former case, it overrides
200 exactly one built-in resource for one specific
202 whereas in the latter case it overrides resources for each defined
205 The following resources are available for customization:
207 .TP \w'ShellInABox.js\ \ \ 'u
209 audio sample that gets played whenever the terminal BEL is sounded.
212 favicon image file that is displayed in the browser's navigation bar.
215 JavaScript file implementing the AJAX terminal emulator.
218 CSS style file that controls the visual appearance of the terminal.
220 It is not recommended to override the root HTML page for a particular
222 Instead, move the service to an anonymous URL and serve a
231 it is possible to provide the name of a directory. This turns
233 into a simple web server that publishes all of the files in that
234 particular directory. This option can be helpful when publishing a more
235 complex root HTML page.
238 \fB-g\fP\ |\ \fB--group=\fP\fIgid\fP
241 the server drops most privileges at start up. Unless overridden by the
243 option, it switches to
246 When already running as an unprivileged user, group changes are not
249 If running with SSL/TLS support enabled, the certificates must be
250 accessible to the unprivileged user and/or group that the daemon
253 \fB-h\fP\ |\ \fB--help\fP
254 Display a brief usage message showing the valid command line parameters.
256 \fB--linkify\fP=[\fBnone\fP|\fBnormal\fP|\fBaggressive\fP]
257 the daemon attempts to recognize URLs in the terminal output and makes them
258 clickable. This is not neccessarily a fool-proof process and both false
259 negatives and false positives are possible. By default, only URLs starting
260 with a well known protocol of
261 .BR http:// ,\ https:// ,\ ftp:// ,\ or\ mailto:
264 mode, anything that looks like a hostname, URL or e-mail address is
265 recognized, even if not preceded by a protocol.
267 \fB--localhost-only\fP
270 listens on all available network interfaces. When operating behind a
271 reverse-proxy that is not always desirable. This command line option
272 tells the daemon to only listen on the loopback interface.
275 not only are audible signals undesired in some working environments, but
276 browser support for media playback is often buggy, too. Setting this option
277 suppresses all audio playback and enables the visual bell by default.
279 \fB-n\fP\ |\ \fB--numeric\fP
282 mode, the daemon prints an
286 By default, host names of peers get resolved
287 before logging them. As DNS look-ups can be expensive, it is possible
288 to request logging of numeric IP addresses, instead.
290 \fB-p\fP\ |\ \fB--port=\fP\fIport\fP
291 Unless overridden by this option, the web server listens on port 4200
292 for incoming HTTP and HTTPS requests.
295 can distinguish between SSL/TLS requests and unencrypted requests. It
296 also knows how to negotiate
299 allowing the use of a single port for all types of requests even when
302 \fB-s\fP\ |\ \fB--service=\fP\fIservice\fP
303 One or more services can be registered on different URL paths:
305 \fISERVICE\fP := <url-path> ':' \fIAPPLICATON\fP
307 There is one pre-defined \fIapplication\fP, 'LOGIN'. It causes the
310 to request the user's name and password, and to start his
311 login shell. This is the default option, if no
313 was defined. Starting
319 Alternatively, an \fIapplication\fP can be specified by providing a
320 \fIuser\fP description, a working directory, and a command line:
322 \fIAPPLICATION\fP := 'LOGIN' | \fIUSER\fP ':' \fICWD\fP ':' <cmdline>
326 The keyword 'AUTH' indicates that the \fIuser\fP information should
327 be requested interactively, instead of being provided as part of the
328 \fIservice\fP description:
335 <username> ':' <groupname>
338 The working directory can either be given as an absolute path, or it
339 can be the user's home directory:
341 \fICWD\fP := 'HOME' : <dir>
344 The <cmdline> supports expansion of variables of the form ${VAR}.
345 Supported variables are:
347 .TP \w'${columns}\ \ 'u
372 Other than the default environment variables of
377 services can have environment variables passed to them, by preceding
378 the <cmdline> with space separated variable assignments of the form
381 The <cmdline> supports single and double quotes, as well as
382 backslashes for escaping characters in the familiar fashion.
384 Please note that when invoking
386 from a command line shell, additional quoting might be required to
387 prevent the shell from expanding the variables prior to passing them
394 defaults to attaching
396 to the root directory of the web server. This is equivalent to saying
397 .BR --service=/:LOGIN .
400 \fB-t\fP\ |\ \fB--disable-ssl\fP
403 redirectes all incoming HTTP requests to their equivalent HTTPS
404 URLs. If promoting of connections to encrypted SSL/TLS sessions is
405 undesired, this behavior can be disabled.
407 This option is also useful during testing or for deployment in trusted
408 intranets, if SSL certificates are unavailable.
410 \fB--disable-ssl-menu\fP
411 If the user should not be able to switch between HTTP and HTTPS modes, this
412 choice can be removed from the context menu. The user can still make this
413 choice by directly going to the appropriate URL.
415 \fB-q\fP\ |\ \fB--quiet\fP
416 Surpresses all messages to
418 This option is mutually exclusive with
423 \fB-u\fP\ |\ \fB--user=\fP\fIuid\fP
426 the server drops privileges by changing to
430 has been overridden by this option.
432 For more details, refer to the description of the
436 \fB-v\fP\ |\ \fB--verbose\fP
441 This option is mutually exclusive with
447 Prints the version number of the binary and exits.
449 There are no configuration files or permanent settings for
450 .BR shell\%ina\%boxd .
451 A small number of run-time configuration options are available from a
452 context menu that becomes available when clicking the right mouse button.
454 .TP \w'shellinaboxd\ 'u
456 Attaches a web-enabled login shell to
457 .I http://localhost:4200/
458 with SSL/TLS support disabled. This command must be run as
460 or the attempt to launch
464 .B shellinaboxd -t -f beep.wav:/dev/null
465 Runs all services with the audible-bell permanently disabled.
467 .B shellinaboxd -t -s /:AUTH:HOME:/bin/bash
468 Interactively request the user's name and password prior to launching
469 a Bourne shell. This command can be run by unprivileged users. But if
470 doing so, it only allows this particular user to log in.
472 .B shellinaboxd -c certificates -u shellinabox -g shellinabox
475 directory exists and is writable by the
477 user and group, self-signed SSL certificates will be generated in this
478 directory. This might require creating an appropriately named user first.
479 Running this command as
481 allows any user on the system to log in at
482 .BR http://localhost:4200/ .
483 Sessions will automatically be promoted to SSL/TLS.
485 .B shellinaboxd -t -s /:LOGIN -s /who:nobody:nogroup:/:w
486 In addition to the login shell at
487 .IR http://localhost:4200 ,
488 show a list of currently logged in users when accessing
489 .IR http://localhost:4200/who .
490 This command must be run as
492 in order to be able to change to
494 as requested by the service description.
496 .B shellinaboxd -t -s '/:root:root:/:wy60 -c /bin/login'
497 Instead of the standard
501 terminal. Again, this command should be run as
505 The daemon returns a non-zero exit code in case of failure. With the
506 exception of a small number of common error cases that are handled
507 explicitly, most errors result in printing a
508 .I \(dqCheck failed\(dq
509 message. This does not typically indicate a bug in the program but is
510 instead its normal way of reporting errors.
512 Common failure conditions are reusing a port that is already in use,
513 lack of sufficient privileges to run a service, failure to find
514 SSL/TLS certificates, and failure to write newly generated
515 certificates to the certification directory.
527 The daemon uses privilege separation techniques to allow it to drop
528 privileges early. It is aware of setuid flags and restricts some
529 operations when launched as a setuid application.
531 Despite these safety features, a bug could conceivably lead to a
532 determined attacker gaining elevated privileges. It is therefore
533 strongly discouraged to set the setuid flag on the binary.
535 The expected deployment would be from a system
539 For extra security, the
543 options should be used to change to a dedicated user.
545 Copyright (C) 2008-2009 by Markus Gutschke
546 .RI < "markus@shellinabox.com" >.
548 This program is free software; you can redistribute it and/or modify
549 it under the terms of the GNU General Public License version 2 as
550 published by the Free Software Foundation.
552 This program is distributed in the hope that it will be useful,
553 but WITHOUT ANY WARRANTY; without even the implied warranty of
554 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
555 GNU General Public License for more details.
557 You should have received a copy of the GNU General Public License
558 along with this program; if not, write to the Free Software
559 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
562 In addition to these license terms, the author grants the following
565 If you modify this program, or any covered work, by linking or
566 combining it with the OpenSSL project's OpenSSL library (or a
567 modified version of that library), containing parts covered by the
568 terms of the OpenSSL or SSLeay licenses, the author
569 grants you additional permission to convey the resulting work.
570 Corresponding Source for a non-source form of such a combination
571 shall include the source code for the parts of OpenSSL used as well
572 as that of the covered work.
574 You may at your option choose to remove this additional permission from
575 the work, or from any part of it.
577 If you would like to negotiate different licensing terms that are
578 compatible for integration with other projects, please contact the
583 system libraries can be found at run-time, they will be invoked by
585 to provide SSL/TLS support. The OpenSSL and SSLeay
586 licenses require the following notices:
588 This product includes software developed by the OpenSSL Project
589 for use in the OpenSSL Toolkit. (http://www.openssl.org/)
591 This product includes cryptographic software written by Eric Young
595 Due to browser limitations, some features might not be available to
596 users of all browers.
598 Konqueror does not allow for reliable interception of
600 keys. If you press a key together with the
602 modifier, it continues performing the browser's predefined behavior for
603 this particular key combination. In most cases, it also fails to report
604 the correct key to the terminal emulator. As a work-around, pressing
611 Some browsers, most notably IE on Windows, disallow interception of
613 keys and always interpret these keys as menu accelerators. As a
614 work-around, many UNIX applications allow pressing
619 When using non-US keyboard layouts, some browser do not allow for
620 reliably determining shifted
622 keys. Please report these cases if they turn out to be a problem, as
623 work-arounds might be possible.
625 Access to the native clipboard is typically not possible. Instead, an
626 internal clipboard accessible from the right-button context menu is used
629 Some browsers restrict the number of concurrent connections to a
630 server. This restricts how many AJAX terminals can be opened
631 simultaneously. If this becomes a problem, users can typically
632 reconfigure their browsers to raise the limit.
634 There have been reports of the VLC plugin on Linux/x86_64 crashing Firefox
635 when the browser page gets reloaded. Setting the
637 option eliminates all references to VLC and thus appears to work around
andersk / test.git / blob