1SHELLINABOXD(1) General Commands Manual SHELLINABOXD(1)
2
6 shellinaboxd - publish command line shell through AJAX interface
7
9 shellinaboxd
10 [ -b | --background[=pidfile] ] [ -c | --cert=certdir ]
11 [ --cert-fd=fd ] [ --css=filename ] [ --cgi[=portrange] ] [ -d |
12 --debug ] [ -f | --static-file=url:file ] [ -g | --group=gid ]
13 [ -h | --help ] [ --linkify=[none|normal|aggressive] ]
14 [ --localhost-only ] [ --no-beep ] [ -n | --numeric ] [ --pid‐
15 file=pidfile ] [ -p | --port=port ] [ -s | --service=service ]
16 [ -t | --disable-ssl ] [ --disable-ssl-menu ] [ -q | --quiet ]
17 [ -u | --user=uid ] [ --user-css=styles ] [ -v | --verbose ]
18 [ --version ]
19
21 The shellinaboxd daemon implements a webserver that listens on the
22 specified port. The web server publishes one or more services that
23 will be displayed in a VT100 emulator implemented as an AJAX web appli‐
24 cation. By default, the port is 4200 and the default service URL is
25 http://localhost:4200/.
26 If no particular service was requested, the server launches /bin/login
28 querying the user for their username and password. It then starts the
29 user's default login shell.
30 Any modern JavaScript and CSS enabled browser will be able to access
32 the published service without requiring additional plugins.
33
35 The following command line parameters control the operation of the dae‐
36 mon:
37 -b | --background[=pidfile]
39 Launch shellinaboxd as a background daemon process. Optionally,
40 write the process id to pidfile.
41 -c | --cert=certdir
43 If built with SSL/TLS support enabled, the daemon will look in
44 certdir for any certificates. If unspecified, this defaults to the
45 current working directory.
46 If the browser negotiated a Server Name Identification the daemon
48 will look for a matching certificate-SERVERNAME.pem file. This
49 allows for virtual hosting of multiple server names on the same IP
50 address and port.
51 If no SNI handshake took place, it falls back on using the cer‐
53 tificate in the certificate.pem file.
54 The administrator should make sure that there are matching cer‐
56 tificates for each of the virtual hosts on this server, and that
57 there is a generic certificate.pem file.
58 If no suitable certificate is installed, shellinaboxd will attempt
60 to invoke /usr/bin/openssl and create a new self-signed certifi‐
61 cate. This only succeeds if, after dropping privileges, shellina‐
62 boxd has write permissions for certdir.
63 Most browsers show a warning message when encountering a self-
65 signed certificate and then allow the user the option of accepting
66 the certificate. Due to this usability problem, and due to the
67 perceived security implications, the use of auto-generated self-
68 signed certificates is intended for testing or in intranet deploy‐
69 ments, only.
70 --cert-fd=fd
72 Instead of providing a --cert directory, it is also possible to
73 provide a filedescriptor fd where the certificate and key can be
74 retrieved. While this option disables SNI support, it does offer
75 an alternative solution for securely providing the private key
76 data to the daemon.
77 --css=filename
79 Sometimes, it is not necessary to replace the entire style sheet
80 using the --static-file option. But instead a small incremental
81 change should be made to the visual appearance of the terminal.
82 The --css option provides a means to append additional style rules
83 to the end of the default styles.css sheet. More than one --css
84 option can be given on the same command line.
85 --cgi[=portrange]
87 Instead of running shellinaboxd as a permanent process, it can be
88 demand-loaded as a CGI web server extension. When doing so, it
89 will spawn a server that lives for the duration of the user's ses‐
90 sion. If an optional portrange of the form MINPORT-MAXPORT has
91 been provided, the server limits itself to these port numbers.
92 They should be configured to pass through the firewall.
93 The --cgi option is mutually exclusive with the --background,
95 --pidfile and --port options.
96 In order to be useful as a CGI script, the shellinaboxd binary
98 probably will have to be made setuid-root. This is currently a
99 discouraged configuration. Use with care.
100 -d | --debug
102 Enables debugging mode, resulting in lots of log messages on
103 stderr. This option is mutually exclusive with --quiet and --ver‐
104 bose.
105 -f | --static-file=url:file
107 The daemon serves various built-in resources from URLs underneath
108 the service mount points. One or more --static-file options allow
109 for overriding these resources with customized externally provided
110 files. The url can either be an absolute or a relative path. In
111 the former case, it overrides exactly one built-in resource for
112 one specific service, whereas in the latter case it overrides
113 resources for each defined service.
114 The following resources are available for customization:
116 beep.wav audio sample that gets played whenever the termi‐
118 nal BEL is sounded.
119 favicon.ico favicon image file that is displayed in the
121 browser's navigation bar.
122 ShellInABox.js JavaScript file implementing the AJAX terminal
124 emulator.
125 styles.css CSS style file that controls the visual appear‐
127 ance of the terminal.
128 print-styles.css CSS style file that controls the visual appear‐
130 ance of printed pages when using the VT100 trans‐
131 parent printing feature.
132 It is not recommended to override the root HTML page for a partic‐
134 ular service. Instead, move the service to an anonymous URL and
135 serve a static-file that references the service in an <iframe>.
136 Instead of a file, it is possible to provide the name of a direc‐
138 tory. This turns shellinaboxd into a simple web server that pub‐
139 lishes all of the files in that particular directory. This option
140 can be helpful when publishing a more complex root HTML page.
141 -g | --group=gid
143 When started as root, the server drops most privileges at start
144 up. Unless overridden by the --group option, it switches to
145 nogroup.
146 When already running as an unprivileged user, group changes are
148 not possible.
149 If running with SSL/TLS support enabled, the certificates must be
151 accessible to the unprivileged user and/or group that the daemon
152 runs as.
153 -h | --help
155 Display a brief usage message showing the valid command line
156 parameters.
157 --linkify=[none|normal|aggressive]
159 the daemon attempts to recognize URLs in the terminal output and
160 makes them clickable. This is not necessarily a fool-proof process
161 and both false negatives and false positives are possible. By
162 default, only URLs starting with a well known protocol of
163 http://, https://, ftp://, or mailto: are recognized. In aggres‐
164 sive mode, anything that looks like a hostname, URL or e-mail
165 address is recognized, even if not preceded by a protocol.
166 --localhost-only
168 Normally, shellinaboxd listens on all available network inter‐
169 faces. When operating behind a reverse-proxy that is not always
170 desirable. This command line option tells the daemon to only lis‐
171 ten on the loopback interface.
172 --no-beep
174 not only are audible signals undesired in some working environ‐
175 ments, but browser support for media playback is often buggy, too.
176 Setting this option suppresses all audio playback and enables the
177 visual bell by default.
178 -n | --numeric
180 When running in --verbose mode, the daemon prints an Apache-style
181 log file to stderr. By default, host names of peers get resolved
182 before logging them. As DNS look-ups can be expensive, it is pos‐
183 sible to request logging of numeric IP addresses, instead.
184 --pidfile=pidfile
186 The shellinaboxd daemon can be configured to store its process
187 identifier in pidfile.
188 -p | --port=port
190 Unless overridden by this option, the web server listens on port
191 4200 for incoming HTTP and HTTPS requests.
192 shellinaboxd can distinguish between SSL/TLS requests and unen‐
194 crypted requests. It also knows how to negotiate Server Name Iden‐
195 tification, allowing the use of a single port for all types of
196 requests even when virtual hosting.
197 -s | --service=service
199 One or more services can be registered on different URL paths:
200 SERVICE := <url-path> ':' APPLICATION
201 There is a pre-defined application, 'LOGIN', which causes the dae‐
203 mon to invoke /bin/login requesting the user's name and password,
204 and starting his login shell. This is the default option for the
205 root user, if no --service was defined. Starting /bin/login
206 requires root privileges.
207 There is another pre-defined application, 'SSH'. Instead of
209 invoking /bin/login, it calls ssh. This is the default option for
210 unprivileged users, if no --service was defined. This operation is
211 available to both privileged and regular users. If the optional
212 host parameter is omitted, shellinaboxd connects to localhost.
213 Alternatively, an application can be specified by providing a user
215 description, a working directory, and a command line:
216 APPLICATION := 'LOGIN' | 'SSH' [ ':' <host> ] | USER ':' CWD
217 ':' CMD
218 USER := <username> ':' <groupname>
220 The working directory can either be given as an absolute path, or
222 it can be the user's home directory:
223 CWD := 'HOME' : <dir>
224 The command that shellinaboxd executes can either be specified as
226 the 'SHELL' keyword, denoting the user's default login shell, or
227 an arbitrary command line:
228 CMD := 'SHELL' : <cmdline>
229 The <cmdline> supports expansion of variables of the form ${VAR}.
231 Supported variables are:
232 ${columns} number of columns.
234 ${gid} numeric group id.
236 ${group} group name.
238 ${home} home directory.
240 ${lines} number of rows.
242 ${peer} name of remote peer.
244 ${realip} value of HTTP header field 'X-Real-IP'.
246 ${uid} numeric user id.
248 ${url} the URL that serves the terminal session.
250 ${user} user name.
252 Other than the environment variables of $TERM, $COLUMNS, $LINES,
254 $SHELLINABOX_PEERNAME, $SHELLINABOX_REALIP and $SHELLINABOX_URL,
255 services can have environment variables passed to them, by preced‐
256 ing the <cmdline> with space separated variable assignments of the
257 form KEY=VALUE.
258 The <cmdline> supports single and double quotes, as well as back‐
260 slashes for escaping characters in the familiar fashion.
261 Please note that when invoking shellinaboxd from a command line
263 shell, additional quoting might be required to prevent the shell
264 from expanding the variables prior to passing them to the daemon.
265 If no explicit --service has been requested, shellinaboxd defaults
267 to attaching the default service to the root directory of the web
268 server. For root, this is /bin/login, and for unprivileged users,
269 this is ssh localhost. This is equivalent to saying --ser‐
270 vice=/:LOGIN, or --service=/:SSH, respectively.
271 Please note that for SSH service to work properly, we need a run‐
273 ning ssh server on local system with enabled password authentica‐
274 tion. If we are using <host> parameter, same conditions must be
275 true on that remote system.
276 -t | --disable-ssl
279 By default, shellinaboxd redirectes all incoming HTTP requests to
280 their equivalent HTTPS URLs. If promoting of connections to
281 encrypted SSL/TLS sessions is undesired, this behavior can be dis‐
282 abled.
283 This option is also useful during testing or for deployment in
285 trusted intranets, if SSL certificates are unavailable.
286 --disable-ssl-menu
288 If the user should not be able to switch between HTTP and HTTPS
289 modes, this choice can be removed from the context menu. The user
290 can still make this choice by directly going to the appropriate
291 URL.
292 -q | --quiet
294 Suppresses all messages to stderr. This option is mutually exclu‐
295 sive with --debug and --verbose.
296 -u | --user=uid
298 If started as root, the server drops privileges by changing to
299 nobody, unless the uid has been overridden by this option.
300 For more details, refer to the description of the --group option.
302 --user-css=styles
304 The visual appearance of the terminal emulator can be customized
305 through user-selectable style sheets. These style sheets will show
306 up as options in the right-click context menu of the terminal emu‐
307 lator.
308 Styles sheet make up either independently selectable on/off
310 options, or multiple style sheets can be grouped together. When
311 forming a group, only one member of the group can be active at any
312 given time. This is used for multiple-choice options.
313 Multiple independent groups are separated by semicolons:
315 STYLES := GROUP { ';' GROUP }*
316 The members of a group are separated by commas:
318 GROUP := OPTION { ',' OPTION }*
319 Groups with exactly one member are used for options that can be
321 independently turned on and off.
322 Options include a human readable label that will be shown in the
324 context menu, followed by the name of the CSS file. They also must
325 include an indicator showing whether the option should initially
326 be turned on or turned off. Within a group, exactly one option
327 should be turned on:
328 OPTION := <label> ':' [ '-' | '+' ] <css-file>
329 The user's selection of options will be persisted in a cookie.
331 This means, the default settings of options as passed on the com‐
332 mand line only takes effect the very first time the user visits
333 the terminal emulator in his browser. On all subsequent visits,
334 the user's preferences take precedence.
335 -v | --verbose
337 Enables logging of Apache-style log file to stderr. This option
338 is mutually exclusive with --debug and --quiet.
339 --version
341 Prints the version number of the binary and exits.
342
344 There are no configuration files or permanent settings for shellina‐
345 boxd.
346 A small number of run-time configuration options are available from a
348 context menu that becomes available when clicking the right mouse but‐
349 ton. These options get persisted in a browser cookie.
350 Many sites already have a web server running and would like to inte‐
352 grate shellinaboxd into their existing site. This is most commonly done
353 by means of a reverse-proxy entry for the main web server. For Apache
354 this would require adding an option such as:
355 <Location /shell>
356 ProxyPass http://localhost:4200/
357 Order allow,deny
358 Allow from all
359 </Location>
360 If you are using a different web server, refer to that server's docu‐
362 mentation on how to configure reverse proxy operations.
363 When using a reverse proxy, the --localhost-only option would normally
365 be enabled as well. In addition, the --disable-ssl might also be con‐
366 sidered depending on the exact configuration details of the reverse
367 proxy.
368
370 shellinaboxd Attaches a web-enabled login shell to https://local‐
371 host:4200/. If the user connected without SSL, the ses‐
372 sion will automatically be promoted. Unless SSL certifi‐
373 cates can be found in the current directory, the daemon
374 will automatically generate suitable self-signed certifi‐
375 cates. If the command was invoked by a non-root user, the
376 daemon uses ssh instead of /bin/login for the session.
377 shellinaboxd -t
379 Attaches a web-enabled login shell to http://local‐
380 host:4200/ with SSL/TLS support disabled.
381 shellinaboxd -t -f beep.wav:/dev/null
383 Runs all services with the audible-bell permanently dis‐
384 abled.
385 shellinaboxd -s /:SSH:example.org
387 The terminal connects to a ssh session on example.org.
388 shellinaboxd -t -s /:AUTH:HOME:/bin/bash
390 Interactively request the user's name and password prior
391 to launching a Bourne shell. This command can be run by
392 unprivileged users. But if doing so, it only allows this
393 particular user to log in.
394 shellinaboxd -c certificates -u shellinabox -g shellinabox
396 If the certificates directory exists and is writable by
397 the shellinabox user and group, self-signed SSL certifi‐
398 cates will be generated in this directory. This might
399 require creating an appropriately named user first. Run‐
400 ning this command as root allows any user on the system to
401 log in at http://localhost:4200/. Sessions will automati‐
402 cally be promoted to SSL/TLS.
403 shellinaboxd -t -s /:LOGIN -s /who:nobody:nogroup:/:w
405 In addition to the login shell at http://localhost:4200,
406 show a list of currently logged in users when accessing
407 http://localhost:4200/who. This command must be run as
408 root in order to be able to change to nobody:nogroup as
409 requested by the service description.
410 shellinaboxd -t -s '/:root:root:/:wy60 -c /bin/login'
412 Instead of the standard ANSI/VT100 terminal, publish a
413 Wyse 60™ terminal. Again, this command should be run as
414 root.
415 shellinaboxd --css white-on-black.css
417 Loads the white-on-black.css style sheet from the current
418 directory and appends it to the built-in styles.css sheet.
419 This causes the terminal to always render white text on a
420 black background.
421 shellinaboxd --user-css Normal:+black-on-white.css,Reverse:-white-on-
423 black.css
424 Allow the user to select whether they want text to be ren‐
425 dered normally or in reverse video. This command line
426 option adds a new entry to the right-click context menu.
427
429 The daemon returns a non-zero exit code in case of failure. With the
430 exception of a small number of common error cases that are handled
431 explicitly, most errors result in printing a "Check failed" message.
432 This does not typically indicate a bug in the program but is instead
433 its normal way of reporting errors.
434 Common failure conditions are reusing a port that is already in use,
436 lack of sufficient privileges to run a service, failure to find SSL/TLS
437 certificates, and failure to write newly generated certificates to the
438 certification directory.
439
441 chmod(1), last(1), login(1), sh(1), shells(5), openssl(1SSL), w(1),
442 wy60(1), xterm(1).
443
445 The daemon uses privilege separation techniques to allow it to drop
446 privileges early. It is aware of setuid flags and restricts some opera‐
447 tions when launched as a setuid application.
448 Despite these safety features, a bug could conceivably lead to a deter‐
450 mined attacker gaining elevated privileges. It is therefore strongly
451 discouraged to set the setuid flag on the binary.
452 The expected deployment would be from a system rc script launched by
454 /sbin/init. For extra security, the --group and --user options should
455 be used to change to a dedicated user.
456
458 Copyright (C) 2008-2010 by Markus Gutschke <markus@shellinabox.com>.
459 This program is free software; you can redistribute it and/or modify it
461 under the terms of the GNU General Public License version 2 as pub‐
462 lished by the Free Software Foundation.
463 This program is distributed in the hope that it will be useful, but
465 WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
466 CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
467 Public License for more details.
468 You should have received a copy of the GNU General Public License along
470 with this program; if not, write to the Free Software Foundation, Inc.,
471 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
472 In addition to these license terms, the author grants the following
474 additional rights:
475 If you modify this program, or any covered work, by linking or combin‐
477 ing it with the OpenSSL project's OpenSSL library (or a modified ver‐
478 sion of that library), containing parts covered by the terms of the
479 OpenSSL or SSLeay licenses, the author grants you additional permission
480 to convey the resulting work. Corresponding Source for a non-source
481 form of such a combination shall include the source code for the parts
482 of OpenSSL used as well as that of the covered work.
483 You may at your option choose to remove this additional permission from
485 the work, or from any part of it.
486 If you would like to negotiate different licensing terms that are com‐
488 patible for integration with other projects, please contact the author.
489 If the OpenSSL system libraries can be found at run-time, they will be
491 invoked by shellinaboxd to provide SSL/TLS support. The OpenSSL and
492 SSLeay licenses require the following notices:
493 This product includes software developed by the OpenSSL Project for use
495 in the OpenSSL Toolkit. (http://www.openssl.org/)
496 This product includes cryptographic software written by Eric Young
498 (eay@cryptsoft.com)
499
501 Due to browser limitations, some features might not be available to
502 users of all browers.
503 Konqueror does not allow for reliable interception of CTRL keys. If you
505 press a key together with the CTRL modifier, it continues performing
506 the browser's predefined behavior for this particular key combination.
507 In most cases, it also fails to report the correct key to the terminal
508 emulator. As a work-around, pressing both the CTRL and the WINDOWS key
509 sometimes works.
510 Some browsers, most notably IE on Windows, disallow interception of ALT
512 keys and always interpret these keys as menu accelerators. As a work-
513 around, many UNIX applications allow pressing ESC, instead of ALT.
514 When using non-US keyboard layouts, some browser do not allow for reli‐
516 ably determining shifted ALT keys. Please report these cases if they
517 turn out to be a problem, as work-arounds might be possible.
518 Access to the native clipboard is typically not possible. Instead, an
520 internal clipboard accessible from the right-button context menu is
521 used for all but IE.
522 Some browsers restrict the number of concurrent connections to a
524 server. This restricts how many AJAX terminals can be opened simultane‐
525 ously. If this becomes a problem, users can typically reconfigure their
526 browsers to raise the limit.
527 There have been reports of the VLC plugin on Linux/x86_64 crashing
529 Firefox when the browser page gets reloaded. Setting the --no-beep
530 option eliminates all references to VLC and thus appears to work around
531 this crash.
532 Sep 11, 2010 SHELLINABOXD(1)