1SHELLINABOXD(1)             General Commands Manual            SHELLINABOXD(1)
2
3
4

NAME

6       shellinaboxd - publish command line shell through AJAX interface
7

SYNOPSIS

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

DESCRIPTION

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
27       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
31       Any  modern  JavaScript  and CSS enabled browser will be able to access
32       the published service without requiring additional plugins.
33

OPTIONS

35       The following command line parameters control the operation of the dae‐
36       mon:
37
38       -b | --background[=pidfile]
39            Launch  shellinaboxd  as  a background daemon process. Optionally,
40            write the process id to pidfile.
41
42       -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
47            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
52            If  no  SNI  handshake took place, it falls back on using the cer‐
53            tificate in the certificate.pem file.
54
55            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
59            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
64            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
71       --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
78       --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
86       --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
94            The --cgi option is  mutually  exclusive  with  the  --background,
95            --pidfile and --port options.
96
97            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
101       -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
106       -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
115            The following resources are available for customization:
116
117            beep.wav         audio sample that gets played whenever the termi‐
118                             nal BEL is sounded.
119
120            favicon.ico      favicon image  file  that  is  displayed  in  the
121                             browser's navigation bar.
122
123            ShellInABox.js   JavaScript  file  implementing  the AJAX terminal
124                             emulator.
125
126            styles.css       CSS style file that controls the  visual  appear‐
127                             ance of the terminal.
128
129            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
133            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
137            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
142       -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
147            When already running as an unprivileged user,  group  changes  are
148            not possible.
149
150            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
154       -h | --help
155            Display  a  brief  usage  message  showing  the valid command line
156            parameters.
157
158       --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
167       --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
173       --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
179       -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
185       --pidfile=pidfile
186            The  shellinaboxd  daemon  can  be configured to store its process
187            identifier in pidfile.
188
189       -p | --port=port
190            Unless overridden by this option, the web server listens  on  port
191            4200 for incoming HTTP and HTTPS requests.
192
193            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
198       -s | --service=service
199            One or more services can be registered on different URL paths:
200                SERVICE := <url-path> ':' APPLICATION
201
202            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
208            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
214            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
219                USER := <username> ':' <groupname>
220
221            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
225            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
230            The  <cmdline> supports expansion of variables of the form ${VAR}.
231            Supported variables are:
232
233            ${columns}  number of columns.
234
235            ${gid}      numeric group id.
236
237            ${group}    group name.
238
239            ${home}     home directory.
240
241            ${lines}    number of rows.
242
243            ${peer}     name of remote peer.
244
245            ${realip}   value of HTTP header field 'X-Real-IP'.
246
247            ${uid}      numeric user id.
248
249            ${url}      the URL that serves the terminal session.
250
251            ${user}     user name.
252
253            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
259            The <cmdline> supports single and double quotes, as well as  back‐
260            slashes for escaping characters in the familiar fashion.
261
262            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
266            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
272            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
277
278       -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
284            This  option  is  also  useful during testing or for deployment in
285            trusted intranets, if SSL certificates are unavailable.
286
287       --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
293       -q | --quiet
294            Suppresses all messages to stderr.  This option is mutually exclu‐
295            sive with --debug and --verbose.
296
297       -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
301            For more details, refer to the description of the --group option.
302
303       --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
309            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
314            Multiple independent groups are separated by semicolons:
315                STYLES := GROUP { ';' GROUP }*
316
317            The members of a group are separated by commas:
318                GROUP := OPTION { ',' OPTION }*
319
320            Groups  with  exactly  one member are used for options that can be
321            independently turned on and off.
322
323            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
330            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
336       -v | --verbose
337            Enables logging of Apache-style log file to stderr.   This  option
338            is mutually exclusive with --debug and --quiet.
339
340       --version
341            Prints the version number of the binary and exits.
342

CONFIGURATION

344       There  are  no  configuration files or permanent settings for shellina‐
345       boxd.
346
347       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
351       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
361       If  you  are using a different web server, refer to that server's docu‐
362       mentation on how to configure reverse proxy operations.
363
364       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

EXAMPLES

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
378       shellinaboxd -t
379                    Attaches   a  web-enabled  login  shell  to  http://local
380                    host:4200/ with SSL/TLS support disabled.
381
382       shellinaboxd -t -f beep.wav:/dev/null
383                    Runs all services with the audible-bell  permanently  dis‐
384                    abled.
385
386       shellinaboxd -s /:SSH:example.org
387                    The terminal connects to a ssh session on example.org.
388
389       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
395       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
404       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
411       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
416       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
422       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

DIAGNOSTICS

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
435       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

SEE ALSO

441       chmod(1),  last(1),  login(1),  sh(1),  shells(5), openssl(1SSL), w(1),
442       wy60(1), xterm(1).
443

SECURITY

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
449       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
453       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

AUTHOR

458       Copyright (C) 2008-2010 by Markus Gutschke <markus@shellinabox.com>.
459
460       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
464       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
469       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
473       In  addition  to  these  license terms, the author grants the following
474       additional rights:
475
476       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
484       You may at your option choose to remove this additional permission from
485       the work, or from any part of it.
486
487       If  you would like to negotiate different licensing terms that are com‐
488       patible for integration with other projects, please contact the author.
489
490       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
494       This product includes software developed by the OpenSSL Project for use
495       in the OpenSSL Toolkit. (http://www.openssl.org/)
496
497       This  product  includes  cryptographic  software  written by Eric Young
498       (eay@cryptsoft.com)
499

BUGS

501       Due to browser limitations, some features might  not  be  available  to
502       users of all browers.
503
504       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
511       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
515       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
519       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
523       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
528       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
533
534
535                                 Sep 11, 2010                  SHELLINABOXD(1)
Impressum