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]\ ]
55 [\ \fB-c\fP\ | \fB--cert=\fP\fIcertdir\fP\ ]
57 [\ \fB--cert-fd=\fP\fIfd\fP\ ]
58 [\ \fB--cgi\fP[\fB=\fP\fIportrange\fP]\ ]
59 [\ \fB-d\fP\ | \fB--debug\fP\ ]
60 [\ \fB-f\fP\ | \fB--static-file=\fP\fIurl\fP:\fIfile\fP\ ]
61 [\ \fB-g\fP\ | \fB--group=\fP\fIgid\fP\ ]
62 [\ \fB-h\fP\ | \fB--help\fP\ ]
63 [\ \fB--linkify\fP=[\fBnone\fP|\fBnormal\fP|\fBaggressive\fP]\ ]
64 [\ \fB--localhost-only\fP\ ]
66 [\ \fB-n\fP\ | \fB--numeric\fP\ ]
67 [\ \fB-p\fP\ | \fB--port=\fP\fIport\fP\ ]
68 [\ \fB-s\fP\ | \fB--service=\fP\fIservice\fP\ ]
70 [\ \fB-t\fP\ | \fB--disable-ssl\fP\ ]
72 [\ \fB--disable-ssl-menu\fP\ ]
73 [\ \fB-q\fP\ | \fB--quiet\fP\ ]
74 [\ \fB-u\fP\ | \fB--user=\fP\fIuid\fP\ ]
75 [\ \fB-v\fP\ | \fB--verbose\fP\ ]
80 daemon implements a webserver that listens on the specified
82 The web server publishes one or more
84 that will be displayed in a VT100 emulator implemented as an AJAX web
85 application. By default, the port is 4200 and the default service URL is
86 .IR http://localhost:4200/ .
90 was requested, the server launches
92 querying the user for their username and password. It then starts the
93 user's default login shell.
95 Any modern JavaScript and CSS enabled browser will be able to access the
98 without requiring additional plugins.
100 The following command line parameters control the operation of the daemon:
102 \fB-b\fP\ | \fB--background\fP[\fB=\fP\fIpidfile\fP]
105 as a background daemon process. Optionally, write the process id to
109 \fB-c\fP\ |\ \fB--cert=\fP\fIcertdir\fP
110 If built with SSL/TLS support enabled, the daemon will look in
112 for any certificates. If unspecified, this defaults to the current
115 If the browser negotiated a
116 .B Server Name Identification
117 the daemon will look for a matching
118 .I certificate-\f[BI]SERVERNAME\fP.pem
119 file. This allows for virtual hosting of multiple server names on the
120 same IP address and port.
124 handshake took place, it falls back on using the certificate in the
128 The administrator should make sure that there are matching
129 certificates for each of the virtual hosts on this server, and that
134 If no suitable certificate is installed,
136 will attempt to invoke
138 and create a new self-signed certificate. This only succeeds if, after
141 has write permissions for
144 Most browsers show a warning message when encountering a self-signed
145 certificate and then allow the user the option of accepting the
146 certificate. Due to this usability problem, and due to the perceived
147 security implications, the use of auto-generated self-signed
148 certificates is intended for testing or in intranet deployments, only.
150 \fB--cert-fd=\fP\fIfd\fP
151 Instead of providing a
153 directory, it is also possible to provide a filedescriptor
155 where the certificate and key can be retrieved. While this option disables
157 support, it does offer an alternative solution for securely providing
158 the private key data to the daemon.
161 \fB--cgi\fP[\fB=\fP\fIportrange\fP]
164 as a permanent process, it can be demand-loaded as a CGI web server
165 extension. When doing so, it will spawn a server that lives for the
166 duration of the user's session. If an optional
170 has been provided, the server limits itself to these port numbers. They
171 should be configured to pass through the firewall.
175 option is mutually exclusive with the
181 In order to be useful as a CGI script, the
183 binary probably will have to be made
185 This is currently a discouraged configuration. Use with care.
187 \fB-d\fP\ |\ \fB--debug\fP
188 Enables debugging mode, resulting in lots of log messages on
190 This option is mutually exclusive with
195 \fB-f\fP\ |\ \fB--static-file=\fP\fIurl\fP:\fIfile\fP
196 The daemon serves various built-in resources from URLs underneath the
198 mount points. One or more
200 options allow for overriding these resources with customized externally
205 can either be an absolute or a relative path. In the former case, it overrides
206 exactly one built-in resource for one specific
208 whereas in the latter case it overrides resources for each defined
211 The following resources are available for customization:
213 .TP \w'ShellInABox.js\ \ \ 'u
215 audio sample that gets played whenever the terminal BEL is sounded.
218 favicon image file that is displayed in the browser's navigation bar.
221 JavaScript file implementing the AJAX terminal emulator.
224 CSS style file that controls the visual appearance of the terminal.
226 It is not recommended to override the root HTML page for a particular
228 Instead, move the service to an anonymous URL and serve a
237 it is possible to provide the name of a directory. This turns
239 into a simple web server that publishes all of the files in that
240 particular directory. This option can be helpful when publishing a more
241 complex root HTML page.
244 \fB-g\fP\ |\ \fB--group=\fP\fIgid\fP
247 the server drops most privileges at start up. Unless overridden by the
249 option, it switches to
252 When already running as an unprivileged user, group changes are not
255 If running with SSL/TLS support enabled, the certificates must be
256 accessible to the unprivileged user and/or group that the daemon
259 \fB-h\fP\ |\ \fB--help\fP
260 Display a brief usage message showing the valid command line parameters.
262 \fB--linkify\fP=[\fBnone\fP|\fBnormal\fP|\fBaggressive\fP]
263 the daemon attempts to recognize URLs in the terminal output and makes them
264 clickable. This is not neccessarily a fool-proof process and both false
265 negatives and false positives are possible. By default, only URLs starting
266 with a well known protocol of
267 .BR http:// ,\ https:// ,\ ftp:// ,\ or\ mailto:
270 mode, anything that looks like a hostname, URL or e-mail address is
271 recognized, even if not preceded by a protocol.
273 \fB--localhost-only\fP
276 listens on all available network interfaces. When operating behind a
277 reverse-proxy that is not always desirable. This command line option
278 tells the daemon to only listen on the loopback interface.
281 not only are audible signals undesired in some working environments, but
282 browser support for media playback is often buggy, too. Setting this option
283 suppresses all audio playback and enables the visual bell by default.
285 \fB-n\fP\ |\ \fB--numeric\fP
288 mode, the daemon prints an
292 By default, host names of peers get resolved
293 before logging them. As DNS look-ups can be expensive, it is possible
294 to request logging of numeric IP addresses, instead.
296 \fB-p\fP\ |\ \fB--port=\fP\fIport\fP
297 Unless overridden by this option, the web server listens on port 4200
298 for incoming HTTP and HTTPS requests.
301 can distinguish between SSL/TLS requests and unencrypted requests. It
302 also knows how to negotiate
305 allowing the use of a single port for all types of requests even when
308 \fB-s\fP\ |\ \fB--service=\fP\fIservice\fP
309 One or more services can be registered on different URL paths:
311 \fISERVICE\fP := <url-path> ':' \fIAPPLICATION\fP
314 There is a pre-defined \fIapplication\fP, 'LOGIN', which causes the
317 requesting the user's name and password, and starting his
318 login shell. This is the default option for the
322 was defined. Starting
328 There is another pre-defined \fIapplication\fP, 'SSH'. Instead of invoking
332 This is the default option for unprivileged users, if no
334 was defined. This operation is available to both privileged and regular
335 users. If the optional \fIhost\fP parameter is omitted,
340 Alternatively, an \fIapplication\fP can be specified by providing a
341 \fIuser\fP description, a working directory, and a command line:
343 \fIAPPLICATION\fP := 'LOGIN' | 'SSH' [ ':' <host> ] | \fIUSER\fP ':' \fICWD\fP ':' <cmdline>
347 The keyword 'AUTH' indicates that the \fIuser\fP information should
348 be requested interactively, instead of being provided as part of the
349 \fIservice\fP description:
353 \fIUSER\fP := 'AUTH' |
358 <username> ':' <groupname>
361 The working directory can either be given as an absolute path, or it
362 can be the user's home directory:
364 \fICWD\fP := 'HOME' : <dir>
367 The <cmdline> supports expansion of variables of the form ${VAR}.
368 Supported variables are:
370 .TP \w'${columns}\ \ 'u
395 Other than the default environment variables of
400 services can have environment variables passed to them, by preceding
401 the <cmdline> with space separated variable assignments of the form
404 The <cmdline> supports single and double quotes, as well as
405 backslashes for escaping characters in the familiar fashion.
407 Please note that when invoking
409 from a command line shell, additional quoting might be required to
410 prevent the shell from expanding the variables prior to passing them
417 defaults to attaching the default service to the root directory of the web
422 and for unprivileged users, this is \fBssh localhost\fP. This is equivalent
424 .BR --service=/:LOGIN ,
426 .BR --service=/:SSH ,
431 \fB-t\fP\ |\ \fB--disable-ssl\fP
434 redirectes all incoming HTTP requests to their equivalent HTTPS
435 URLs. If promoting of connections to encrypted SSL/TLS sessions is
436 undesired, this behavior can be disabled.
438 This option is also useful during testing or for deployment in trusted
439 intranets, if SSL certificates are unavailable.
442 \fB--disable-ssl-menu\fP
443 If the user should not be able to switch between HTTP and HTTPS modes, this
444 choice can be removed from the context menu. The user can still make this
445 choice by directly going to the appropriate URL.
447 \fB-q\fP\ |\ \fB--quiet\fP
448 Surpresses all messages to
450 This option is mutually exclusive with
455 \fB-u\fP\ |\ \fB--user=\fP\fIuid\fP
458 the server drops privileges by changing to
462 has been overridden by this option.
464 For more details, refer to the description of the
468 \fB-v\fP\ |\ \fB--verbose\fP
473 This option is mutually exclusive with
479 Prints the version number of the binary and exits.
481 There are no configuration files or permanent settings for
482 .BR shell\%ina\%boxd .
483 A small number of run-time configuration options are available from a
484 context menu that becomes available when clicking the right mouse button.
486 .TP \w'shellinaboxd\ 'u
488 Attaches a web-enabled login shell to
489 .I http://localhost:4200/
490 with SSL/TLS support disabled. This command must be run as
492 or the attempt to launch
496 .B shellinaboxd -t -f beep.wav:/dev/null
497 Runs all services with the audible-bell permanently disabled.
499 .B shellinaboxd -t -s /:AUTH:HOME:/bin/bash
500 Interactively request the user's name and password prior to launching
501 a Bourne shell. This command can be run by unprivileged users. But if
502 doing so, it only allows this particular user to log in.
504 .B shellinaboxd -c certificates -u shellinabox -g shellinabox
507 directory exists and is writable by the
509 user and group, self-signed SSL certificates will be generated in this
510 directory. This might require creating an appropriately named user first.
511 Running this command as
513 allows any user on the system to log in at
514 .BR http://localhost:4200/ .
515 Sessions will automatically be promoted to SSL/TLS.
517 .B shellinaboxd -t -s /:LOGIN -s /who:nobody:nogroup:/:w
518 In addition to the login shell at
519 .IR http://localhost:4200 ,
520 show a list of currently logged in users when accessing
521 .IR http://localhost:4200/who .
522 This command must be run as
524 in order to be able to change to
526 as requested by the service description.
528 .B shellinaboxd -t -s '/:root:root:/:wy60 -c /bin/login'
529 Instead of the standard
533 terminal. Again, this command should be run as
537 The daemon returns a non-zero exit code in case of failure. With the
538 exception of a small number of common error cases that are handled
539 explicitly, most errors result in printing a
540 .I \(dqCheck failed\(dq
541 message. This does not typically indicate a bug in the program but is
542 instead its normal way of reporting errors.
544 Common failure conditions are reusing a port that is already in use,
545 lack of sufficient privileges to run a service, failure to find
546 SSL/TLS certificates, and failure to write newly generated
547 certificates to the certification directory.
559 The daemon uses privilege separation techniques to allow it to drop
560 privileges early. It is aware of setuid flags and restricts some
561 operations when launched as a setuid application.
563 Despite these safety features, a bug could conceivably lead to a
564 determined attacker gaining elevated privileges. It is therefore
565 strongly discouraged to set the setuid flag on the binary.
567 The expected deployment would be from a system
571 For extra security, the
575 options should be used to change to a dedicated user.
577 Copyright (C) 2008-2009 by Markus Gutschke
578 .RI < "markus@shellinabox.com" >.
580 This program is free software; you can redistribute it and/or modify
581 it under the terms of the GNU General Public License version 2 as
582 published by the Free Software Foundation.
584 This program is distributed in the hope that it will be useful,
585 but WITHOUT ANY WARRANTY; without even the implied warranty of
586 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
587 GNU General Public License for more details.
589 You should have received a copy of the GNU General Public License
590 along with this program; if not, write to the Free Software
591 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
594 In addition to these license terms, the author grants the following
597 If you modify this program, or any covered work, by linking or
598 combining it with the OpenSSL project's OpenSSL library (or a
599 modified version of that library), containing parts covered by the
600 terms of the OpenSSL or SSLeay licenses, the author
601 grants you additional permission to convey the resulting work.
602 Corresponding Source for a non-source form of such a combination
603 shall include the source code for the parts of OpenSSL used as well
604 as that of the covered work.
606 You may at your option choose to remove this additional permission from
607 the work, or from any part of it.
609 If you would like to negotiate different licensing terms that are
610 compatible for integration with other projects, please contact the
615 system libraries can be found at run-time, they will be invoked by
617 to provide SSL/TLS support. The OpenSSL and SSLeay
618 licenses require the following notices:
620 This product includes software developed by the OpenSSL Project
621 for use in the OpenSSL Toolkit. (http://www.openssl.org/)
623 This product includes cryptographic software written by Eric Young
627 Due to browser limitations, some features might not be available to
628 users of all browers.
630 Konqueror does not allow for reliable interception of
632 keys. If you press a key together with the
634 modifier, it continues performing the browser's predefined behavior for
635 this particular key combination. In most cases, it also fails to report
636 the correct key to the terminal emulator. As a work-around, pressing
643 Some browsers, most notably IE on Windows, disallow interception of
645 keys and always interpret these keys as menu accelerators. As a
646 work-around, many UNIX applications allow pressing
651 When using non-US keyboard layouts, some browser do not allow for
652 reliably determining shifted
654 keys. Please report these cases if they turn out to be a problem, as
655 work-arounds might be possible.
657 Access to the native clipboard is typically not possible. Instead, an
658 internal clipboard accessible from the right-button context menu is used
661 Some browsers restrict the number of concurrent connections to a
662 server. This restricts how many AJAX terminals can be opened
663 simultaneously. If this becomes a problem, users can typically
664 reconfigure their browsers to raise the limit.
666 There have been reports of the VLC plugin on Linux/x86_64 crashing Firefox
667 when the browser page gets reloaded. Setting the
669 option eliminates all references to VLC and thus appears to work around
andersk / test.git / blob